docs/notes/style-guide.adoc

////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License
////

= Style guidelines

:toc:
:toc-placement: preamble

When contributing to the Qpid Dispatch Router documentation, use the _IBM Style Guide_. You can also use the following guidelines for quick reference.

== 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]`.
* Do not use the word 'the' before 'Broker'. It is just 'Broker'

== Styling headings and titles

In headline-style capitalization, capitalize the initial letter of the following words:

* The first and last words of the text
* All nouns, pronouns, adjectives, verbs, adverbs, and subordinating conjunctions, such as 'after', 'although', 'because', 'before', 'how', 'if', 'than', 'that', 'though', 'until', 'when', 'where', 'whether', and 'while'
* Any word in a hyphenated compound that is not an article, preposition, or coordinating conjunction
* The last word in a hyphenated compound, regardless of its part of speech

In headline-style capitalization, do not capitalize the initial letter of the following words:

* Articles, except as the first word
* Coordinating conjunctions
* Prepositions, except as the first or last word
* The 'to' in an infinitive

NOTE: To learn more about Headline-style titles see, the _Capitalization_ section in Chapter 1 of the _IBM Style Guide_.

.Headings Quick Reference
[cols="33%,33%a,33%a",options="header"]
|===
|Item |Use |Not
.2+|Section headings .2+|Configuring the System with Fedora
|Configuring the system with Fedora
|Configuring The System With Fedora
|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
.2+|Document IDs .2+|\[[this_heading_here]]
|\[[this-heading-here]]
|\[[ThisHeadingHere]]
|Unnumbered titled sections |_[discrete]_ |
|===

== Styling replaceables

.Replaceables Quick Reference
[cols="50%,50%a",options="header"]
|===
|Item |Use
|Replaceable value |\`\_SOME_VAR_`
|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,options="nowrap",subs="+quotes"]++`).

.Additional Replaceable Guidelines
* Use callouts for replaceables in code segments to make it clear to the user
  that a replaceable is present.

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

== 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+|\`this-style`
|\`this_style`
|\`ThisStyle`
|===