Comments (12)
@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.
Related Issues (20)
- Add supported syntax highlighting formats HOT 2
- Add links to AsciiDoc(tor) user manual and mark-up reference HOT 1
- Add intro paragraph HOT 2
- Edit text to say 'Click' instead of 'Press' HOT 1
- Mark the conventions that are experimental HOT 3
- Add 'Inline Icons' to this list
- Fix link to mod docs guide
- nbsp for product names HOT 4
- Use of Italics for "System or software variable to be replaced by the user" HOT 8
- Product name
- the subtitle is not accurate HOT 2
- Incorrect example of emphasis for a term HOT 3
- Keyboard shortcut example doesn't match IBM Style HOT 1
- Double underscore for italics surrounded by chevrons (aka pointy brackets)
- {nbsp} in Command Block HOT 1
- Needs to be more robust HOT 5
- Update the 'Reference to Red Hat guides' example HOT 1
- Update the 'System or software variable to be replaced by the user' example ad markup used HOT 1
- Update the 'Anchor' example HOT 3
- Add context description to clarify purpose of this resource
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from asciidoc-markup-conventions.