zz1a-asciidoc_cheatsheet_and_style_guide.asciidoc

Style notes:

Markup

Conventions:

Table 1. A Table

syntax	docbook	description
plus signs	monospaced	monospaced text
\`backticks\`	<literal>	generic literal text
star plus	<userinput>	literal commands typed by user or foo
bar plus plus	<replaceable>	+replaceable+ or foo
bar star star plus plus	user inp+replbl	+user input replaceable+ or foo
underscores	<emphasis>	emphasized text and new terms.
'single_quotes'	<emphasis>	URLs, email addresses, filenames, and file extensions
[role="filename"]'/pathto/file.ext'	<filename>	[role="filename"]'/pathto/file.ext'
[role="citetitle"]'Hadoop'	<book title>	[role="citetitle"]'Hadoop'
asterisks	bold text	bold text should not be used for emphasis — use underscores.
H2O and 25 = 32	super/subscripts	H2O and 25 = 32. Subscripts and superscripts. For mathematical equations, italicize the variables: x2 + y2 = z2
[double angles]	<xref>	Style notes:
[1]`	footnotes	footnote[2]. Put them belly-up against text and following the punctuation — Hello.[3] (note: this effs with emacs' markup, so during the early phases I will instead always use a space; will strip them later)
.I am a Title!	figure titles	Titles for figures, tables, examples, and sidebars, but not sections.

Table 2. Block Table

.Image \n image::path/image.jpg	image
[quote] \n _	<quote>	underbars
.Code blk \n ==== ---- \n [source,ruby]	code block
.Sidebar \n **	sidebar
`.Table \n [options="header"] \n	==== \n`	table
	\n <remark>	secret message
plus	[WARNING] \n =====	NOTE, TIP, WARNING, CAUTION

Titles

== Chapter
=== Section
==== Sub-section
===== Passage

Lists

Definition Lists

Term 1::
  Definition/description
Term 2::
  Something else

Bulleted (aka Itemized) Lists

• lions

• tigers

  • sabre-toothed

  • teapotted

• bears

Ordered (aka Numbered) Lists

1. Preparation

2. Assembly

   1. Measure

   2. Combine

   3. Bake

3. Applause

JOEMAN:Notation

| :HS | Half Sentence | :Comment | General editorial comment | :FIN | Chapter / section needs finishing, conclusion, summary

References

Blocks

Quote

Here’s a <quote> by Tracy Morgan:

Live every week like it was Shark Week

Images & Figures

See guidelines for illustrations

Somewhere nearby is [FIG1_syntax] (a figure, titled and cross-referenced).

[[FIG_syntax]]
.A figure
image::images/quadkeys-numbering-zl0-zl1.png[alt="This is the alt text" width="222px"]

Figure 1. A figure

Code Block

Inline code block. You can use include::code/HelloWorld.rb[] to pull it in from a separate file.

Prefix each with

[source,java]
CODE_BLOCK_NOTE = Standard line length for code is 85 in an "Animal" book:"

STANDARD LINE_FORMAT = <<-EOF
0        10        20        30        40        50        60        70        80
1234567890123456789012345678901234567890123456789012345678901234567890123456789012345
EOF

Contrast the code block above with An Example, which is a formal code example (titled and cross-referenced).

Example 1. An Example

[source,ruby]

CODE_BLOCK_NOTE = "Note that the line length is a bit longer here (90 in an Animal):"

LINE_FORMAT = <<-EOF
0        10        20        30        40        50        60        70        80        9
123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890
EOF

Sidebar

A Sidebar

This is a sidebar!!

Tables

[[STD_TABLE]]
.A Table
[options="header"]
|=======
| syntax                                | docbook               | description
| `+plus signs+`			| monospaced      	| +monospaced text+
|=======

Secret Messages

Use a passthrough block like this for notes to production staff

Admonitions (Notes and Warnings)

Here are some admonitions:

Note	O’Reilly Animal books traditionally make no distinction between the DocBook <note>, <tip>, and <important> elements.

Tip	Titled Admonition We do support optional titles in admonitions (in most series).

Warning

O’Reilly Animal books traditionally make no distinction between the DocBook <warning> and <caution> elements.

Caution

O’Reilly Animal books traditionally make no distinction between the DocBook <warning> and <caution> elements.

---

1. This is a footnote.

2. This is a footnote.

3. hi!