Extract snippets

docs/general/how-to-add-a-new-document-part-to-a-package.md

@@ -40,8 +40,7 @@ The code starts with opening a package file by passing a file name to one of the
 ***
 
 
-The **using** statement provides a recommended alternative to the typical .Create, .Save, .Close sequence. It ensures that the **Dispose** method (internal method used by the Open XML SDK to clean up resources) is automatically called when the closing brace is reached. The block that follows the **using** statement establishes a scope for the object that is created or named in the **using** statement, in this case **wordDoc**. Because the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the Open XML SDK
-automatically saves and closes the object as part of its **System.IDisposable** implementation, and because the **Dispose** method is automatically called when you exit the block; you do not have to explicitly call **Save** and **Close**, as long as you use **using**.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 [!include[Structure](../includes/word/structure.md)]
 

docs/general/how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md

@@ -33,7 +33,7 @@ programmatically.
 To open an existing document, instantiate the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class as shown in
 the following two **using** statements. In the
 same statement, you open the word processing file with the specified
-file name by using the [Open](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.open) method, with the Boolean parameter.
+file name by using the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Open%2A> method, with the Boolean parameter.
 For the source file that set the parameter to **false** to open it for read-only access. For the
 target file, set the parameter to **true** in
 order to enable editing the document.
@@ -57,16 +57,7 @@ order to enable editing the document.
 ```
 ***
 
-The `using` statement provides a recommended
-alternative to the typical .Create, .Save, .Close sequence. It ensures
-that the <xref:System.IDisposable.Dispose> method (internal method
-used by the Open XML SDK to clean up resources) is automatically called
-when the closing brace is reached. The block that follows the using
-statement establishes a scope for the object that is created or named in
-the `using` statement. Because the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the Open XML SDK
-automatically saves and closes the object as part of its <xref:System.IDisposable> implementation, and because
-<xref:System.IDisposable.Dispose> is automatically called when you
-exit the block, you do not have to explicitly call <xref:DocumentFormat.OpenXml.Packaging.OpenXmlPackage.Save%2A>.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 --------------------------------------------------------------------------------
 
@@ -107,7 +98,7 @@ is stored in the ZIP item theme/theme1.xml:
 ```
 
 
-© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
+&copy; [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
 
 
 --------------------------------------------------------------------------------

docs/general/how-to-create-a-package.md

@@ -59,15 +59,7 @@ template.
 ```
 ***
 
-The **using** statement provides a recommended
-alternative to the typical .Create, .Save, .Close sequence. It ensures
-that the **Dispose** () method (internal method
-used by the Open XML SDK to clean up resources) is automatically called
-when the closing bracket is reached. The block that follows the **using** statement establishes a scope for the
-object that is created or named in the **using** statement, in this case **wordDoc**. Because the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the Open XML SDK
-automatically saves and closes the object as part of its **System.IDisposable** implementation, and because
-**Dispose** is automatically called when you exit the bracketed block, you do not have to explicitly call **Save** and **Close**─as
-long as you use **using**.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 Once you have created the Word document package, you can add parts to
 it. To add the main document part you call <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.AddMainDocumentPart%2A>. Having done that,

docs/general/how-to-get-the-contents-of-a-document-part-from-a-package.md

@@ -54,17 +54,7 @@ opened in read-only mode to avoid accidental changes.
 ```
 ***
 
-
-The **using** statement provides a recommended
-alternative to the typical .Create, .Save, .Close sequence. It ensures
-that the **Dispose** method (internal method
-used by the Open XML SDK to clean up resources) is automatically called
-when the closing brace is reached. The block that follows the **using** statement establishes a scope for the
-object that is created or named in the **using** statement, in this case **wordDoc**. Because the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the Open XML SDK
-automatically saves and closes the object as part of its **System.IDisposable** implementation, and because
-the **Dispose** method is automatically called
-when you exit the block; you do not have to explicitly call **Save** and **Close**─as
-long as you use using.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 
 ---------------------------------------------------------------------------------
@@ -95,7 +85,7 @@ document:
 The **comments** element contains the single
 comment specified by this document in this example.
 
-© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
+&copy; [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
 
 The following XML schema fragment defines the contents of this element.
 

docs/general/how-to-remove-a-document-part-from-a-package.md

@@ -54,16 +54,7 @@ should be opened in read/write mode.
 ***
 
 
-The **using** statement provides a recommended
-alternative to the typical .Create, .Save, .Close sequence. It ensures
-that the **Dispose** method (internal method
-used by the Open XML SDK to clean up resources) is automatically called
-when the closing brace is reached. The block that follows the **using** statement establishes a scope for the
-object that is created or named in the **using** statement, in this case **wordDoc**. Because the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the Open XML SDK
-automatically saves and closes the object as part of its **System.IDisposable** implementation, and because
-the **Dispose** method is automatically called
-when you exit the block; you do not have to explicitly call **Save** and **Close**─as
-long as you use **using**.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 
 ---------------------------------------------------------------------------------
@@ -94,7 +85,7 @@ introduces the settings element in a **PresentationML** package.
 > automatic tab stop increments of 0.5" using the **defaultTabStop** element, and no character level
 > white space compression using the **characterSpacingControl** element. 
 > 
-> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
+> &copy; [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
 
 
 --------------------------------------------------------------------------------

docs/general/how-to-replace-the-theme-part-in-a-word-processing-document.md

@@ -29,7 +29,7 @@ In the sample code, you start by opening the word processing file by
 instantiating the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class as shown in
 the following **using** statement. In the same
 statement, you open the word processing file *document* by using the
-[Open](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.open) method, with the Boolean parameter set
+<xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Open%2A> method, with the Boolean parameter set
 to **true** to enable editing the document.
 
 ### [C#](#tab/cs-0)
@@ -49,19 +49,7 @@ to **true** to enable editing the document.
 ```
 ***
 
-
-The **using** statement provides a recommended
-alternative to the typical .Open, .Save, .Close sequence. It ensures
-that the **Dispose** method (internal method
-used by the Open XML SDK to clean up resources) is automatically called
-when the closing brace is reached. The block that follows the **using** statement establishes a scope for the
-object that is created or named in the **using** statement, in this case *wordDoc*. Because
-the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the
-Open XML SDK automatically saves and closes the object as part of its
-**System.IDisposable** implementation, and
-because **Dispose** is automatically called
-when you exit the block, you do not have to explicitly call **Save** and **Close**─as
-long as you use **using**.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 
 ## How to Change Theme in a Word Package
@@ -97,7 +85,7 @@ In this example, we see how a theme can affect font, colors,
 backgrounds, fills, and effects for different objects in a presentation.
 *end example*]
 
-© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
+&copy; [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)]
 
 The following table lists the possible child types of the Theme class.
 

docs/general/how-to-search-and-replace-text-in-a-document-part.md

@@ -32,7 +32,7 @@ In the sample code, you start by opening the word processing file by
 instantiating the **<xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument>** class as shown in
 the following **using** statement. In the same
 statement, you open the word processing file *document* by using the
-**[Open](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.open)** method, with the Boolean parameter set
+**<xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Open%2A>** method, with the Boolean parameter set
 to **true** to enable editing the document.
 
 ### [C#](#tab/cs-0)
@@ -53,18 +53,7 @@ to **true** to enable editing the document.
 ***
 
 
-The **using** statement provides a recommended
-alternative to the typical .Open, .Save, .Close sequence. It ensures
-that the **Dispose** method (internal method
-used by the Open XML SDK to clean up resources) is automatically called
-when the closing brace is reached. The block that follows the **using** statement establishes a scope for the
-object that is created or named in the **using** statement, in this case *wordDoc*. Because
-the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the
-Open XML SDK automatically saves and closes the object as part of its
-**System.IDisposable** implementation, and
-because **Dispose** is automatically called
-when you exit the block, you do not have to explicitly call **Save** and **Close**─as
-long as you use **using**.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 
 --------------------------------------------------------------------------------

docs/includes/presentation/modern-comment-description.md

@@ -0,0 +1,68 @@
+## The Structure of the Modern Comment Element
+
+The following XML element specifies a single comment. 
+It contains the text of the comment (`t`) and attributes referring to its author
+(`authorId`), date time created (`created`), and comment id (`id`).
+
+```xml
+<p188:cm id="{62A8A96D-E5A8-4BFC-B993-A6EAE3907CAD}" authorId="{CD37207E-7903-4ED4-8AE8-017538D2DF7E}" created="2024-12-30T20:26:06.503">
+  <p188:txBody>
+      <a:bodyPr/>
+      <a:lstStyle/>
+      <a:p>
+      <a:r>
+          <a:t>Needs more cowbell</a:t>
+      </a:r>
+      </a:p>
+  </p188:txBody>
+</p188:cm>
+```
+
+The following tables list the definitions of the possible child elements and attributes
+of the `cm` (comment) element. For the complete definition see [MS-PPTX 2.16.3.3 CT_Comment](/openspecs/office_standards/ms-pptx/161bc2c9-98fc-46b7-852b-ba7ee77e2e54)
+
+
+| Attribute | Definition |
+|---|---|
+| id | Specifies the ID of a comment or a comment reply. |
+| authorId | Specifies the author ID of a comment or a comment reply. |
+| status | Specifies the status of a comment or a comment reply. |
+| created | Specifies the date time when the comment or comment reply is created. |
+| startDate | Specifies start date of the comment. |
+| dueDate | Specifies due date of the comment. |
+| assignedTo | Specifies a list of authors to whom the comment is assigned. |
+| complete | Specifies the completion percentage of the comment. |
+| title | Specifies the title for a comment. |
+
+| Child Element | Definition |
+|------------|---------------|
+| pc:sldMkLst | Specifies a content moniker that identifies the slide to which the comment is anchored. |
+| ac:deMkLst | Specifies a content moniker that identifies the drawing element to which the comment is anchored. |
+| ac:txMkLst | Specifies a content moniker that identifies the text character range to which the comment is anchored. |
+| unknownAnchor | Specifies an unknown anchor to which the comment is anchored. |
+| pos | Specifies the position of the comment, relative to the top-left corner of the first object to which the comment is anchored. |
+| replyLst | Specifies the list of replies to the comment. |
+| txBody | Specifies the text of a comment or a comment reply. |
+| extLst | Specifies a list of extensions for a comment or a comment reply. |
+
+
+
+The following XML schema example defines the members of the `cm` element in addition to the required and
+optional attributes.
+
+```xml
+ <xsd:complexType name="CT_Comment">
+   <xsd:sequence>
+     <xsd:group ref="EG_CommentAnchor" minOccurs="1" maxOccurs="1"/>
+     <xsd:element name="pos" type="a:CT_Point2D" minOccurs="0" maxOccurs="1"/>
+     <xsd:element name="replyLst" type="CT_CommentReplyList" minOccurs="0" maxOccurs="1"/>
+     <xsd:group ref="EG_CommentProperties" minOccurs="1" maxOccurs="1"/>
+   </xsd:sequence>
+   <xsd:attributeGroup ref="AG_CommentProperties"/>
+   <xsd:attribute name="startDate" type="xsd:dateTime" use="optional"/>
+   <xsd:attribute name="dueDate" type="xsd:dateTime" use="optional"/>
+   <xsd:attribute name="assignedTo" type="ST_AuthorIdList" use="optional" default=""/>
+   <xsd:attribute name="complete" type="s:ST_PositiveFixedPercentage" default="0%" use="optional"/>
+   <xsd:attribute name="title" type="xsd:string" use="optional" default=""/>
+ </xsd:complexType>
+```

docs/includes/presentation/structure.md

@@ -7,7 +7,7 @@ introduces the overall form of a **PresentationML** package.
 
 > The main part of a **PresentationML** package
 > starts with a presentation root element. That element contains a
-> presentation, which, in turn, refers to a **slide** list, a *slide master* list, a *notes
+> presentation, which, in turn, refers to a *slide* list, a *slide master* list, a *notes
 > master* list, and a *handout master* list. The slide list refers to
 > all of the slides in the presentation; the slide master list refers to
 > the entire slide masters used in the presentation; the notes master
@@ -30,8 +30,8 @@ introduces the overall form of a **PresentationML** package.
 > A **PresentationML** document is not stored
 > as one large body in a single part. Instead, the elements that
 > implement certain groupings of functionality are stored in separate
-> parts. For example, all comments in a document are stored in one
-> comment part while each slide has its own part.
+> parts. For example, all authors in a document are stored in one
+> authors part while each slide has its own part.
 > 
 > [!include[ISO/IEC 29500 version](../iso-iec-29500-version.md)]
 
@@ -65,13 +65,13 @@ two slides denoted by the IDs 267 and 256.
 
 Using the Open XML SDK, you can create document structure and
 content using strongly-typed classes that correspond to PresentationML
-elements. You can find these classes in the [DocumentFormat.OpenXml.Presentation](/dotnet/api/documentformat.openxml.presentation)
+elements. You can find these classes in the <a href="xref:DocumentFormat.OpenXml.Presentation?displayName=fullName" />
 namespace. The following table lists the class names of the classes that
 correspond to the **sld**, **sldLayout**, **sldMaster**, and **notesMaster** elements.
 
 | PresentationML Element | Open XML SDK Class | Description |
 |---|---|---|
-| sld | [Slide](/dotnet/api/documentformat.openxml.presentation.slide) | Presentation Slide. It is the root element of SlidePart. |
-| sldLayout | [SlideLayout](/dotnet/api/documentformat.openxml.presentation.slidelayout) | Slide Layout. It is the root element of SlideLayoutPart. |
-| sldMaster | [SlideMaster](/dotnet/api/documentformat.openxml.presentation.slidemaster) | Slide Master. It is the root element of SlideMasterPart. |
-| notesMaster | [NotesMaster](/dotnet/api/documentformat.openxml.presentation.notesmaster) | Notes Master (or handoutMaster). It is the root element of NotesMasterPart. |
+| sld | <xref:DocumentFormat.OpenXml.Presentation.Slide> | Presentation Slide. It is the root element of SlidePart. |
+| sldLayout | <xref:DocumentFormat.OpenXml.Presentation.SlideLayout> | Slide Layout. It is the root element of SlideLayoutPart. |
+| sldMaster | <xref:DocumentFormat.OpenXml.Presentation.SlideMaster> | Slide Master. It is the root element of SlideMasterPart. |
+| notesMaster | <xref:DocumentFormat.OpenXml.Presentation.NotesMaster> | Notes Master (or handoutMaster). It is the root element of NotesMasterPart. |

docs/includes/presentation/using-statement.md

@@ -0,0 +1,5 @@
+With v3.0.0+ the <xref:DocumentFormat.OpenXml.Packaging.OpenXmlPackage.Close> method has been removed and
+the `using` statement provides the recommended replacement for the deprecated `.Create`, `.Save`, `.Close` sequence. 
+It ensures that the <xref:System.IDisposable.Dispose> method is automatically called
+when the closing brace is reached. The block that follows the `using` statement establishes a scope for the
+object that is created or named in the `using` statement, in this case 

docs/includes/word/using-statement.md

@@ -0,0 +1,11 @@
+With v3.0.0+ the <xref:DocumentFormat.OpenXml.Packaging.OpenXmlPackage.Close> method has been removed and
+the `using` statement provides the recommended replacement for the deprecated `.Create`, `.Save`, `.Close` sequence. 
+It ensures that the <xref:System.IDisposable.Dispose> method (internal method
+used by the Open XML SDK to clean up resources) is automatically called
+when the closing brace is reached. The block that follows the using
+statement establishes a scope for the object that is created or named in
+the using statement. Because the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class in the Open XML SDK
+automatically saves and closes the object as part of its <xref:System.IDisposable> implementation, and because
+<xref:System.IDisposable.Dispose> is automatically called when you
+exit the block, you do not have to explicitly call <xref:DocumentFormat.OpenXml.Packaging.OpenXmlPackage.Save> and
+<xref:DocumentFormat.OpenXml.Packaging.OpenXmlPackage.Dispose> as long as you use `using`.