Publish programming-with-documents category examples (#239)

Author: agent-aspose-words-examples

programming-with-documents/AGENTS.md

@@ -604,7 +604,7 @@ Use the simplest workflow that satisfies the task.
 ## Build and run contract
 
 - Target framework: `net8.0`
-- Package: `Aspose.Words` `26.7.0`
+- Package: `Aspose.Words` `26.8.0`
 
 ## Command reference
 
@@ -618,7 +618,7 @@ cd ExampleProject
 ### Add required packages
 
 ```bash
-dotnet add package Aspose.Words --version 26.7.0
+dotnet add package Aspose.Words --version 26.8.0
 ```
 
 ### Copy a category example into the temp project

programming-with-documents/README.md

@@ -1,14 +1,14 @@
 # Programming With Documents Examples for Aspose.Words for .NET
 
-This folder contains the live, publish-ready C# examples for the Programming With Documents category. Each file is a standalone console example selected from the verified 26.7.0 run.
+This folder contains the live, publish-ready C# examples for the Programming With Documents category. Each file is a standalone console example selected from the verified 26.8.0 run.
 
 ## Snapshot
 
 - Category: Programming With Documents
 - Slug: programming-with-documents
 - Total examples: 110
 - Publish-ready successful examples: 110 / 110
-- Source run: 20260802_190455_803b68
+- Source run: 20260830_195242_46e1a9
 - Document Workflow examples: 110
 
 ## Category rules that shaped these examples
@@ -22,7 +22,7 @@ This folder contains the live, publish-ready C# examples for the Programming Wit
 ## Prerequisites
 
 - .NET SDK 8.0 or later
-- Aspose.Words 26.7.0
+- Aspose.Words 26.8.0
 
 ## Running Examples
 
@@ -31,7 +31,7 @@ Each file in this folder is a single, standalone `.cs` console example. To run o
 ```bash
 dotnet new console -n ExampleProject --framework net8.0
 cd ExampleProject
-dotnet add package Aspose.Words --version 26.7.0
+dotnet add package Aspose.Words --version 26.8.0
 
 # Copy one example from this folder into the project as Program.cs
 # PowerShell:
@@ -52,7 +52,7 @@ Example:
 # From the repository root
 dotnet new console -n ExampleProject --framework net8.0
 cd ExampleProject
-dotnet add package Aspose.Words --version 26.7.0
+dotnet add package Aspose.Words --version 26.8.0
 
 # PowerShell example
 Copy-Item ..\programming-with-documents\create-a-first-page-header-with-a-centered-logo-image-using-documentbuilder.cs .\Program.cs
@@ -204,6 +204,6 @@ dotnet run --configuration Release --no-build
 
 ## Notes for maintainers
 
-- This category is 100% publish-ready for the 26.7.0 run.
+- This category is 100% publish-ready for the 26.8.0 run.
 - Preserve file-to-task traceability when updating this folder.
 - Keep examples standalone and bootstrap local inputs inside the example whenever external sources are mentioned.

programming-with-documents/add-a-caption-below-the-table-using-a-paragraph-styled-as-caption-and-reference-it.cs

@@ -1,5 +1,4 @@
 using System;
-using System.IO;
 using Aspose.Words;
 using Aspose.Words.Tables;
 
@@ -11,41 +10,36 @@ public static void Main()
         Document doc = new Document();
         DocumentBuilder builder = new DocumentBuilder(doc);
 
-        // Insert a bookmark that will surround the table so we can reference it later.
-        builder.StartBookmark("MyTable");
-
         // Build a simple 2x2 table.
-        Table table = builder.StartTable();
+        builder.StartTable();
         builder.InsertCell();
-        builder.Write("Cell 1,1");
+        builder.Write("Cell 1");
         builder.InsertCell();
-        builder.Write("Cell 1,2");
+        builder.Write("Cell 2");
         builder.EndRow();
 
         builder.InsertCell();
-        builder.Write("Cell 2,1");
+        builder.Write("Cell 3");
         builder.InsertCell();
-        builder.Write("Cell 2,2");
+        builder.Write("Cell 4");
         builder.EndRow();
         builder.EndTable();
 
-        // End the bookmark after the table.
-        builder.EndBookmark("MyTable");
-
-        // Insert a caption paragraph directly below the table.
-        // Use the built‑in "Caption" style.
-        builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Caption;
+        // Insert a caption paragraph styled as "Caption" and bookmark it for referencing.
+        builder.StartBookmark("TableCaption");
+        builder.ParagraphFormat.StyleName = "Caption";
         builder.Writeln("Table 1: Sample table.");
+        builder.EndBookmark("TableCaption");
+
+        // Move cursor to the end of the document to add a reference to the caption.
+        builder.MoveToDocumentEnd();
 
-        // Add some regular text and a cross‑reference to the table.
-        builder.ParagraphFormat.ClearFormatting(); // reset to normal style
-        builder.Writeln();
-        builder.Writeln("Reference to the table above:");
-        // Insert a REF field that points to the bookmark "MyTable" and makes it a hyperlink.
-        builder.InsertField(@" REF MyTable \h ");
+        // Insert a reference field that points to the bookmarked caption.
+        builder.Write("See Table ");
+        builder.InsertField(" REF TableCaption \\h ");
+        builder.Writeln(" for details.");
 
-        // Save the document to the current directory.
-        string outputPath = Path.Combine(Directory.GetCurrentDirectory(), "TableCaption.docx");
-        doc.Save(outputPath);
+        // Save the document to the local file system.
+        doc.Save("TableCaptionReference.docx");
     }
 }

programming-with-documents/add-a-paragraph-with-a-background-shading-of-light-yellow-to-highlight-important-informati.cs

@@ -9,17 +9,17 @@ public static void Main()
         // Create a new blank document.
         Document doc = new Document();
 
-        // Attach a DocumentBuilder to the document for easy content insertion.
+        // Initialize a DocumentBuilder which will be used to add content.
         DocumentBuilder builder = new DocumentBuilder(doc);
 
-        // Set the paragraph shading to a light yellow color.
-        // This will highlight the paragraph background.
+        // Apply light yellow background shading to the current paragraph.
         builder.ParagraphFormat.Shading.BackgroundPatternColor = Color.LightYellow;
 
         // Write the highlighted paragraph.
-        builder.Writeln("This is an important paragraph highlighted with a light yellow background.");
+        builder.Writeln("Important information highlighted with light yellow shading.");
 
         // Save the document to the local file system.
-        doc.Save("HighlightedParagraph.docx");
+        string outputPath = "HighlightedParagraph.docx";
+        doc.Save(outputPath);
     }
 }

programming-with-documents/add-a-paragraph-with-a-custom-field-that-displays-the-document-s-author-name-dynamically.cs

@@ -10,20 +10,21 @@ public static void Main()
         // Create a new blank document.
         Document doc = new Document();
 
-        // Set the built‑in Author property – the AUTHOR field will read this value.
+        // Set the built‑in Author property (optional, otherwise the default author will be used).
         doc.BuiltInDocumentProperties.Author = "John Doe";
 
-        // Initialize a DocumentBuilder to add content.
+        // Initialize a DocumentBuilder for the document.
         DocumentBuilder builder = new DocumentBuilder(doc);
 
         // Add a paragraph that introduces the author field.
         builder.Writeln("Document author:");
 
-        // Insert an AUTHOR field and update it so the result reflects the Author property.
+        // Insert an AUTHOR field that displays the document's author dynamically.
         FieldAuthor authorField = (FieldAuthor)builder.InsertField(FieldType.FieldAuthor, true);
+        // Update the field to reflect the current Author property.
         authorField.Update();
 
-        // Save the document to the current working directory.
+        // Save the document to the current directory.
         string outputPath = Path.Combine(Directory.GetCurrentDirectory(), "AuthorField.docx");
         doc.Save(outputPath);
     }

programming-with-documents/add-a-paragraph-with-a-drop-cap-character-and-specify-the-number-of-lines-it-spans.cs

@@ -2,26 +2,36 @@
 using System.IO;
 using Aspose.Words;
 
-public class Program
+namespace DropCapExample
 {
-    public static void Main()
+    public class Program
     {
-        // Create a new blank document.
-        Document doc = new Document();
-        DocumentBuilder builder = new DocumentBuilder(doc);
-
-        // Set the drop cap height to span 4 lines.
-        builder.ParagraphFormat.LinesToDrop = 4;
-        builder.Writeln("H"); // This paragraph becomes the drop cap.
-
-        // Reset the drop cap setting for subsequent paragraphs.
-        builder.ParagraphFormat.LinesToDrop = 0;
-        builder.Writeln("ello world!"); // Normal paragraph that wraps around the drop cap.
-
-        // Save the document to the output folder.
-        string outputDir = "Output";
-        Directory.CreateDirectory(outputDir);
-        string outputPath = Path.Combine(outputDir, "DropCapExample.docx");
-        doc.Save(outputPath);
+        public static void Main()
+        {
+            // Create a new blank document.
+            Document doc = new Document();
+
+            // Attach a DocumentBuilder to the document.
+            DocumentBuilder builder = new DocumentBuilder(doc);
+
+            // Set the number of lines the drop cap should span.
+            // This makes the next paragraph start with a large capital letter.
+            builder.ParagraphFormat.LinesToDrop = 4;
+
+            // Write the drop cap character.
+            builder.Writeln("H");
+
+            // Reset LinesToDrop to 0 so subsequent text behaves normally.
+            builder.ParagraphFormat.LinesToDrop = 0;
+
+            // Write the remaining text that will wrap around the drop cap.
+            builder.Writeln("ello world! This paragraph demonstrates a drop cap character spanning four lines.");
+
+            // Define the output path (in the same folder as the executable).
+            string outputPath = Path.Combine(Directory.GetCurrentDirectory(), "DropCapExample.docx");
+
+            // Save the document.
+            doc.Save(outputPath);
+        }
     }
 }

programming-with-documents/add-a-paragraph-with-a-hanging-indent-of-0-25-inches-for-citation-formatting.cs

@@ -9,22 +9,21 @@ public static void Main()
         // Create a new blank document.
         Document doc = new Document();
 
-        // Initialize a DocumentBuilder for the document.
+        // Attach a DocumentBuilder to the document.
         DocumentBuilder builder = new DocumentBuilder(doc);
 
-        // Set a hanging indent of 0.25 inches (18 points). Negative value creates a hanging indent.
-        builder.ParagraphFormat.FirstLineIndent = -18; // 0.25 inch = 0.25 * 72 points
+        // Set a hanging indent of 0.25 inches (18 points) for the next paragraph.
+        // Positive values create a first‑line indent, negative values create a hanging indent.
+        builder.ParagraphFormat.FirstLineIndent = -18; // 0.25 inch = 18 points
 
-        // Add a sample citation paragraph.
-        builder.Writeln("Doe, J. (2020). Example citation text with a hanging indent for formatting purposes.");
+        // Write the citation text. The paragraph will inherit the hanging indent set above.
+        builder.Writeln("“The quick brown fox jumps over the lazy dog.” – Example Citation");
 
-        // Determine the output file path.
-        string outputPath = Path.Combine(Directory.GetCurrentDirectory(), "HangingIndent.docx");
-
-        // Ensure the directory exists (in case the current directory is a root path).
-        Directory.CreateDirectory(Path.GetDirectoryName(outputPath));
+        // Ensure the output directory exists.
+        string outputFile = Path.Combine(Directory.GetCurrentDirectory(), "HangingIndent.docx");
+        Directory.CreateDirectory(Path.GetDirectoryName(outputFile));
 
         // Save the document.
-        doc.Save(outputPath);
+        doc.Save(outputFile);
     }
 }

programming-with-documents/add-a-text-box-to-a-document-header-and-ensure-it-appears-on-every-page-of-the-section.cs

@@ -11,38 +11,36 @@ public static void Main()
         Document doc = new Document();
         DocumentBuilder builder = new DocumentBuilder(doc);
 
-        // Move the builder's cursor to the primary header of the first section.
+        // Move the cursor to the primary header of the first (and only) section.
         builder.MoveToHeaderFooter(HeaderFooterType.HeaderPrimary);
 
         // Create a floating text box shape.
         Shape textBox = new Shape(doc, ShapeType.TextBox);
-        textBox.WrapType = WrapType.None;          // No text wrapping – the box stays in the header.
-        textBox.Height = 50;                       // Height in points.
-        textBox.Width = 200;                       // Width in points.
+        textBox.WrapType = WrapType.None;
+        textBox.Width = 200;
+        textBox.Height = 50;
         textBox.HorizontalAlignment = HorizontalAlignment.Center;
         textBox.VerticalAlignment = VerticalAlignment.Top;
 
-        // Add a paragraph with a run of text inside the text box.
+        // Add a paragraph with centered text inside the text box.
         textBox.AppendChild(new Paragraph(doc));
-        Paragraph para = (Paragraph)textBox.FirstParagraph;
+        Paragraph para = textBox.FirstParagraph;
         para.ParagraphFormat.Alignment = ParagraphAlignment.Center;
-        Run run = new Run(doc, "Header Text Box");
+        Run run = new Run(doc, "Header TextBox");
         para.AppendChild(run);
 
         // Insert the text box into the header.
         builder.InsertNode(textBox);
 
-        // Return the cursor to the main document body.
+        // Add some body content spanning multiple pages to demonstrate the header repeats.
         builder.MoveToSection(0);
-
-        // Add enough content to generate multiple pages.
         builder.Writeln("Page 1");
         builder.InsertBreak(BreakType.PageBreak);
         builder.Writeln("Page 2");
         builder.InsertBreak(BreakType.PageBreak);
         builder.Writeln("Page 3");
 
-        // Save the document. The text box will appear in the header on every page.
+        // Save the document.
         doc.Save("HeaderWithTextBox.docx");
     }
 }