Merge pull request #108 from redhat-documentation/94-hyphens-in-anchor-id

Issue 94: Use underscore to separate {context}

Author: adahms

modular-docs-manual/content/topics/module_anchor-and-file-names-concept.adoc

@@ -3,12 +3,12 @@
 
 To optimize modular documentation, follow these guidelines for naming module anchors and files:
 
-Anchor names:: Provide an anchor in the format `+++[id="anchor-name-{context}"]+++` for every module so that it can be identified by Asciidoctor when reused or cross-referenced. `+++{context}+++` is a variable whose value you define in the assembly. Give the anchor the same or similar name as the module heading. Separate the words in the anchor with hyphens:
+Anchor names:: Provide an anchor in the format `+++[id="anchor-name_{context}"]+++` for every module so that it can be identified by Asciidoctor when reused or cross-referenced. `+++{context}+++` is a variable whose value you define in the assembly. Give the anchor the same or similar name as the module heading. Separate the words in the anchor with hyphens and use an underscore to separate the `+++{context}+++` part:
 +
 --
 [source]
 ----
-[id="anchor-name-{context}"]
+[id="anchor-name_{context}"]
 = Module Heading
 
 The first sentence of the topic.
@@ -17,7 +17,7 @@ The first sentence of the topic.
 .Example 1. Concept Module
 [source]
 ----
-[id="guided-decision-tables-{context}"]
+[id="guided-decision-tables_{context}"]
 = Guided Decision Tables
 
 The guided decision tables feature works similarly to ...
@@ -26,7 +26,7 @@ The guided decision tables feature works similarly to ...
 .Example 2. Procedure Module
 [source]
 ----
-[id="creating-guided-decision-tables-{context}"]
+[id="creating-guided-decision-tables_{context}"]
 = Creating Guided Decision Tables
 
 You can use guided decision tables to ...
@@ -38,6 +38,8 @@ You can use guided decision tables to ...
 The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. For details, see xref:reusing-modules[]. Other anchor formats include `+++[[anchor-name]]+++` and `+++[#anchor-name]+++`, but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.
 ====
 
+NOTE: The underscore is recommended as the separator for `+++{context}+++`, because this facilitates tooling to distinguish the context part from the base anchor ID.
+
 For more information about Asciidoc anchors, see the link:http://asciidoctor.org/docs/user-manual/#anchordef[Asciidoctor User Manual].
 --
 

modular-docs-manual/content/topics/module_reusing-modules-procedure.adoc

@@ -17,21 +17,21 @@ This error is resolved by adding and defining a document variable.
 [discrete]
 .Procedure
 
-. In the module file that will be reused, add the `+++{context}+++` suffix with a hyphen to the anchor name in the format `[id="anchor-name-+++{context}"+++]`.
+. In the module file that will be reused, add the `+++{context}+++` suffix with a hyphen to the anchor name in the format `[id="anchor-name_{context}"]`.
 +
 NOTE: Although you can use any document variable that clearly indicates the variable in question, such as `+++{product}+++` or `+++{chapter}+++`, the `+++{context}+++` variable is recommended. This variable indicates more generally that the same module can be reused in the specified "context" of one section of a document or another, regardless of whether that section is product-specific or not, whether it is a whole chapter or a small assembly, or some other limitation.
 
 +
 .Two Modules to Be Reused: Module A and Module B
 [source]
 ----
-[id="module-A-being-reused-{context}"]
+[id="module-A-being-reused_{context}"]
 = Module A Heading
 ----
 +
 [source]
 ----
-[id="module-B-being-reused-{context}"]
+[id="module-B-being-reused_{context}"]
 = Module B Heading
 ----
 
@@ -97,7 +97,7 @@ include::module-A-being-reused.adoc
 //
 // ...
 
-[id="module-A-being-reused-{context}"]
+[id="module-A-being-reused_{context}"]
 = Module A Heading
 ----
 
@@ -142,7 +142,7 @@ The module files contain the following content:
 // asset-definitions.adoc
 // business-rules.adoc
 
-[id="projects-{context}"]
+[id="projects_{context}"]
 = Projects
 ----
 
@@ -154,7 +154,7 @@ The module files contain the following content:
 // asset-definitions.adoc
 // business-rules.adoc
 
-[id="creating-assets-{context}"]
+[id="creating-assets_{context}"]
 = Creating Assets
 ----
 
@@ -220,7 +220,7 @@ The module file contains the following content:
 .projects.adoc
 [source]
 ----
-[id="projects-{context}"]
+[id="projects_{context}"]
 = Projects
 ----
 

modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc

@@ -4,11 +4,11 @@
 
 // Base the file name and the ID on the module title. For example:
 // * file name: my-concept-module-a.adoc
-// * ID: [id="my-concept-module-a-{context}"]
+// * ID: [id="my-concept-module-a_{context}"]
 // * Title: = My concept module A
 
 // The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
-[id="using_text_snippets_or_text_fragments-{context}"]
+[id="using_text_snippets_or_text_fragments_{context}"]
 // The `context` attribute enables module reuse. Every module's ID includes a variable that sets the context, such as {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
 = Text Snippets or Text Fragments (Pseudo-modules)
 //In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly.

modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc

@@ -14,7 +14,7 @@ ifdef::context[:parent-context: {context}]
 
 // The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
 [id="a-collection-of-modules"]
-// If the assembly is reused in other assemblies in a guide, include {context} in the ID: [id="a-collection-of-modules-{context}"].
+// If the assembly is reused in other assemblies in a guide, include {context} in the ID: [id="a-collection-of-modules_{context}"].
 = A collection of modules
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 :context: assembly-keyword

modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc

@@ -4,11 +4,11 @@
 
 // Base the file name and the ID on the module title. For example:
 // * file name: my-concept-module-a.adoc
-// * ID: [id="my-concept-module-a-{context}"]
+// * ID: [id="my-concept-module-a_{context}"]
 // * Title: = My concept module A
 
 // The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
-[id="concept-explanation-{context}"]
+[id="concept-explanation_{context}"]
 // The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
 = Concept explanation
 //In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly.

modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc

@@ -8,7 +8,7 @@
 // * Title: = Doing procedure A
 
 // The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
-[id="doing-one-procedure-{context}"]
+[id="doing-one-procedure_{context}"]
 // The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
 = Doing one procedure
 // Start the title of a procedure module with a verb, such as Creating or Create. See also _Wording of headings_ in _The IBM Style Guide_.

modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc

@@ -8,7 +8,7 @@
 // * Title: = My reference A
 
 // The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
-[id="reference-material-{context}"]
+[id="reference-material_{context}"]
 // The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
 = Reference material
 //In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly.