[[style-guide]]
= Style guidelines

[[general-styles]]
== General styles

.General quick reference
[cols="33%,33%a,33%a",options="header"]
|===
|Item |Use |Not
|Filesystem names and paths, symbols, and literals.  | \`filename`  |
|GUI items (_Match the capitalization of the button_)  |\*bold*  |
|Navigation link text |\*bold*  |
|Superuser console commands  | $ sudo  |#
|Emphasis  |\_yay_  |\*yay*
|List of options (_underline the default if there is one_)  |1\|[.underline]\#2#\|3 |1/2/3
|Decimal integers < 10  |four  |4
|Decimal integers >= 10  |12  |twelve
|Hexadecimal integers (_always numeric, lowercase x_) |0x123 |0X13
|Number ranges (_always use numerals_)  |1-20 |1-twenty
.3+|Do not use Latin abbreviations  |that is |i.e.
|and so on |etc.
|for example  |e.g.
|Cannot  |cannot  |can not
|And |and | &
.2+|Choices |and |and/or
|or |
|Heartbeating |heartbeating |heart-beating
|===

.Additional general guidelines
* Stick to one file per chapter unless the content is too long,
  excluding reusable topics.
* Don't use contractions, ;).
* Document IDs are book-scoped, so they don't need the book title in
  them.
* Terminate bulleted and numbered lists with periods unless the items
  listed are simple names.
* The words "server" and "broker" are not capitalized unless they
   begin a sentence or appear in a title.
* Avoid the word "simply" unless it clarifies.
* For substitution of `{attr}` in code blocks, use `[subs=+attributes]`.
* For styling of `++*bold*++` (`*bold*`) in code blocks, use
  `[subs=+quotes]`.

[[naming-files-style]]
== Naming files

.File Names Quick Reference
[cols="33%,33%a,33%a",options="header"]
|===
|Item |Use |Not
.2+|Custom attributes
.2+|\`ThisStyle`
|\`this-style`
|\`this_style`
.2+|File and directory names
.2+|\`module_this-style`
|\`module-this_style`
|\`ModuleThisStyle`
|===

Learn more about naming files in the xref:files-and-attributes[Files and Attributes] appendix.

[[headings-titles]]
== Styling headings and titles

Uses sentence-case headings for modules, tables, and figures.

.Headings quick reference
[cols="33%,33%a,33%a",options="header"]
|===
|Item |Use |Not
.2+|Section headings .2+|Configuring the system with RHEL
|Configuring the System with RHEL
|Configuring The System With RHEL
|Procedure Titles (_gerund_) |Configuring | Configure
.2+|Table and block titles .2+|This is an example
|This is an Example
|This Is An Example
.2+|Hyphenated headings .2+| Configuring point-to-point messaging | Configuring Point-To-Point Messaging | Configuring Point-to-point Messaging
|Unnumbered titled sections |_[discrete]_ |
|===

[[ids]]
== Section IDs

The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. Other anchor formats include `+++[[anchor-name]]+++` and `+++[#anchor-name]+++`, but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.

Learn more about reusing content in the link:https://redhat-documentation.github.io/modular-docs/#reusing-modules[Modular Documentation Reference Guide^].

.IDs quick reference
[cols="33%,33%a,33%a",options="header"]
|===
|Item |Use |Not
.3+|Document IDs .3+|++[id="same-as-section-heading-{context}"]++
|\[[this-heading-here]]
|\[[ThisHeadingHere]]
|++[#anchor-name]++
|===

[[punctuation-guide]]
== Styling punctuation

.General punctuation guidelines
* Do not refer to an individual punctuation mark or special character by its symbol alone.
* Use the name alone, or use the name followed by the symbol in parentheses.
* Use the name alone if the punctuation mark or special character is standard, such as a comma or period, and including the symbol would clutter the text.
* Include the symbol in parentheses when a punctuation mark or special character is not well known or when including the symbol improves clarity.

.Punctuation quick reference
[cols="30%,70%a",options="header"]
|===
|Character |Name
|&  | Ampersand
|< > | Angle brackets, opening angle bracket, or closing angle bracket
|" "  | Double quotation marks, opening quotation marks, or closing quotation marks (not quotes or quote marks)
|' '  | Single quotation marks, opening quotation mark,or closing quotation mark (not quotes or quote marks)
|%  | Percent sign
| ( )  | Parentheses, opening parenthesis, or closing parenthesis
|$  | Dollar sign
|*  | Asterisk (not star)
|# |Number sign
|! |Exclamation point (not exclamation mark or bang)
|===

[[replaceables]]
== Styling replaceables

Replaceable values in the text and code should be styled in `monospace`, with italics, uppercase, and hyphens.

.Replaceables quick reference
[cols="50%,50%a",options="header"]
|===
|Item |Use
|Replaceable value |\_`SOME-VALUE`_
|Location of broker instance |\_`BROKER-INSTANCE-DIR>`_
|Component install directory |\_`INSTALL-DIR`_
|===

TIP: If using a replaceable within a source block, you will need to add
`subs="+quotes"`` to the source tag for it to render. (For example : `++[source,subs="+quotes"]++`).

IMPORTANT: If you enter the source language, for example, 'shell', the italics will not render.

== Styling Links

.Links Quick Reference
[cols="33%,33%a,33%a",options="header"]
|===
|Item |Use |Not
.2+|Zip files .2+|zip
|_.zip_
|ZIP
.2+|Tar files .2+|tar
|_.tar_
|TAR
|External links |\link:github.com[GitHub^] |\link:github.com[GitHub]
|Internal links |\xref:doc_id[Section Title]|\xref:doc_id[Section Title^]
|===

NOTE: If you use the caret syntax more than once in a single paragraph, you may need to
escape the first occurrence with a backslash.

IMPORTANT: Links with attributes (including the subject and body segments on mailto links)
are a feature unique to Asciidoctor. When they are enabled, you must surround the link text
in double quotes if it contains a comma.

.Additional link guidelines
* Refer to the top-level sections of books as chapters, not sections
  or topics.
* Do not split link paths across lines when wrapping text. This will cause issues with the doc builds.
