Comments (5)
@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:
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.
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
- 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.