It is important that the final document is consistent with formatting and general style. This guide shares some requirements and suggestions
to help.

When editing please include at least a brief comment about your changes for the commit log.


## Text Formatting ##

- The document editing is done using [[Markdown]] syntax with a few extensions:

> - \(\(\(three parentheses))) will be used for indexing entries for the book's Index. For example:

>    \(\(\(Syslog, reloading)))

- Another extension for preformatted code or examples that use a fixed font is to prefix the line with two double-quotes (\"\"):

""drwxr-xr-x   4 _reed_  reed     512 Oct 10 12:59 **var**

> This is because the back-ticks notation does not allow Markdown formatting to be converted.

- If you need real backticks within this custom preformatted block, then use HTML entity: `&#96;` TODO: check printed output
- Do not use superfluous highlighting. Only use \_italics_ or \*\*bold** very rarely (if any).
- Sometimes special characters like underscore (\_) may need to be escaped with a slash (\\).
- Manually using LaTeX should not be needed.
- Be [[careful]] with formatting as the [[PDF]] format for the printed book is generated from this content.
- To include less-than (`<`) or greater-than (`>`) characters just put backticks around it or use HTML entities.


## Length ##

- Book length at book size will be around 200 to 250 pages. The book's [[objective|Chapter_Introduction]] is not to be a large encyclopaedic reference but a quick learning guide. (At initial import, the book was around 90 pages.)

- Section lengths vary by topic, but with description and example(s) from a half (printed) page to three pages. If a topic becomes longer than three pages, split it up. (Note: at initial import there were 104 sections.)

## Cross-references ##

Cross-references are handled for the printed book for referring to top-level sections as highlighted with two pound signs (\#\#).
A \#\# top-level section \#\#  becomes a label.
Also a label is automatically made that matches the individual wiki page name (minus the .html).
Then to point to it just use two brackets \[\[Name\_of\_section\]\], for example:

> See section [[Determine_which_process_are_consuming_the_most_CPU]] for more details about ...

Note that sub-sections aren't automatically handled because we have multiple of these headers with identical naming.

Note that some special characters have been remapped for filenames. See below ...

## File Naming ##

- \_\_39__ in the filename is a single quote
- \_\_40__ is a left parenthesis
- \_\_41__ is a right parenthesis
- \_\_44__ is a comma
- a dash-dash (--) is replacement for a slash (in a filename)

## General Notes ##

1. Spell out asterisk and backslash and other characters as appropriate, like "using an asterisk (*) in the ...".
1. "it__'__s" means "it is"; the possessive pronoun "its" does not have a single-quote (just like his or hers).
1. Opinions should not be included just facts. Use comments or a sub-discussion page for discussion. If an option is really needed in book, attempt to back up all the opinions with solid fact, attribution  or other references.
1. Please do a spell check. For the main book, please use American English.
1. Search for sentences that begin with "There are ..." (or "This is ...") and consider rewording them. (In other words, convert from passive voice to active voice.) For example, maybe start the sentence with a rewording from the end of the original sentence, add some action verb and then complete the sentence.
1. Search for the word "that" -- does your sentence sound good without it?
1. Use words for "zero" through "ten" (even "eleven" and "twelve" if you prefer) as appropriate.
1. Don't have gender bias. Don't use "him" or "he".

## Writing Suggestions ##

1. Read your article out-loud -- does it sound natural?
1. Teach the reader -- make sure your section is educational and something that the reader can learn from.
1. If you have writer's block, try writing a letter to a friend teaching about the concept, describing it, and showing a few examples and explaining the examples. Then use that letter as the basis for your section.

## To cover here in style guide ##

- screenshots
- tables 
- cross-reference other sections in book
- reference man pages and outside docs, etc.
- format for pathnames (and document in [[conventions|Chapter_Introduction]])

> maybe use `fixed face` for `/path/to/file` by using back ticks around it (TODO: escaping with backslashes is not working)

- format for command output (and document in [[conventions|Chapter_Introduction]])

> maybe use indented block by indenting with four spaces or with a tab, for example:

    this is indented with four spaces
    this     is     more       output

> Note that other markdown doesn't render within code blocks, so could use backticks as needed

- differentiating commands from command output

> maybe use **bold** for commands typed, for example

""$ **echo foo**
""foo

- define choice like replace with your own value

> maybe use *italics*, for example

""$ **mail -u** *username*

- define consistent unix shell prompt

- define how trademarks and capitalizations are to be handled
