redhat-documentation / asciidoc-markup-conventions Goto Github PK
View Code? Open in Web Editor NEWHow to use AsciiDoc mark-up to properly style elements in Red Hat documentation
Home Page: https://access.redhat.com/documentation/
How to use AsciiDoc mark-up to properly style elements in Red Hat documentation
Home Page: https://access.redhat.com/documentation/
SSIA
@rkratky, I see that we are in sync on the anchor name format per my latest email to you Nov 6, 2017. The format you suggest is right on. However, per our previous agreement in the Mod Doc Ref Guide (which needs to be updated per the full anchor format as well), it should be an underscore preceding the {parameter}, not a dash. You, @tradej, and I had a long discussion on this and agreed that the underscore would be a nice delimiter between anchor IDs and parameter names when mentioned in full in xrefs.
So you've said this: [id='section-header-{parameter}']
But should be this: [id='section-header_{parameter}']
to be consistent with Mod Doc Ref Guide decisions and previous discussions.
This will make an xref like this: For details, see xref:section-header_parameter-name.
Also, I would recommend mentioning the use of the {context} attribute specifically, even as a note, and linking to the discussion of Reusing Modules in the Mod Doc Ref Guide.
I'm happy to submit the PR myself, if you'd like.
Speaking of PRs, do I have the okay then to go ahead and make a PR with the change to the Mod Doc Ref Guide to use this full anchor format instead of the previously decided [#anchor-name] format? Please let me know here or via the email I sent you.
Thanks,
Stetson
The guide is IMO missing the following at the moment:
Keyboard shortcuts - kbd:[key1(+key2+...)]
. At the same time, this only works if you set :experimental:
in the master file, I'm not really sure how we want to handle that. Keycombos are important and used quite a lot in some types of docs so I feel we should have them and tell people to use experimental, it doesn't seem to break anything.
Admonitions - [NOTE]
, [IMPORTANT]
, [WARNING]
. Those are used all the time and very useful. They don't need any special parameters, but the document should explain to people when to use each admonition, a la the old Document Conventions we used to put at the start of older guides. (Note = you might be interested in knowing this, Important = you might lose data if you don't know this, Warning = you will lose data if you don't know this).
Tables - there's no mention of those. It's not a huge problem since it's basically just "do an asciidoc table", however other elements that are just basic adoc, like links or images, are explained in the doc so we should cover tables too. Preferably also show how to do multi-row/multi-column cells.
The ADoc equivalent of xrefs, so we can point to internal IDs and get autogenerated links.
Notes on elements that are already included:
"Code blocks" could use a link to a list of languages supported by the highlighter
"Command blocks" a link to the ADoc reference explaining [subs=...]
options, or better yet, just list useful options and what they do. We should also mention that yes, please add the prompt (#
or $
based on whether the user is expected to be root or not), and don't add the current directory (foo]#
). If there's consensus on that, of course - an argument could be made for including the current dir if we're telling the user to switch directories, since it helps people orient themselves.
The example must be update to reflect the latest Mod docs conventions as per the Modular Documentation Reference Guide: https://redhat-documentation.github.io/modular-docs/
From: [id="section-header_{context}"]
To: [id="proc-section-header_{context}"]
or [id="ref-section-header_{context}"]
or [id="con-section-header_{context}"]
or even [id="assembly-section-header_{context}"]
This quick reference would benefit from a description that explains its purpose, for example that it describes the technical implementation of various style elements.
For information about stylistic choices, see the IBM Style Guide and the Red Hat supplementary style guide for product documentation (https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values)
For information about modular documentation guidelines, see the Modular Documentation Reference Guide (https://redhat-documentation.github.io/modular-docs/).
In the current guide it has the following example:
Emphasis for a term | Use this approach. -- | --
I don't think we should ever use italics to emphasise a word like 'this'. I cannot think of a scenario where this would be a legitimate use case.
If we are adding italics, we should be doing so in accordance with the IBM Style Guide.
For example, when you define a new term, the word you are defining can be in italics.
I suggest either deleting this guidance, or rewriting with an example from IBM Style Guide.
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.
IBM style pp 219 and elsewhere outlines how keyboard shortcuts should be handled in documentation.
In the Asciidoc Markup conventions doc, we highlight keyboard shortcuts in another manner.
Why is it necessary to break with IBM here? Is it really necessary to highlight it if IBM doesn't say it should be highlighted? I didn't see any discussion of this on the mailing lists.
Thanks!
A note needs to be added that the :experimental:
attribute must be enabled for the mark-up to work properly.
I believe it's enabled by default in ccutil/Pantheon (check!), but local AsciiDoctor or CI Jenkins previews, wouldn't work w/o it.
For 'GUI Button' we should use the language 'Click' as that's the standard.
{nbsp} in a command block does not render correctly unless the block is preceded by [subs="attributes"], as in the following example:
A short explanation of the purpose of these guidelines needs to be added to prevent misunderstandings. See #7 (comment)
Investigate whether standard mark-up for tables needs to be added.
Looking at the table[1], I noticed one thing.
The mark-up for anchors is either [[anchor]] or [#anchor]. I recommend adding [id='anchor']. It's the only one that seems to work with attributes in appendices. To be more specific:
An anchor like this in an appendix:
[#{assembly}-section_header]
gives this error when building with ccutil:
asciidoctor: ERROR: master.adoc: line 67: invalid part,
must have at least one section (e.g., chapter, appendix, etc.)
But with an anchor like this:
[id='{assembly}-section_header']
the book builds correctly.
[1] https://redhat-documentation.github.io/asciidoc-markup-conventions/
It would be great if we could include 'Inline Icons' too here. It would help to be consistent on this in all our documentation.
http://asciidoctor.org/docs/user-manual/#inline-icons suggests: 'icon:tags[] ruby, asciidoctor' for font based icons.
Says this:
Navigate to menu:File[Import>Import csv] to import a csv file.
But I think should be this:
Navigate to menu:[File>Import>Import csv] to import a csv file.
Right?
I suggest adding a comment to "System or software variable to be replaced by the user".
Underscores are not rendered as italics in a code block if they are surrounded by chevrons. Example: product_key renders as unformatted text.
Workaround: double underscores. product_key does render as italics.
Keyboard shortcuts - kbd:[key1(+key2+...)]
Add a 'Additional Resources' section with $SUBJ.
The file needs to be more robust and include many more complex examples.
For 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:
+
----
<pool type='iscsi'>
<name>iscsirhel7pool</name>
<source>
<host name='192.168.122.1'/>
<device path='iqn.2010-05.com.example.server1:iscsirhel7guest'/>
<auth type='chap' username='redhat'>
<secret usage='iscsirhel7secret'/>
</auth>
</source>
<target>
<path>/dev/disk/by-path</path>
</target>
</pool>
----
+
[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>
----
The code block at the end should be part of the note, but I have no idea how to do it!
Hello, the subtitle is not accurate. It is not really an "overview", its the list of markup.
I suggest just remove "Overview of".
Thank you
Laura Bailey:
I am curious about "NOTE: Do not put steps in bold." beside ordered lists - I've often titled steps in procedures, and have used bold on the first part of an ordered list item to make the main action clearer to those who are skimming rather than reading in-depth. What's our reasoning here?
Use of Italics for "System or software variable to be replaced by the user" and "System or software configuration parameter or environment variable" may lead to confusion.
Recommend reviewing this convention.
This example doesn't follow the conventions for references that outlined in the IBM Style Guide (see Citations and references, General guidelines).
I suggest rewording the example
from: See the JBoss EAP Getting Started Guide for more information.
to: For more information, see the JBoss EAP Getting Started Guide.
According to the RH Supplementary Style Guide (https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values) this example should be updated to reflect the following guidelines.
Ensure that user-replaced values have the following characteristics:
Example AsciiDoc: User-replaced value in a paragraph
Create an Ansible inventory file that is named /_<path>_/inventory/hosts
.
Suggested change
from: Use the following command to roll back a deployment, specifying the deployment name: oc rollback _deployment_
.
to: Use the following command to roll back a deployment, specifying the deployment name: oc rollback _<deployment>_
.
alternative suggestion: To roll back a deployment, specify the deployment name: oc rollback _<deployment>_
.
The company name and product name guidelines indicate no special markup, but we should have a non-breaking space markup recommended. I believe the guidelines in the past were something like this:
Red Hat Enterprise Linux
The 'code block' element should link to a list of supported languages.
Can we add an example that shows when not to add {nbsp} ?
For example, there must not be a {nbsp} between "Hat" and "Enterprise" in:
"Red{nbps}Hat Enterprise{nbsp}Linux{nbsp}7"
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.