DRAFT FS Document Font Conventions

1. Introduction

This document covers font and other typographic conventions for FS HTML documents using asciidoctor source.

2. Conventions

2.1. Terminology

All top-level document sections are referred to as sections.
All sections below the top-level are referred to as sub-sections.
All steps at the top-level of instructions are referred to as steps.
All steps below the top-level are referred to as sub-steps.

Note	Steps often occur as sub-sections. If a section, or sub-section, is a step, or sub-step, it should referred to as a step, or sub-step, as appropriate.

2.2. In-line text

The default body font is used for all text, except:

italics are used for names (filenames, filename extensions, directory paths, libraries, programs, accounts, UNIX commands, versions, nodes, domain names, websites, URLs, URIs, email addresses, etc., but not people, places, FSx, or FSLx), emphasis, variable items, and the first use of technical terms.
monospace is used for data (code, program input/output, contents of files, UNIX command options, FS commands, etc.) and explicit command/option examples.
monospace bold for explicit input/commands to be entered by the user.
monospace italic (no bold) for replaceable/variable items in data and explicit commands/text to be entered by the user.
<angle brackets> around replaceable items that would have been italics anyway.

2.3. Code blocks

For code blocks of simple input or output, monospace is used. Italics are used for replaceable items.

For code blocks with both input and output, the output is shown as it would for a simple output. Literal user input is bold, with replaceable user input as bold italics.

2.4. Links

The anchor text in all links is normal body text for simplicity. Using references to section or lists is preferred to using the numbering or lettering since those may change. The form used depends on the reference:

External URLs — These are references to web pages outside of the FS. The anchor text should be the full URL. Shorter anchor text can be used if explained; this is useful for repetitive forms.
Other FS documents — These are references to other FS documents. The anchor text should be the full title of the document. The surrounding text should identify it as a document.
Sections (or steps that appear as sections) in other FS documents — The anchor text should be the full section title. The surrounding text should identify it as a section or sub-section (or step or sub-step) and include a link to the document.
References to other anchors in other FS documents — The anchor display text should show content related text. The surrounding text should identify it as something other than a section/step (perhaps change if appropriate) and include links to its section/step and document. There should be a link reference to the anchor at the point where it occurs, typically followed by a colon. This makes the location of the anchor visible. The text in the link at anchor and in the reference(s) should be the same.
References to sections/steps of the current document — The anchor text should be the full section/step title. The surrounding text should identify it as a section or sub-section (or step or sub-step). Including whether it is above and below is helpful.
References to other anchors in the current document — The anchor text should show content related text. The surrounding text should identify it as something other than a section/step (perhaps change if appropriate) and include a link to its section/step. There should be a link reference to the anchor at the point where it occurs, typically followed by a colon. This makes the location of the anchor visible. The text in the link at anchor and in the reference(s) should be the same.
An appendix is referred to as an “appendix” but is otherwise referenced the same as a section. Sections, steps, sub-sections, and sub-steps in appendices are referenced the same as ones in the main document.

2.5. Document titles

Document titles use normal important word capitalization. Upper case is used for acronyms and technical terms that are normally upper case. There are no special fonts in document titles.

2.6. Section and sub-section titles

The first word and proper names in sections and sub-section titles start with capital letters. Upper case is used for acronyms and technical terms that are normally upper case. Other words are all lower case.

There are no special fonts in section and sub-section titles for simplicity. Such formatting may also trigger different results for different asciidoctor versions.

2.7. General guidelines for admonitions

These are not firm distinctions.

Tip

Advice

Note	Non-essential, supplemental, information

Caution

Could cause a minor issue

Warning

Could cause a major issue

Important

Will result in a major issue

2.8. FS/drudg change items

Each change is listed as an automatically numbered title (starting with an active verb), then usually a few summary sentences, followed by a collapsible block:

Details

Details are shown here.

The Details toggle can be clicked on to show (or not show) the block. In this way, you can view the summary as a list and only reveal the details of items that interest you. The summary sentences and/or the collapsible block may be omitted if they would not add any new information, usually because it is already covered in the numbered title item and/or the details are very brief.

2.9. Links to different documents and to the inside of collapsible blocks

If you return “back” to a document after following a link to a different document, previously opened collapsible blocks will be closed because the web page has been reloaded. This makes it a little more difficult to return to where you were reading in the original document if it was within opened text.

