Use auto-generated IDs for Anchor IDs

[bhardesty]

It looks like we may be greatly over-complicating the process for reusing modules within an assembly.

Consider that Asciidoctor automatically generates a unique ID for every section in a document. It ensures that each ID is unique even for included .adoc files. In other words, if you include the same module twice in an assembly, Asciidoctor will generate two separate, unique IDs for those modules.

I verified this by creating a test assembly and then including the same module three times:

= Test Assembly
This assembly is a test. This is only a test.

include::module1.adoc[leveloffset=+1]
include::module1.adoc[leveloffset=+1]
include::module1.adoc[leveloffset=+1]

The output was built without error, and Asciidoctor generated a unique ID for each module1.adoc inclusion (module, module-2, and module-3).

Therefore, is there a reason why we have defined the mod docs standards to require, 1.) manually overriding the auto-generated ID for every module title, and 2.) using attributes to guarantee uniqueness in each ID? If not, it would be much simpler and quicker to just let Asciidoctor generate unique anchor IDs for modules.

Even if this won't work for some reason, we could still use the built-in :idprefix: attribute to manually override an automatically-generated ID. For example, if you defined this (probably just once in the main attributes.adoc file):

:idprefix: {context}

Then in an assembly, you could apply the unique context to an included module:

:context: assembly-1-name
include::con_module-A-being-reused.adoc

In this case, if the title of con_module-A-being-reused.adoc is "Module A", then the automatically-generated anchor ID for the module would resolve to assembly-1-name-module-a.

[VladimirSlavik]

An ID is needed when (cross)linking to a module. So...

• Is the method for automatically generated IDs guaranteed to be stable so the links won't break randomly?
• Is it the same for all of the tools that might be used? (Think ccutil vs asciidoctor...)
• What happens if I edit a/an/the/(empty) in the title, or perhaps even replace "application" with "program"?

All of that makes manual IDs a de facto requirement for modules that are a target of some link. Can I predict which modules will be linked to and may need a manual ID? I can only know where I am linking...

The :idprefix: looks great - again, as an ccutil user, I have to ask if it works for me...

[tradej]

Using idprefix is possible, but due to the fact that changing any part of the heading also changes the ID makes me think we don't want to do it, and want to hardcode ID from the very beginning.

In addition to that, if there is an attribute (e. g. a product name) in the heading, changing the attribute changes the anchor IDs automatically too, which may not be obvious to the person changing the attribute, and may further break links without anybody realising.

All in all, I am for keeping the current structure because it is explicit and, in my opinion, fairly error-resistant.

[bhardesty]

@VladimirSlavik @tradej thanks for the feedback. Since I created this issue, I think we've pretty firmly established a standard of hardcoding anchor IDs for modules. So we can close this.