Use xref (#308)

Author: twsouthwick

.openpublishing.publish.config.json

@@ -6,13 +6,42 @@
       "build_output_subfolder": "open-xml-docs",
       "locale": "en-us",
       "monikers": [],
-      "moniker_ranges": [],
+      "moniker_ranges": [
+        "openxml-2.7.1",
+        "openxml-2.7.2",
+        "openxml-2.8.0",
+        "openxml-2.8.1",
+        "openxml-2.9.0",
+        "openxml-2.9.1",
+        "openxml-2.10.0",
+        "openxml-2.10.1",
+        "openxml-2.11.0",
+        "openxml-2.11.1",
+        "openxml-2.11.2",
+        "openxml-2.11.3",
+        "openxml-2.12.0",
+        "openxml-2.12.1",
+        "openxml-2.12.2",
+        "openxml-2.12.3",
+        "openxml-2.13.0",
+        "openxml-2.13.1",
+        "openxml-2.14.0",
+        "openxml-2.15.0",
+        "openxml-2.16.0",
+        "openxml-2.17.1",
+        "openxml-2.18.0",
+        "openxml-2.19.0",
+        "openxml-2.20.0",
+        "openxml-3.0.0",
+        "openxml-3.0.1"
+      ],
       "open_to_public_contributors": true,
       "customized_tasks": {
         "docset_prebuild": [
           "_dependentPackages/CommonPlugins/tools/JoinTOC.ps1"
         ]
       },
+      "xref_query_tags": [ "/dotnet" ],
       "type_mapping": {
         "Conceptual": "Content",
         "ManagedReference": "Content",

docs/general/features.md

@@ -38,20 +38,21 @@ private sealed class PrivateFeature
 {
 }
 ```
+
 > [!NOTE]
 > The feature collection on elements is readonly. This is due to memory issues if it is made writeable. If this is needed, please engage on https://github.com/dotnet/open-xml-sdk to let us know your scenario.
 
 ## Visualizing Registered Features
 
-The in-box implementations of the `IFeatureCollection` provide a helpful debug view so you can see what features are available and what their properties/fields are:
+The in-box implementations of the <xref:DocumentFormat.OpenXml.Features.IFeatureCollection> provide a helpful debug view so you can see what features are available and what their properties/fields are:
 
 ![Features Debug View](../media/feature-debug-view.png)
 
 ## Available Features
 
 The features that are currently available are described below and at what scope they are available:
 
-### IDisposableFeature
+### <xref:DocumentFormat.OpenXml.Features.IDisposableFeature>
 
 This feature allows for registering actions that need to run when a package or a part is destroyed or disposed:
 
@@ -65,7 +66,7 @@ part.Features.Get<IDisposableFeature>().Register(() => /* Some action that is ca
 
 Packages and parts will have their own implementations of this feature. Elements will retrieve the feature for their containing part if available.
 
-### IPackageEventsFeature
+### <xref:DocumentFormat.OpenXml.Features.IPackageEventsFeature>
 
 This feature allows getting event notifications of when a package is changed:
 
@@ -79,7 +80,7 @@ var feature = package.Features.GetRequired<IPackageEventsFeature>();
 > [!NOTE]
 > There may be times when the package is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
 
-### IPartEventsFeature
+### <xref:DocumentFormat.OpenXml.Features.IPartEventsFeature>
 
 This feature allows getting event notifications of when an event is being created. This is a feature that is added to the part or package:
 
@@ -95,7 +96,7 @@ Generally, assume that there may be a singleton implementation for the events an
 > [!NOTE]
 > There may be times when the part is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
 
-### IPartRootEventsFeature
+### <xref:DocumentFormat.OpenXml.Features.IPartRootEventsFeature>
 
 This feature allows getting event notifications of when a part root is being modified/loaded/created/etc. This is a feature that is added to the part level feature:
 
@@ -111,11 +112,11 @@ Generally, assume that there may be a singleton implementation for the events an
 > [!NOTE]
 > There may be times when the part root is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
 
-### IRandomNumberGeneratorFeature
+### <xref:DocumentFormat.OpenXml.Features.IRandomNumberGeneratorFeature>
 
 This feature allows for a shared service to generate random numbers and fill an array.
 
-### IParagraphIdGeneratorFeature
+### <xref:DocumentFormat.OpenXml.Features.IParagraphIdGeneratorFeature>
 
 This feature allows for population and tracking of elements that contain paragraph ids. By default, this will ensure uniqueness of values and ensure that values that do exist are valid per the constraints of the standard. To use this feature:
 
@@ -159,21 +160,3 @@ body2.AddChild(p2);
 Assert.NotEqual(p1.ParagraphId, p2.ParagraphId);
 Assert.Equal(2, shared.Count);
 ```
-
-### IPartRootXElementFeature
-
-This feature allows operating on an `OpenXmlPart` by using XLinq features and directly manipulating `XElement` nodes.
-
-```csharp
-OpenXmlPart part = GetSomePart();
-
-var node = new(W.document, new XAttribute(XNamespace.Xmlns + "w", W.w),
-    new XElement(W.body,
-        new XElement(W.p,
-            new XElement(W.r,
-                new XElement(W.t, "Hello World!")))));
-
-part.SetXElement(node);
-```
-
-This `XElement` is cached but will be kept in sync with the underlying part if it were to change.

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

@@ -21,7 +21,7 @@ This topic shows how to use the classes in the Open XML SDK for Office to add a
 
 ## Get a WordprocessingDocument object
 
-The code starts with opening a package file by passing a file name to one of the overloaded **[Open()](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.open)** methods of the **[DocumentFormat.OpenXml.Packaging.WordprocessingDocument](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument)** that takes a string and a Boolean value that specifies whether the file should be opened for editing or for read-only access. In this case, the Boolean value is **true** specifying that the file should be opened in read/write mode.
+The code starts with opening a package file by passing a file name to one of the overloaded <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Open%2A> methods of the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> that takes a string and a Boolean value that specifies whether the file should be opened for editing or for read-only access. In this case, the Boolean value is `true` specifying that the file should be opened in read/write mode.
 
 ### [C#](#tab/cs-0)
 ```csharp
@@ -40,14 +40,14 @@ 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 **WordprocessingDocument** class in the Open XML SDK
+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[Structure](../includes/word/structure.md)]
 
 ## How the sample code works
 
-After opening the document for editing, in the **using** statement, as a **WordprocessingDocument** object, the code creates a reference to the **MainDocumentPart** part and adds a new custom XML part. It then reads the contents of the external
+After opening the document for editing, in the **using** statement, as a <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> object, the code creates a reference to the **MainDocumentPart** part and adds a new custom XML part. It then reads the contents of the external
 file that contains the custom XML and writes it to the **CustomXmlPart** part.
 
 > [!NOTE]

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

@@ -30,7 +30,7 @@ programmatically.
 
 --------------------------------------------------------------------------------
 ## Getting a WordprocessingDocument Object
-To open an existing document, instantiate the [WordprocessingDocument](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument) class as shown in
+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.
@@ -57,19 +57,16 @@ order to enable editing the document.
 ```
 ***
 
-
-The **using** statement provides a recommended
+The `using` statement provides a recommended
 alternative to the typical .Create, .Save, .Close sequence. It ensures
-that the **Dispose** method (internal method
+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 **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**.
-
+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>.
 
 --------------------------------------------------------------------------------
 
@@ -117,9 +114,9 @@ is stored in the ZIP item theme/theme1.xml:
 ## How the Sample Code Works
 To copy the contents of a document part in an Open XML package to a
 document part in a different package, the full path of the each word
-processing document is passed in as a parameter to the **CopyThemeContent** method. The code then opens both
-documents as **WordprocessingDocument**
-objects, and creates variables that reference the **ThemePart** parts in each of the packages.
+processing document is passed in as a parameter to the `CopyThemeContent` method. The code then opens both
+documents as <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument>
+objects, and creates variables that reference the <xref:DocumentFormat.OpenXml.Packaging.ThemePart> parts in each of the packages.
 
 ### [C#](#tab/cs-1)
 ```csharp
@@ -144,8 +141,8 @@ objects, and creates variables that reference the **ThemePart** parts in each of
 ***
 
 
-The code then reads the contents of the source **ThemePart** part by using a **StreamReader** object and writes to the target
-**ThemePart** part by using a **StreamWriter** object.
+The code then reads the contents of the source <xref:DocumentFormat.OpenXml.Packaging.ThemePart>  part by using a **StreamReader** object and writes to the target
+<xref:DocumentFormat.OpenXml.Packaging.ThemePart> part by using a <xref:System.IO.StreamWriter>.
 
 ### [C#](#tab/cs-2)
 ```csharp
@@ -170,7 +167,7 @@ The code then reads the contents of the source **ThemePart** part by using a **S
 --------------------------------------------------------------------------------
 ## Sample Code
 The following code copies the contents of one document part in an Open
-XML package to a document part in a different package. To call the **CopyThemeContent** method, you can use the
+XML package to a document part in a different package. To call the `CopyThemeContent`` method, you can use the
 following example, which copies the theme part from "MyPkg4.docx" to
 "MyPkg3.docx."
 
@@ -207,9 +204,4 @@ Following is the complete sample code in both C\# and Visual Basic.
 --------------------------------------------------------------------------------
 ## See also
 
-
 - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk)
-
-
-
-

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

@@ -23,29 +23,25 @@ from content in the form of **WordprocessingML** XML markup.
 
 [!include[Structure](../includes/word/packages-and-document-parts.md)]
 
-
 ## Getting a WordprocessingDocument Object
 
-In the Open XML SDK, the [WordprocessingDocument](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument) class represents a Word document package. To create a Word document, you create an instance
-of the **WordprocessingDocument** class and
+In the Open XML SDK, the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class represents a Word document package. To create a Word document, you create an instance
+of the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class and
 populate it with parts. At a minimum, the document must have a main
 document part that serves as a container for the main text of the
 document. The text is represented in the package as XML using **WordprocessingML** markup.
 
-To create the class instance you call the [Create(String, WordprocessingDocumentType)](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.create)
-method. Several **Create** methods are
-provided, each with a different signature. The sample code in this topic
-uses the **Create** method with a signature
-that requires two parameters. The first parameter takes a full path
+To create the class instance you call <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Create(System.String,DocumentFormat.OpenXml.WordprocessingDocumentType)>. Several <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Create%2A> methods are
+provided, each with a different signature. The first parameter takes a full path
 string that represents the document that you want to create. The second
-parameter is a member of the [WordprocessingDocumentType](/dotnet/api/documentformat.openxml.wordprocessingdocumenttype) enumeration.
+parameter is a member of the <xref:DocumentFormat.OpenXml.WordprocessingDocumentType> enumeration.
 This parameter represents the type of document. For example, there is a
-different member of the [WordProcessingDocumentType](/dotnet/api/documentformat.openxml.wordprocessingdocumenttype) enumeration for each
+different member of the <xref:DocumentFormat.OpenXml.WordprocessingDocumentType> enumeration for each
 of document, template, and the macro enabled variety of document and
 template.
 
 > [!NOTE]
-> Carefully select the appropriate **WordProcessingDocumentType** and verify that the persisted file has the correct, matching file extension. If the **WordProcessingDocumentType** does not match the file extension, an error occurs when you open the file in Microsoft Word. The code that calls the **Create** method is part of a **using** statement followed by a bracketed block, as shown in the following code example.
+> Carefully select the appropriate <xref:DocumentFormat.OpenXml.WordprocessingDocumentType> and verify that the persisted file has the correct, matching file extension. If the <xref:DocumentFormat.OpenXml.WordprocessingDocumentType> does not match the file extension, an error occurs when you open the file in Microsoft Word.
 
 ### [C#](#tab/cs-0)
 ```csharp
@@ -63,19 +59,18 @@ 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 **WordprocessingDocument** class in the Open XML SDK
+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**.
 
 Once you have created the Word document package, you can add parts to
-it. To add the main document part you call the [AddMainDocumentPart()](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.addmaindocumentpart) method of the **WordprocessingDocument** class. Having done that,
+it. To add the main document part you call <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.AddMainDocumentPart%2A>. Having done that,
 you can set about adding the document structure and text.
 
 [!include[Structure](../includes/word/structure.md)]
@@ -99,7 +94,6 @@ call:
 ```
 ***
 
-
 After you run the program, open the created file "myPkg4.docx" and
 examine its content; it should be one paragraph that contains the phrase
 "Hello world!"
@@ -114,9 +108,4 @@ Following is the complete sample code in both C\# and Visual Basic.
 
 ## See also
 
-
-
 - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk)
-
-
-

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

@@ -30,7 +30,7 @@ document programmatically.
 ## Getting a WordprocessingDocument Object
 The code starts with opening a package file by passing a file name to
 one of the overloaded [Open()](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.open) methods (Visual Basic .NET Shared
-method or C\# static method) of the [WordprocessingDocument](/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument) class that takes a
+method or C\# static method) of the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> class that takes a
 string and a Boolean value that specifies whether the file should be
 opened in read/write mode or not. In this case, the Boolean value is
 **false** specifying that the file should be
@@ -60,7 +60,7 @@ 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 **WordprocessingDocument** class in the Open XML SDK
+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