PRR fixes

Author: Chris Cho

source/style-guide/markup/directives/sharedinclude.txt

@@ -4,21 +4,26 @@
 Shared Include
 ==============
 
-The ``sharedinclude`` directive allows you to source content from a file
-located in the MongoDB internal `docs-shared <https://github.com/10gen/docs-shared>`__
+The ``sharedinclude`` directive lets you source content from a file located in
+the MongoDB internal `docs-shared <https://github.com/10gen/docs-shared>`__
 repository. Use this directive when you need to keep the same content in sync
 for multiple sets of documentation or multiple branches of a documentation set.
 
 This page uses the following terms:
 
-- **External file**: content committed to the ``docs-shared`` repository
-  that can be sourced by other documentation repositories.
-- **Sourcing file**: content in a documentation repository that uses a
-  ``sharedinclude`` directive to pull content from an external file.
-- **Placeholder**: a variable that indicates text that the sourcing file
-  must provide a replacement for. These are located in external files and are
-  represented by the placeholder name surrounded by the ``|`` (pipe)
-  character.
+External file
+  Content committed to the ``docs-shared`` repository that other documentation
+  repositories can source.
+
+Sourcing file
+  Content in a documentation repository that uses a ``sharedinclude``
+  directive to pull content from an external file.
+
+Placeholder
+  A variable that indicates text that the sourcing file must provide a
+  replacement for. These variables are represented by the placeholder name
+  surrounded by the ``|`` (pipe) character. The variables are used in
+  external files.
 
 .. tip::
 
@@ -33,14 +38,14 @@ This page uses the following terms:
 Setup
 -----
 
-You must add the URL from which to source the shared content in the
-``sharedinclude_root`` setting of the documentation repository's ``snooty.toml``
-configuration file. This should reference the unprocessed versions of the files,
-currently served from the ``raw.githubusercontent.com`` domain.
+You must ensure the ``sharedinclude_root`` setting in the documentation
+repository's ``snooty.toml`` configuration file is set to the shared
+content repository URL. This URL must point to the unprocessed version of the
+files, currently served from the ``raw.githubusercontent.com`` domain.
 
-If the shared content that your docs repository file references is on the
-``main`` branch of ``docs-snooty``, your ``snooty.toml`` configuration entry
-should resemble the following line:
+For example, if the external files that your docs repository file references
+is on the ``main`` branch of ``docs-shared``, your docs repository
+``snooty.toml`` configuration entry should resemble the following line:
 
 .. code-block::
 
@@ -54,11 +59,11 @@ Syntax
 ------
 
 To include content from an external file, add the ``sharedinclude`` directive
-to the sourcing file. Specify the path of external file relative to the
+to the sourcing file. Specify the path of the external file relative to the
 ``docs-shared`` base directory, omitting the leading slash.
 
 For example, if the file path from the root of the ``docs-shared`` repository
-is ``drivers/compatibility-tables/c.rst``, the rST in the sourcing file
+is ``drivers/compatibility-tables/c.rst``, the {+rst-abbrev+} in the sourcing file
 should include the following code:
 
 .. code-block:: rst
@@ -112,17 +117,21 @@ Placeholders in Inline Context
 ``````````````````````````````
 
 An **inline context** describes the positioning of placeholders as adjacent to
-other paragraph text. You can only replace variable placeholders in an inline
-context with values that contain markup elements which includes any of the
-following types:
+other paragraph text. If the placeholder is in an inline context, you can
+replace it with markup elements including the following types:
 
 - Unformatted text
 - Formatted text such as ``monospace``, **emphasis**, or *italic*
 - Links
 
+You cannot replace variable placeholders in inline contexts with elements
+such as lists, code blocks, includes, and headers. If you need to
+source these elements from a ``sharedinclude``, make sure the placeholders
+are in a block context as described in the next section.
+
 For example, suppose you want to source content from an external file, located
-at ``dbx/fundamentals/agg-operators.rst`` in the ``docs-shared`` repository,
-which contains the following content:
+at ``dbx/fundamentals/agg-operators.rst`` in the ``docs-shared`` repository
+that contains the following content:
 
 .. code-block:: rst
    :caption: dbx/fundamentals/agg-operators.rst external file in docs_shared
@@ -131,7 +140,6 @@ which contains the following content:
    To learn more about **aggregation operators**, see the
    |learn-agg-operator-docs|.
 
-
 In the sourcing file, you can use the following placeholder replacement
 in the ``sharedinclude`` directive:
 
@@ -146,27 +154,22 @@ in the ``sharedinclude`` directive:
          Aggregation Operations page in the
          :server:`MongoDB Server documentation </aggregation>`
 
-The published page renders as if the sourcing file contained the following rST:
+The published page renders as if the sourcing file contained the following
+{+rst-abbrev+}:
 
 .. code-block:: rst
    :copyable: false
 
    To learn more about **aggregation operators**, see the Aggregation Operations
    page in the :server:`MongoDB Server documentation </aggregation>`.
 
-
-You cannot replace variable placeholders in inline contexts with elements
-such as lists, codeblocks, includes, and headers. If you need to
-source these elements from a ``sharedinclude``,, make sure the placeholders
-are in a block context as described in the following section.
-
 Placeholders in Block Context
 `````````````````````````````
 
 A **block context** describes the positioning of placeholders as
-separated from paragraph text by linebreaks. You can replace variable
-placeholders in a block context with most inline or block rST elements
-including the following types:
+separated from paragraph text by line breaks. You can replace variable
+placeholders in a block context with most inline or block {+rst-abbrev+}
+elements, including the following types:
 
 - Titles
 - Code blocks
@@ -175,7 +178,7 @@ including the following types:
 
 For example, suppose you want to source content from an external file, located
 at ``dbx/fundamentals/agg-operators.rst`` in the ``docs-shared`` repository,
-which containsk the following content:
+which contains the following content:
 
 .. code-block:: rst
    :caption: dbx/fundamentals/agg-operators.rst external file in docs_shared
@@ -211,7 +214,7 @@ in the ``sharedinclude`` directive:
 
             { <operator>: [ <argument1>, <argument2> ... ] }
 
-The published page renders as if the sourcing file contained the following rST:
+The published page renders as if the sourcing file contained the following {+rst-abbrev+}:
 
 .. code-block:: rst
    :copyable: false