Needs to be more robust about asciidoc-markup-conventions HOT 5 CLOSED

@yzimmerm The guidelines are not intended as a substitute for AsciiDoc(tor) documentation. They only specify the way selected elements should be formatted to conform with Red Hat docs styling. When there is no guideline specified, regular (valid) AsciiDoc mark-up should be used -- i.e. no special formatting is called for.

To learn about general AsciiDoc syntax, please, use the following resources:

• AsciiDoc Syntax Quick Reference
• AsciiDoc Writer’s Guide
• Asciidoctor User Manual

In your particular example, the problem is caused by your incorrect use of the admonition mark-up. You're omitting the required admonition delimiter (====), which causes the code block to not be included in the admonition. This doesn't have anything to do with the 'note' being a part of a list or not. Use the following mark-up to achieve the desired result (and see the Admonition chapter in AsciiDoctor documentation for an overview of the syntax):

[NOTE]
====
The `*<auth>*` sub-element exists in different locations within the guest XML's `*<pool>*` and 
`*<disk>*` elements. For a `*<pool>*`, `*<auth>*` is specified within the `*<source>*` element, as this 
describes where to find the pool sources, since authentication is a property of some pool sources 
(iSCSI and RBD). For a `*<disk>*`, which is a sub-element of a domain, the authentication to the iSCSI 
or RBD disk is a property of the disk. In addition, the `*<auth>*` sub-element for a disk differs from that 
of a storage pool.

----
<auth username='redhat'>
  <secret type='iscsi' usage='iscsirhel7secret'/>
</auth>
----
====

from asciidoc-markup-conventions.

@rkratky The problem is that AsciiDcotor documentation provides for things that are not supported by ccutil. For example: [subs="quotes"] works just fine to add formatting codes in a code block in ccutil. However, ccutil does not parse it properly, and it requires [literal, subs="quotes"].

The NOTE tag works fine without delimiters, except for very specific situations. In addition, there are multiple x-ref formats in the AsciiDoctor documentation. Which should be used.

I think that this AsiiDoc Markup Conventions document should have much more content. I would want it to be my go to cheat sheet!

from asciidoc-markup-conventions.

The problem is that AsciiDcotor documentation provides for things that are not supported by ccutil.

I'm not aware of any such things. ccutil users asciidoctor internally.

For example: [subs="quotes"] works just fine to add formatting codes in a code block in ccutil. However, ccutil does not parse it properly, and it requires [literal, subs="quotes"].

That's not the case. I can point to a number of CP-published examples where [subs="quotes"] works just fine. The issue you're experiencing is likely caused by some other factor. Moreover, by using the literal block, you're changing the semanticity of your mark-up. See Literal Text and Blocks.

Also, I recommend you try [subs="+quotes"], which adds the substitution rule to the list of substitutions rules applied by default (as opposed to replacing it -- as documented at Incremental Substitutions).

The NOTE tag works fine without delimiters, except for very specific situations.

Yours is one of the specific situations -- namely when you need the admonition to include content spread over more than one paragraph. Then the use of delimiters is required, just like with other block elements. This is all described in the linked manual.

there are multiple x-ref formats in the AsciiDoctor documentation. Which should be used.

All valid AsciiDoc xref syntax is supported by ccutil. Therefore, you can use all valid xref formats. There's no need to prefer one over the other -- as long as the syntax is correct.

I think that this AsiiDoc Markup Conventions document should have much more content.

As stated before, this document's purpose is to provide guidelines on styling and formatting of specific elements. For example, it codifies that Red Hat docs should render variables in a certain way and offers the AsciiDoc syntax that ensures such styling.

The document is not intended as a general help with AsciiDoc syntax.

I would want it to be my go to cheat sheet!

I can appreciate that, but this is only a styling cheatsheet. Not syntax cheatsheet.

Perhaps you'd like to start and coordinate an effort to create a CCS-wide 'tips and tricks for AsciiDoc syntax' doc? I'm sure many people would like that, and I would support that. Only thing is, such content is not suitable for this particular doc.

from asciidoc-markup-conventions.

@rkratky the freshness of asciidoctor hidden inside ccutil is disputable, I think ;-)

@yzimmerm ask jherrmann about the asciidoc materials, he likely knows most as he produces some.

from asciidoc-markup-conventions.

the freshness of asciidoctor hidden inside ccutil is disputable, I think ;-)

True :) But given that Fedora has an almost two-year-old version, too, I don't think it matters much...

from asciidoc-markup-conventions.