Adding upstream version 2.1.6.upstream/2.1.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 99 insertions, 0 deletions

diff --git a/doc/asciidoc.reference b/doc/asciidoc.reference
new file mode 100644
index 0000000..7a5fcb5
--- /dev/null
+++ b/doc/asciidoc.reference
@@ -0,0 +1,99 @@
+= Single-chapter part of the documentation =
+
+== Go-to reference chapter for how we use AsciiDoc on this project ==
+
+[NOTE]
+======
+This is *not* an attempt for fully self-hosted AsciiDoc document,
+consider it a plaintext full of AsciiDoc samples (it's up to the reader
+to recognize the borderline) at documentation writers' disposal
+to somewhat standardize the style{empty}footnote:[
+  style of both source notation and final visual appearance
+].
+
+See also:
+   http://powerman.name/doc/asciidoc
+======
+
+Emphasis:    _some test_
+Mono:        +some text+
+Strong:      *some text*
+Super:       ^some text^
+Sub:         ~some text~
+Quotes:
+             ``double quoted''
+              `single quoted'
+
+Command:     `some-tool --with option`
+Newly introduced term:
+             'some text' (another form of emphasis as of this edit,
+                          but not compatible with newer revision
+                          of the standard/Asciidoctor outside of
+                          legacy compatibility mode)
+
+File:        mono
+Literal:     mono
+Tool:        command
+Option:      mono
+Replaceable: emphasis mono
+Varname:     mono
+Term encountered on system (e.g., menu choice, hostname):
+             strong
+
+
+.Title for Example
+=====
+Some text
+=====
+
+.Title for Example with XML Listing
+=====
+[source,XML]
+-----
+<some xml=here/>
+-----
+=====
+
+Naked code listing:
+(Use 'C' and a leading '#' instead of 'Bash' when commands are being show)
+
+[source,C]
+-----
+# some command --here
+-----
+
+
+Section anchors:
+
+[[s-name]]
+=== Some Section Title ===
+
+References to section anchors:
+
+<<s-name>> or <<s-name,Alternate Text>>
+
+
+Tables:
+
+Typically styled like this:
+[width="95%",cols="1m,<4m,<6",options="header",align="center"]
+
+It's vital that column alignment/style, if any, goes first/last in the proper
+column specifier (as a whole possibly preceded with column multiplier),
+otherwise Asciidoctor will end up with invalid DocBook sources:
+- correct: 1m,<4m,<6
+- bad:     1m,4<m,6<
+
+Avoid "a" (asciidoc) style for the columns, since it will prevent any
+reference anchors being placed there.  However, if the particular cell
+is to carry a list (inherently a block element) or a comment that should
+be omitted from the output, it needs to be turned into asciidoc style like
+this (note the initial 'a'):
+
+|col1-per-row
+|col2-per-row
+|Details for col1 + col2 per row combo:
+a|Hence either:
+
+* foo
+* bar