Demonstrating the use of snippets for both boilerplate content and module reuse

[IanFrangs]

The following git branch tests if snippets are a viable option for reusing both boilerplate content and the contents of entire modules apart from their ID and heading or title in a single title (document, guide etc.). It also provides a folder called "repo" under which I have created a folder structure like one may see in a repo to demonstrate how modules could be reused within a single title or between two titles in the same repo:

https://gitlab.cee.redhat.com/rhci-documentation/docs-Red_Hat_Enterprise_Linux_OpenStack_Platform/-/merge_requests/12371

None of these assemblies or modules provide context IDs.

These modules contain text in which I have explained the advantage of this method of content reuse, such as the ability to provide users with more context for the reused modules, which each provide their own title (H1 heading), which you can make unique if needed and most importantly each module and assembly has its own unique ID.

I want to also reiterate that while a text snippet is not a module, as specified in the mod docs manual. When a snippet is being used to replace the ENTIRE content of a module, it therefore MUST adheres to all the mod docs requirements of this module type, except it does NOT include the anchor ID or H1 heading.

Please install this git branch in your repos and play around with it to familiarize yourself with this suggested replacement for module reuse..

This git branch is also contained in the following ZIP file:
mod-docs-no-context-only-snippets.zip

[aneta-petrova]

@IanFrangs Is there a way to make your example accessible to upstream contributors for testing?

[emmurphy1]

We will try to get something public to share with Max.

[emmurphy1]

Thank you @IanFrangs for providing the template. I was able to apply the concepts to a modified version of an HCC document:
https://gitlab.cee.redhat.com/red-hat-cloud-services-software-documentation/cloud-platform-documentation/-/merge_requests/278

Your model appears to work great.
The only question I have is about the [tag=] in the level offset. Can you explain that?

[IanFrangs]

When creating snippets you can either create a separate snippet file for each snippet that you require or you can use one file for many snippets, if you use a tag to identify each snippet, these tags are added as comments to the snippet file, for example:

// tag::chapter-start-content[]

This is the first line of text that you will read in every main chapter.

// end::chapter-start-content[]

If you choose to use tags, then when including this content, you need to specify the required tag:
include::Snippets/snip-reused_content.adoc[tag=chapter-start-content]

I have tried to add useful comments and instructions for use to the files that I have added to this demo, so that it will be easier to use this demo.

[Jenny-Anne]

Hi @IanFrangs , Thanks for setting this up.

My only issue is that I had a use case for using the ifeval condition with the assembly context to include a module in two different assemblies, so I'm sorry to lose that :) I guess the same result could be achieved somehow with a variable? I'd like to see how a similar condition would work in a snippet. I've created a branch from your branch but haven't tested variables or conditions yet.

= Module heading

Common text common text common text
Common text common text common text

ifeval::["{context}" == "assembly-1-context"]
You can do this thing.
endif::[]

ifeval::["{context}" == "assembly-2-context"]
You can do this other thing.
endif::[]

[IanFrangs]

Hi @Jenny-Anne , yes the ifeval topic provided by Asciidoctor uses AsciiDoc attributes (variables) to specify their conditions
https://docs.asciidoctor.org/asciidoc/latest/directives/ifeval/