Separate the internal and external wrappers in examples

msuchane · Feb 26, 2024 · f848cf9 · f848cf9
1 parent 75892c5
commit f848cf9
Show file tree

Hide file tree

Showing 10 changed files with 23 additions and 22 deletions.
diff --git a/docs/modules/con_documentation-files-generated-from-templates.adoc b/docs/modules/con_documentation-files-generated-from-templates.adoc
@@ -28,7 +28,7 @@ ref___title-of-section__-__title-of-its-including-parent__.adoc
 
 * If no tickets in your project match the `filter` rules defined in this chapter or section, it does not generate any file.
 +
-You must remove or comment out the include statement to this file in your `main.adoc` file, otherwise `asciidoctor` reports an error when you compile the document.
+You must remove or comment out the include statement to this file in your `main-template.adoc` file, otherwise `asciidoctor` reports an error when you compile the document.
 +
 For example:
 

diff --git a/docs/modules/proc_adding-an-explanatory-footnote-to-private-tickets.adoc b/docs/modules/proc_adding-an-explanatory-footnote-to-private-tickets.adoc
@@ -25,7 +25,7 @@ The footnote must appear before you include the first file generated by {name},
 +
 You can store the footnote text in a separate attribute, so that it is more convenient to edit:
 +
-.Placement of the footnote in main.adoc
+.Placement of the footnote in main-template.adoc
 ====
 [source,asciidoc]
 ----

diff --git a/docs/modules/proc_building-release-notes.adoc b/docs/modules/proc_building-release-notes.adoc
@@ -50,17 +50,17 @@ $ {bin-name} build
 . Compile the external and internal version of the AsciiDoc document:
 +
 ----
-$ asciidoctor --safe -vn main.adoc
+$ asciidoctor --safe -vn main-external.adoc
 
-$ asciidoctor --safe -vn internal.adoc
+$ asciidoctor --safe -vn main-internal.adoc
 ----
 
-. Open the `main.html` and `internal.html` files in a web browser to preview the document.
+. Open the `main-external.html` and `main-internal.html` files in a web browser to preview the document.
 +
 In the GNOME desktop environment, you can use the following commands:
 +
 ----
-$ gio open main.html
+$ gio open main-external.html
 
-$ gio open internal.html
+$ gio open main-internal.html
 ----
diff --git a/docs/modules/proc_structuring-templates.adoc b/docs/modules/proc_structuring-templates.adoc
@@ -30,7 +30,7 @@ In this case:
 
 . Rebuild your release notes and examine the generated files in the `{bin-name}/generated/internal/` directory.
 
-. Include the generated files in your `main.adoc` file.
+. Include the generated files in your `main-template.adoc` file.
 
 .Verification
 

diff --git a/docs/modules/ref_available-options-to-organize-release-notes.adoc b/docs/modules/ref_available-options-to-organize-release-notes.adoc
@@ -8,7 +8,7 @@ The `{bin-name}/templates.yaml` configuration file recognizes several options an
 .The base level of organization
 The configuration file always requires the `chapters` entry, which defines the initial, base organization level.
 
-This level is called `chapters` because it usually generates files that you include directly from your `main.adoc` file. These generated files can either be reference modules or assemblies, depending on their content.
+This level is called `chapters` because it usually generates files that you include directly from your `main-template.adoc` file. These generated files can either be reference modules or assemblies, depending on their content.
 
 The `chapters` entry has the following syntax:
 
@@ -52,7 +52,7 @@ NOTE: Subsections can also be called `sections` in the configuration file for le
 .Deeper levels of organization
 If you enable deeper levels of organization by specifying the `subsections` (or `sections`) option in `chapters`, you must add the `subsections` (or `sections`) entry at the top of the `templates.yaml` file.
 
-The `subsections` entry defines rules organizing at levels that you do not include yourself in the `main.adoc` file, but rather, the base-level chapters include these generated files.
+The `subsections` entry defines rules organizing at levels that you do not include yourself in the `main-template.adoc` file, but rather, the base-level chapters include these generated files.
 
 The `subsections` entry has the following syntax, which is identical to the `chapters` syntax, except for the addition of YaML anchors:
 

diff --git a/example/.gitlab-ci.yml b/example/.gitlab-ci.yml
@@ -26,11 +26,11 @@ pages:
   script:
     - mkdir -p $OUT_DIR
     - asciidoctor --safe -vn preview-index.adoc
-    - asciidoctor --safe -vn main.adoc
-    - asciidoctor --safe -vn internal.adoc
+    - asciidoctor --safe -vn main-external.adoc
+    - asciidoctor --safe -vn main-internal.adoc
     - cp preview-index.html $OUT_DIR/index.html
-    - cp main.html $OUT_DIR/external.html
-    - cp internal.html $OUT_DIR/internal.html
+    - cp main-external.html $OUT_DIR/external.html
+    - cp main-internal.html $OUT_DIR/internal.html
     - cp acorns/generated/status-table.html $OUT_DIR/status-table.html
     - cp acorns/generated/status-table.json $OUT_DIR/status-table.json
     - printf "<p>Latest generated release:</p><p><a href=$CI_COMMIT_REF_NAME>$CI_COMMIT_REF_NAME</a></p>" > public/index.html

diff --git a/example/README.adoc b/example/README.adoc
@@ -2,9 +2,11 @@
 
 This directory provides configuration for a release notes documentation project. It uses the aCoRNs tool to generate release notes from Bugzilla and Jira tickets.
 
-* The `main.adoc` file is the main, entry-point AsciiDoc file. It includes both generated and manually written content. It compiles as an external version of the document, suitable for publication.
+* The `main-template.adoc` file is the central AsciiDoc file. It includes both generated and manually written content. You can compile it using the following two wrappers.
 
-* The `internal.adoc` file is a wrapper around `main.adoc`. It enables you to select an internal preview of the documentation, rather than the default external version.
+* The `main-external.adoc` file is a wrapper around `main-template.adoc`. It enables you to select an external preview of the documentation.
+
+* The `main-internal.adoc` file is a wrapper around `main-template.adoc`. It enables you to select an internal preview of the documentation.
 
 * The `manual-content/` directory contains manually written AsciiDoc content that you can include from the main file.
 

diff --git a/example/main-external.adoc b/example/main-external.adoc
@@ -0,0 +1,4 @@
+// Override the generated directory to compile an external version of the document.
+:generated-dir: acorns/generated/external
+
+include::main-template.adoc[]
diff --git a/example/internal.adoc → example/main-internal.adoc b/example/internal.adoc → example/main-internal.adoc
@@ -1,4 +1,4 @@
 // Override the generated directory to compile an internal version of the document.
 :generated-dir: acorns/generated/internal
 
-include::main.adoc[]
+include::main-template.adoc[]
diff --git a/example/main.adoc → example/main-template.adoc b/example/main.adoc → example/main-template.adoc
@@ -1,11 +1,6 @@
 // Include the shared attributes
 include::attributes.adoc[]
 
-// By default, compile the external version of the document.
-ifndef::generated-dir[]
-:generated-dir: acorns/generated/external
-endif::[]
-
 // The name and ID of the title is defined in attributes.adoc
 [id="{ProjectNameID}"]
 = {ProjectName}