search

redhat-documentation / asciidoc-markup-conventions

How to use AsciiDoc mark-up to properly style elements in Red Hat documentation
https://access.redhat.com/documentation/
17 stars 16 forks source link

Use of Italics for "System or software variable to be replaced by the user" #25

Closed tylerkelly13 closed 3 years ago

tylerkelly13 commented 6 years ago

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.

michellemurray commented 6 years ago

++1

gaurav-nelson commented 6 years ago

+1

rkratky commented 6 years ago

What do you suggest?

tylerkelly13 commented 6 years ago

I suggest using <variable> to make the replaceable more obvious to the user. this is the convention used in openshift docs, as well as some middleware products

rkratky commented 6 years ago

@tylerkelly13 by that you mean mandating the enclosing of the value in <>?

tylerkelly13 commented 6 years ago

Yes, it helps replaceable code stand out more for the user. Some of our code (possibly most) can be copied and pasted from our docs into a terminal and run without modification. It's important emphasize code that needs modification before being run.

swadeley commented 6 years ago

Using <> around a replaceable would be double markup when using italics. Leave them for manual pages.

Re: configuration parameter or environment variable

I agree they should not be in italics. If these are in capitals, such as directives, then no markup is required, but no strong objection to `` for these.

I have been using `` for commands as we already use ** for GUI labels.

bergerhoffer commented 3 years ago

Closing this issue as the replaceable value guidance has been evaluated by the supplementary style guide project, and the effort to update this guide is being handled in #36.