Needs to be more robust

[yzimmerm]

The file needs to be more robust and include many more complex examples. For example:

• How do you make commands in a code block bold?
• x-ref formats are not included in the file.
• How do you add a code block to a note in a numbered list? See the following example:

  
  . Add an authentication entry in the storage pool's XML file using the [command]`virsh edit` command, 
  and add an `*<auth>*` element, specifying `*authentication type*`, `*username*`, and `*secret usage*`.

• For example:

• ---

  iscsirhel7pool /dev/disk/by-path

  ---

• [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.

• ---

  ---

  
  The code block at the end should be part of the note, but I have no idea how to do it!

[rkratky]

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

[yzimmerm]

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

[rkratky]

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.

[VladimirSlavik]

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

[rkratky]

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...