Enhance DocumentAssembler image handling with sizing, alignment, fallbacks, and comprehensive tests

.gitignore

@@ -41,4 +41,5 @@ TestResults/
 .idea/
 _ReSharper.Caches/
 
-TestResult/
+TestResult/
+ExampleOutput*

DOCUMENT_ASSEMBLER.md

@@ -0,0 +1,78 @@
+# OpenXmlPowerTools
+
+OpenXmlPowerTools provides guidance and example code for programming with Open XML Documents (DOCX, XLSX, and PPTX). It is based on, and extends the functionality of the Open XML SDK.
+
+## Document Assembler
+
+The `DocumentAssembler` module is a powerful tool for generating documents from templates and data. It allows you to create `.docx` files with dynamic content, such as tables, conditional sections, and repeating elements, based on data from an XML file.
+
+### Key Features
+
+*   **Template-Based Document Generation**: Create documents from Word templates (`.docx`) and populate them with data from XML files.
+*   **Content Replacement**: Use simple placeholders in your template to insert data from your XML file.
+*   **Dynamic Tables**: Automatically generate tables in your document based on data from your XML file.
+*   **Conditional Content**: Include or exclude parts of your document based on conditions in your data.
+*   **Repeating Content**: Repeat sections of your document for each item in a collection in your data.
+*   **Error Handling**: The `DocumentAssembler` will report errors in the generated document if it encounters any issues with your template or data.
+
+### How it Works
+
+The `DocumentAssembler` works by processing a Word document that contains special markup in content controls or in paragraphs. This markup defines how the document should be assembled based on the provided XML data.
+
+The process is as follows:
+
+1.  **Create a Template**: Start with a regular Word document (`.docx`).
+2.  **Add Placeholders**: Use content controls or special syntax in paragraphs to define placeholders for your data.
+3.  **Provide Data**: Create an XML file that contains the data you want to insert into the document.
+4.  **Assemble the Document**: Use the `DocumentAssembler.AssembleDocument` method to merge the template and data, producing a new Word document.
+
+### Template Syntax
+
+The template syntax uses XML elements within content controls or as text in the format `<#ElementName ... #>`.
+
+#### Content Replacement
+
+To replace a placeholder with a value from your XML data, you can use the `Content` element. The `Select` attribute contains an XPath expression to select the data from the XML file.
+
+**Example:**
+
+`<#Content Select="Customer/Name" #>`
+
+#### Tables
+
+To generate a table, you use the `Table` element. The `Select` attribute specifies the collection of data to iterate over. The table in the template must have a prototype row, which will be repeated for each item in the data.
+
+**Example:**
+
+`<#Table Select="Customers/Customer" #>`
+
+#### Conditional Content
+
+You can conditionally include content using the `Conditional` element. The `Select` attribute specifies the data to test, and the `Match` or `NotMatch` attribute specifies the value to compare against.
+
+**Example:**
+
+`<#Conditional Select="Customer/Country" Match="USA" #>
+... content to include if the customer is from the USA ...
+<#EndConditional #>`
+
+#### Repeating Content
+
+To repeat a section of the document, you can use the `Repeat` element. The `Select` attribute specifies the collection of data to iterate over.
+
+**Example:**
+
+`<#Repeat Select="Customers/Customer" #>
+... content to repeat for each customer ...
+<#EndRepeat #>`
+
+### Getting Started
+
+To use the `DocumentAssembler`, you will need to:
+
+1.  Add a reference to the `OpenXmlPowerTools` library in your project.
+2.  Create a Word template with the appropriate placeholders.
+3.  Create an XML data file.
+4.  Call the `DocumentAssembler.AssembleDocument` method to generate your document.
+
+For more detailed examples and documentation, please refer to the `DocumentAssembler`, `DocumentAssembler01`, `DocumentAssembler02`, and `DocumentAssembler03` projects in the `OpenXmlPowerToolsExamples` directory.

OpenXmlPowerTools.sln

@@ -78,6 +78,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MarkupSimplifierApp", "OpenXmlPowerToolsExamples\MarkupSimplifierApp\MarkupSimplifierApp.csproj", "{6731E031-9C81-48FB-97A7-0E945993BCE2}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "OpenXmlPowerToolsExamples", "OpenXmlPowerToolsExamples", "{AA7E2DBC-70B3-4F8A-AC47-4416CDA9F3DA}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocumentAssembler04", "OpenXmlPowerToolsExamples\DocumentAssembler04\DocumentAssembler04.csproj", "{94E64B7D-BB4A-4478-B3BF-69F83C2FD379}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -208,6 +212,10 @@ Global
 		{6731E031-9C81-48FB-97A7-0E945993BCE2}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{6731E031-9C81-48FB-97A7-0E945993BCE2}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{6731E031-9C81-48FB-97A7-0E945993BCE2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{94E64B7D-BB4A-4478-B3BF-69F83C2FD379}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{94E64B7D-BB4A-4478-B3BF-69F83C2FD379}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{94E64B7D-BB4A-4478-B3BF-69F83C2FD379}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{94E64B7D-BB4A-4478-B3BF-69F83C2FD379}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -242,6 +250,7 @@ Global
 		{D4078011-2611-46A7-8A30-55E4AB8FA786} = {A83D6B58-6D38-46AF-8C20-5CFC170A1063}
 		{DCE8EC51-1E58-49A0-82CF-5BE269FA0A9D} = {A83D6B58-6D38-46AF-8C20-5CFC170A1063}
 		{6731E031-9C81-48FB-97A7-0E945993BCE2} = {A83D6B58-6D38-46AF-8C20-5CFC170A1063}
+		{94E64B7D-BB4A-4478-B3BF-69F83C2FD379} = {AA7E2DBC-70B3-4F8A-AC47-4416CDA9F3DA}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {E623EFF5-2CA4-4FA0-B3AB-53F921DA212E}