Slight tweak to anchor name format about asciidoc-markup-conventions HOT 12 CLOSED

@sterobin, ah, yes, it's an oversight on my part -- not intentional.

I'm happy to submit the PR myself, if you'd like.

Please, do.

Speaking of PRs, do I have the okay then to go ahead and make a PR with the change to the Mod Doc Ref Guide to use this full anchor format instead of the previously decided [#anchor-name] format?

Of course. Please, go right ahead.

from asciidoc-markup-conventions.

@sterobin @rkratky I wanted to ask a question about the delimiter on anchors. Betty was going over the modular docs guide with us last week and we noticed the anchors used a combo of both dashes and underscores and thought it was odd.

We've always used underscores on EAP to delimit our anchors, because if you don't explicitly specify an anchor, the build will automatically use underscores. So we figured it was best to be consistent and use underscores always. I can even see a few instances in the modular docs guide where the section headings use just underscores.

So is what you're suggesting here (and in the modular docs guide) is still to use a combo of dashes and underscores? If so, that seems awful confusing and wouldn't look very nice in the user-facing URLs. We don't use attributes in our anchors now, but I'm not sure I see the benefit of why you would want a different delimiter.

from asciidoc-markup-conventions.

@bergerhoffer, there's a good reason (and a long debate) behind every part of that, but I'll let @sterobin reply :-)

However, @sterobin, the fact that adoctor uses underscores when automatically generating anchors escaped us. I'm not saying we should reopen the discussion, but it weakens the argument for dashes.

from asciidoc-markup-conventions.

@bergerhoffer, in summary of the decision:

• Underscores can cause issues in URLs because there are cases when they are interpreted as spaces. Consider when linked text is underlined, as is common whenever the raw link is placed in the product or in external documentation, forums, etc. This makes underscores disappear. Seems like an edge case, I know, but it happens more often than one would think and I encountered it frequently at a previous organization when dev implemented doc links in the product and found this issue. Also have heard of others facing the same issue. Dashes are the most stable. Plus underscores have become a bit archaic, mostly for this reason. The fact that asciidoctor defaults to underscores in the absence of an anchor doesn't sway my opinion, personally, because we should be defining anchors in every module anyway.

• That said, one handy use of the underscore is to distinguish the anchor name from the context variable in full URLs and in cross-references. Consider a module called "Creating Decision Tables" that is found in multiple assemblies, one of which is called "Asset Types" with the :context: attribute defined according.

With this scenario, consider these dash/underscore options as they appear in cross-refs (the same would also appear in URLs):
A) For details, see xref: creating-decision-tables-asset-types[ ].
B) For details, see xref: creating_decision_tables_asset_types[ ].
C) For details, see xref: creating-decision-tables_asset-types[ ].

With option C, the writer can more easily tell that the module "creating decision tables" is being referenced to its use in the context of "asset types". With options A and B, it takes more deliberate thinking and familiarity.

So it's simply an aid in cross-refs and in URLs, which in some cases could also benefit users. But mostly for us internally.

If we don't like this deviation and want all or nothing, then I vote for dashes all around, unless someone can give a better reason beyond the default asciidoc behavior (which shouldn't matter if all files have anchors set, as they should).

from asciidoc-markup-conventions.

@sterobin Thanks for the explanation.

However, if you're using an underscore to separate the "asset-types" part of the anchor, don't you run into the same exact issue as you've described above with the underscores? Plus, I think we should be more concerned about the end user experience with the anchor as opposed to us as writers.

I still prefer underscores, though I can't say that I've had personal experience with the issues that you're describing. But if nothing else, I would prefer just being consistent in the use of dash or underscore.

from asciidoc-markup-conventions.

@bergerhoffer, but it is 'being consistent' -- dashes are used between words, and underscores are used to delimit the boundary between the heading part and the attribute.

I agree with you regarding preference for underscores, but whichever we decide to use, it's a good idea to use the other for clearly separating the heading from the parameter.

from asciidoc-markup-conventions.

@rkratky But why does that separation have to be visible in the end product? I feel like it shouldn't matter in the end product whether something was compiled in a modular fashion or not.

from asciidoc-markup-conventions.

@bergerhoffer, well, the fact that it's visible in the compiled doc is a side product, but a harmless one. In my opinion, it is greatly outweighed by the help it provides writers. The final anchor (i.e. with the attribute translated) is often used even in the source code when you want to link to a specific section. Then it becomes handy.

from asciidoc-markup-conventions.

@bergerhoffer, the original (endless) discussion was at redhat-documentation/modular-docs#19

from asciidoc-markup-conventions.

@rkratky @sterobin I'm fine with keeping the guidance in this doc in sync with the guidance from the modular docs on anchors at the moment. Though I still think it should be revisited there. Again, the argument against underscores doesn't work if you're still using them this way. Might be worth getting larger input on the subject.

from asciidoc-markup-conventions.

And then there's the fact that our own tooling defaults to underscores, too (but it makes a judicious use of dashes). See, e.g., https://access.redhat.com/documentation/en-us/red_hat_container_development_kit/3.2/html-single/release_notes_and_known_issues/

from asciidoc-markup-conventions.

Closing this as the decision on delimeters is up to mod docs, and we have updated to reflect.

from asciidoc-markup-conventions.