Skip to content

Remove prefixes from the IDs in the module templates #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mjahoda merged 4 commits into from
May 26, 2023
Merged

Remove prefixes from the IDs in the module templates #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
306b370
Remove prefixes from the IDs in the module templates
mjahoda Apr 12, 2023
4e93012
Remove example IDs with prefixes from comments
mjahoda Apr 20, 2023
7091f64
Remove example IDs with prefixes from File names and anchors
mjahoda Apr 20, 2023
bd7dd38
Fix broken xrefs and examples in Appendix C
mjahoda Apr 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 4 additions & 23 deletions modular-docs-manual/content/topics/module_anchor-and-file-names-concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ These file naming guidelines are optional but highly recommended. However, if yo
----

.Anchors
At the top of every module, provide an anchor in the format `+++[id="filename_{context}"]+++` where `filename` is the exact name of the file, without the file extension (`.adoc`). Module anchors are necessary so that Asciidoctor can identify the module when the module is reused or cross-referenced. The `context` variable is defined in each assembly module, such as `:context: my-context-value`. When you build an assembly, the value of the `context` variable replaces `context` in each module anchor ID and is displayed in the generated URL.
At the top of every module, provide an anchor in the format `+++[id="filename_{context}"]+++` where `filename` is the exact name of the file, without the file extension (`.adoc`) and a module prefix. Module anchors are necessary so that Asciidoctor can identify the module when the module is reused or cross-referenced. The `context` variable is defined in each assembly module, such as `:context: my-context-value`. When you build an assembly, the value of the `context` variable replaces `context` in each module anchor ID and is displayed in the generated URL.

[source]
----
Expand All @@ -52,35 +52,16 @@ The first sentence of the topic.
.Example 1. Concept module
[source]
----
[id="con-guided-decision-tables_{context}"]
[id="guided-decision-tables_{context}"]
= Guided Decision Tables

The guided decision tables feature works similarly to ...
----

.Example 2. Concept module
.Example 2. Procedure module
[source]
----
[id="con_guided-decision-tables_{context}"]
= Guided Decision Tables

The guided decision tables feature works similarly to ...
----


.Example 3. Procedure module
[source]
----
[id="proc-creating-guided-decision-tables_{context}"]
= Creating Guided Decision Tables

You can use guided decision tables to ...
----

.Example 4. Procedure module
[source]
----
[id="proc_creating-guided-decision-tables_{context}"]
[id="creating-guided-decision-tables_{context}"]
= Creating Guided Decision Tables

You can use guided decision tables to ...
Expand Down
2 changes: 1 addition & 1 deletion modular-docs-manual/content/topics/module_creating-assemblies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ An assembly could represent an article, "chapter" in a book, or even an entire b
. Create an assembly file for each user story that you identified.
+
--
Be sure to follow the conventions for xref:anchor-and-file-names[naming anchors and files]. For example: `guided-decision-tables.adoc`
Follow the conventions for xref:module_anchor-and-file-names-concept[naming anchors and files]. For example: `assembly_designing-guided-decision-tables.adoc`
--

. For each top-level assembly file that you created, fill in the content.
Expand Down
2 changes: 1 addition & 1 deletion modular-docs-manual/content/topics/module_creating-modules.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ After identifying and creating the assemblies, each assembly should identify the
--
Each assembly should already have the names of the modules that should be included in the assembly. Now you just need to create the actual files for those modules.

Be sure to follow the conventions for xref:anchor-and-file-names[naming anchors and files]. For example: `guided-decision-tables.adoc`
Follow the conventions for xref:module_anchor-and-file-names-concept[naming anchors and files]. For example: `proc_creating-guided-decision-tables.adoc`
--
. For each module file that you created, add content.
+
Expand Down
6 changes: 3 additions & 3 deletions modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
////
Base the file name and the ID on the module title. For example:
* file name: con-my-concept-module-a.adoc
* ID: [id="con-my-concept-module-a_{context}"]
* file name: con_my-concept-module-a.adoc
Copy link
Collaborator

@emmurphy1 emmurphy1 May 25, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why con_ instead of con-?

Copy link
Contributor Author

@mjahoda mjahoda May 25, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@emmurphy1 I think that it makes sense to distinguish the prefix part and the title part of a file name this way. Moreover, it's a default in the newdoc tool, all RHEL modules and assemblies follow this pattern, and if you check the source files [1] of our mod-docs guide... :-)

[1] https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/content/topics

* ID: [id="my-concept-module-a_{context}"]
* Title: = My concept module A
////

Expand All @@ -17,7 +17,7 @@ Add the following attribute before the module ID:
The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
////

[id="con-my-concept-module-a_{context}"]
[id="my-concept-module-a_{context}"]

////
The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
Expand Down
6 changes: 3 additions & 3 deletions modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
////
Base the file name and the ID on the module title. For example:
* file name: proc-doing-procedure-a.adoc
* ID: [id="proc-doing-procedure-a_{context}"]
* file name: proc_doing-procedure-a.adoc
* ID: [id="doing-procedure-a_{context}"]
* Title: = Doing procedure A

Indicate the module type in one of the following
Expand All @@ -13,7 +13,7 @@ Add the following attribute before the module ID:
The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in an assembly file.
////

[id="proc-doing-procedure-a_{context}"]
[id="doing-procedure-a_{context}"]

= Doing procedure A
////
Expand Down
6 changes: 3 additions & 3 deletions modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
////
Base the file name and the ID on the module title. For example:
* file name: ref-my-reference-a.adoc
* ID: [id="ref-my-reference-a_{context}"]
* file name: ref_my-reference-a.adoc
* ID: [id="my-reference-a_{context}"]
* Title: = My reference A
////

Expand All @@ -17,7 +17,7 @@ Add the following attribute before the module ID:
The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
////

[id="ref-reference-material_{context}"]
[id="reference-material_{context}"]

////
The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
Expand Down