Mark the conventions that are experimental

[vikram-redhat]

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]

@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]

@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]

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.