Tip	To avoid this, right click the link, then open it in a new tab (alternatively, open it in a new window), and then click on that tab. To return to the original document, you can close the new tab or click on the original document’s tab (or close the new window), whatever you prefer.

Links that point into a closed collapsible block in the same document do not work in all browsers. To help with that, when these links appear, additional instructions with a second link to the item with the collapsible block are provided. If the original link into the collapsible block doesn’t work, an alternate approach is to follow the second link, click on the Details toggle below that location to open it, go Back in the browser, and then click on the original link. At least some Chromium-based browsers appear to able to follow links into a closed collapsible blocks.

Links that point into a collapsible block in a different document also do not work in all browsers. To help with that, if the relevant text is small it is reproduced within an embedded sidebar block (grey background). Otherwise, a second link to the item with the collapsible block is provided along with instructions to follow the link (probably opening it in a new tab, or new window, would be best), open the toggle, and then search for the anchor text of the original link.

3. Source examples

3.1. Italics

Use single underscores around _words_ to be in italics; double underscores for __char__acters.

Results in:

Use single underscores around words to be in italics; double underscores for characters.

3.2. Monospace

Use single backticks around `words` to be in monospace; double backticks for ``char``acters.

Results in:

Use single backticks around words to be in monospace; double backticks for characters.

3.3. Monospace bold

Use single backticks and asterisks around `*words*` to be in monospace bold; double backticks and single asterisks for ``*char*``acters.

Results in:

Use single backticks and asterisks around words to be in monospace bold; double backticks and single asterisks for characters.

3.4. Monospace italic

Use single backticks and underscores around `_words_` to be in monospace italics; double backticks and single underscores for ``_char_``acters.

Results in:

Use single backticks and underscores around words to be in monospace italics; double backticks and single underscores for characters.

3.5. Curved quotes

Add backticks inside '`quotes`' to make them "`curved.`"

Results in:

Add backticks inside ‘quotes’ to make them “curved.”

3.6. Code blocks

Code blocks are created by indenting text, or preceding and following it with four periods.

3.7. Italics and bold in code blocks

[subs="+quotes"]
....
login: _account_
password: _password_
$ *ls* *_dir_*
....

Results in:

login: account
password: password
$ ls dir

3.8. Open blocks

Open blocks can be useful for better indentation in complicated situations. They essentially make a block that can be indented as needed. To put text in an open block, insert it between two lines that each start with two dashes. For example:

. A few experimental, __user beware__, utilities were
added.
+

CAUTION: These may not work well for their intended purpose or at all.
They are only intended for developers.  They may change in the future.

+
--
In _misc/_:

* _ntpmon_ -- Simple NTP monitoring

* _time_delay_ -- Simple source acquisition time delay listing

* _tpcont_rdbe_ -- Simple RDBE continuous TP extraction
--
+

In _chk_time_/:

*  _chk_time_ a simple utility for checking for NTP time jumps.

Results in:

A few experimental, user beware, utilities were added.

Caution
These may not work well for their intended purpose or at all. They are only intended for developers. They may change in the future.
In misc/:
- ntpmon — Simple NTP monitoring
- time_delay — Simple source acquisition time delay listing
- tpcont_rdbe — Simple RDBE continuous TP extraction
In chk_time/:
- chk_time a simple utility for checking for NTP time jumps.

3.9. Admonitions

Admonitions are created by starting a line with the admonition in capital letters followed by a colon and space.

For admonitions with complex content, a block can be made by putting the capitalized admonition in square brackets, then on the next line four equal signs, then ending the block with a line of four equal signs.

[TIP]
====
Suggestion:

. Step
. Another step
====

Results in:

Tip	Suggestion: Step Another step

3.10. Linking to inline anchors

Inline anchors provide a way to link to arbitrary text. To assist the reader, the location of the inline anchor can made visible by including a link to it where it occurs. By convention, this “visibility” link is usually followed by semicolon. To ease identifying the anchor, all links to the inline anchor, including the visibility link, should use the same anchor text. An example of using an inline anchor:

[[check_files]]<<check_files,Check files>>: Some explanatory text
probably follows. The inline anchor above is in double square brackets
`+++[[<i>anchor</i>]]+++`. The link with anchor text, is in double
angle brackets `+++<<<i>anchor</i>,<i>text</i>>>+++`.

