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"

For 'GUI Button' we should use the language 'Click' as that's the standard.

@asteflova:

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/

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.

The 'code block' element should link to a list of supported languages.

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

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.

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!

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.

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

A short explanation of the purpose of these guidelines needs to be added to prevent misunderstandings. See #7 (comment)

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.

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:
+
----
<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!

Keyboard shortcuts - kbd:[key1(+key2+...)]

Investigate whether standard mark-up for tables needs to be added.

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.

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

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.

Add a 'Additional Resources' section with $SUBJ.

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

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?

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.

{nbsp} in a command block does not render correctly unless the block is preceded by [subs="attributes"], as in the following example:

[options="nowrap" subs="+quotes,verbatim,attributes"]

ansible-playbook --private-key=/etc/pki/ovirt-engine/keys/engine_id_rsa -i /usr/share/ovirt-engine-metrics/bin/ovirt-engine-hosts-ansible-inventory --extra-vars "{nbsp}cluster_name=Cluster_Name ovn_central=OVN_Central_IP ovn_tunneling_interface=VDSM_Network_Name" ovirt-provider-ovn-driver.yml

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.

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:

• Surrounded by angle brackets (< >)
• Separated by underscores (_) for multi-word values
• Lowercase, unless the rest of the related text is uppercase or another capitalization scheme
• Italicized
• If the user-replaced value is referencing a value in code or in a command that is normally monospace, also use monospace for the user-replaced value.

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

SSIA