search

redhat-documentation / asciidoc-markup-conventions

How to use AsciiDoc mark-up to properly style elements in Red Hat documentation
https://access.redhat.com/documentation/
17 stars 16 forks source link

Mark the conventions that are experimental #20

Open vikram-redhat opened 6 years ago

vikram-redhat commented 6 years ago

The guide should mark the conventions that are experimental so teams can decide whether or not to use them. I know there is a note at the top that says that some of these conventions are experimental, but it is left for the user to figure out which ones.

rkratky commented 6 years ago

@vikram-redhat, only the UI elements macros (kbd, menu, btn) require the experimental attribute. Given that ccutil (and the CP) fully supports (i.e. renders well) these macros, the team that worked on these conventions did not consider their use optional. The macros improve semanticity of the source and as such are preferred over non-semantic mark-up.

vikram-redhat commented 6 years ago

@rkratky - thanks. I wasn't referring to the UI elements macros, but to the others which are not yet part of the AsciiDoc conventions. The use of the experimental attribute was totally coincidental, but that is an interesting conversation as well.

I was referring to: command, package and filename. These are not standard AsciiDoc tags?

rkratky commented 6 years ago

I was referring to: command, package and filename. These are not standard AsciiDoc tags?

Got it, apologies for the misunderstanding.

The mark-up you're referring to is actually valid AsciiDoc(tor) syntax, and there's nothing experimental about it. AsciiDoc allows setting arbitrary/ad hoc class attributes using the [class]#element# syntax. See http://asciidoctor.org/docs/user-manual/#custom-styling-with-attributes

We're merely making use of this functionality to semantically mark up our source code, so that tools for automated docs testing, such as Emender, can easily pick up these elements and perform their checks.