Somewhere else in the document, before or after the inline anchor,
include a link to it. In this example, see <<check_files,Check
files>>, above.

It can also be referred to from a different document with something of
the form <<font_conventions.adoc#check_files,Check files>> with the
correct relative path to the document. Including a link to the section
and the document will be helpful for those working from a print-out.

Renders as:

Check files: Some explanatory text probably follows. The inline anchor above is in double square brackets [[anchor]]. The reference, with anchor text, is in double angle brackets <<anchor,text>>.

Somewhere else in the document, before or after the inline anchor, include a reference to it. In this example, see Check files, above.

It can also be referred to from a different document with something of the form Check files with the correct relative path to the document. Including a reference to the section and the document will be helpful for those working from a print-out.

3.11. Appendices

Add appendices by inserting :doctype: book before the title of the document. Then before the each appendix insert [appendix]. The appendix title appears as a document title (conceptually it is a new book). Sections start with === (conceptually they are sub-sections). Sub-sections (====) can be added as needed:

:doctype: book

= Document title

[appendix]

= Title of appendix

=== Title of section

==== Title of sub-section

3.12. Collapsible blocks

Collapsible blocks are used in FS/drudg change items and wherever it may be useful to suppress a lengthy narrative that may not be of interest to all readers. The collapsible block starts with [%collapsible] followed by a line of four equal signs. The end of the block is marked by another line with four equal signs. For example:

[%collapsible]
====
Details are shown here.
====

renders as:

Details

Details are shown here.

3.13. Embedded sidebar blocks

Embedded sidebar blocks are use to set off text that is being quoted from another source. It is displayed in a grey background. It is delineated by two lines of four asterisks. Full formatting with the text is usually preserved. For example:

****
. _quoted_ *text*
****

renders as:

quoted text

3.14. Nesting blocks

Nesting blocks can be achieved by increasing the number of equal signs in the lines used to delineate the blocks. For example:

[NOTE]
====
Note text
[TIP]
=====
Tip text
=====
More note text
====

renders as

Note

Note text

Tip

Tip text

More note text

4. Workarounds

This section covers some ad hoc workarounds for issues with asciidoctor.

4.1. Effect of references to sections in other documents on italics

In some cases a reference to a section header in a different document, e.g.,:

<<beta2.adoc#_update_control_files,Update control files>>

may fail to link properly if there are italicized words (implemented as single underscores on each side of the word) later in the same paragraph.

There are two possible fixes. The first is preferred.

Change the single underscores around all the following words to be italicized in the same paragraph to be double underscores.

This treats them as characters to be italicized, which is syntactically correct, if somewhat typographically redundant. This is the preferred approach since it stays within the normal syntax.
Change the #_ in the reference to #\_.

While more compact typographically, this is not preferred because it is outside the normal syntax. And although it fixes the link, single underscores for italics will then not work for words that follow in that paragraph.

4.2. List continuation

In some cases the usual list continuation command, a plus sign (+) on a line by itself, may not provide the expected indentation. If the indentation level is not enough, sometimes it can be fixed by adding more lines with a plus sign, typically with blank lines between them. Another technique is to add an extra line with a plus sign after the last indented section and before the next list item. Some experimentation may be needed to achieve the desired indentation.

Another useful tool that may solve some problems is Open blocks.

4.3. Unordered list markers

Unordered list markers alternate when nesting by default as:

Disc (closed circle)
- Circle (open circle)
  - Square (continuing to lower levels)

This gives a reasonably appearance, but the HTML rendering may produce a different alternation within ordered lists. In principle it is possible to set the style manually, but it may apply to remaining all levels until the next section. The bottom line is that it may be possible to get a reasonable result only for a one-level unordered list in this situation. A nested list is probably best left to the default alternation, which may still not be very good when used within ordered lists. Avoiding complicated nesting, or additional use of ordered lists, is probably the best answer.

An example of what can be reasonably accomplished is to convert:

Item
- Not a disc

to:

Item
- Disc

Using

. Item
[disc]
* Disc

The full set of marker styles that can be set are disc, circle, square, none (no marker, but indented), and unstyled (no marker or indentation).