|
|
AsciiDoc User Guide
|
|
|
===================
|
|
|
Stuart Rackham <srackham@gmail.com>
|
|
|
:Author Initials: SJR
|
|
|
:toc:
|
|
|
:icons:
|
|
|
:numbered:
|
|
|
:website: http://asciidoc.org/
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
.This document
|
|
|
**********************************************************************
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
See <X6,Getting Started> and Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
**********************************************************************
|
|
|
|
|
|
|
|
|
Introduction
|
|
|
------------
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
.muspi meroL or Lorem ipsum?
|
|
|
**********************************************************************
|
|
|
|
|
|
.murobal tse di mina tillom tnuresed aiciffo iuq apluc ni tnus ,tnediorp non tatadipuc taceacco tnis ruetpecxE .rutairap allun taiguf ue erolod mullic esse tilev etatpulov ni tiredneherper ni rolod eruri etua siuD .tauqesnoc odommoc ae xe piuqila tu isin sirobal ocmallu noitaticrexe durtson siuq ,mainev minim da mine tU .auqila angam erolod te erobal tu tnudidicni ropmet domsuie od des ,tile gnicsipida rutetcesnoc ,tema tis rolod muspi meroL
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
**********************************************************************
|
|
|
|
|
|
|
|
|
[[X6]]
|
|
|
Getting Started
|
|
|
---------------
|
|
|
Installing Lorem
|
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
See the `README` and `CONTRIBUTING` Files. <<X38,Packager Notes>>.
|
|
|
|
|
|
[[X11]]
|
|
|
Example LoremDocs
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
Check it:
|
|
|
|
|
|
- Lorem ipsum dolor sit amet,
|
|
|
|
|
|
- consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
|
|
|
|
|
|
- Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
|
|
|
|
|
Ipsum Document Types
|
|
|
-----------------------
|
|
|
There are three types of AsciiDoc documents: article, book and
|
|
|
manpage. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
article
|
|
|
~~~~~~~
|
|
|
Used for short documents, articles and general documentation.
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
book
|
|
|
~~~~
|
|
|
Books share the same format as articles, with the following differences: The part titles in multi-part books are top level titles (same level as book title); and some sections are book specific e.g. preface and colophon.
|
|
|
|
|
|
Use DocBook!
|
|
|
|
|
|
|
|
|
manpage
|
|
|
~~~~~~~
|
|
|
Used to generate roff format UNIX manual pages.
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
Supported stuff.
|
|
|
|
|
|
docbook45::
|
|
|
Outputs DocBook XML 4.5 markup.
|
|
|
|
|
|
|
|
|
html5::
|
|
|
This backend generates HTML 5 markup
|
|
|
|
|
|
slidy::
|
|
|
Use this backend to generate self-contained HTML + JS slideshows from asciidoc docs.
|
|
|
|
|
|
.Stylesheet file locations
|
|
|
[cols="3*",frame="topbot",options="header"]
|
|
|
|====================================================================
|
|
|
|'stylesdir' attribute
|
|
|
|Linked location ('linkcss' attribute defined)
|
|
|
|Embedded location ('linkcss' attribute undefined)
|
|
|
|
|
|
|Undefined (default).
|
|
|
|Same directory as the output document.
|
|
|
|`stylesheets` subdirectory in the AsciiDoc configuration directory
|
|
|
(the directory containing the backend conf file).
|
|
|
|
|
|
|Absolute or relative directory name.
|
|
|
|Absolute or relative to the output document.
|
|
|
|Absolute or relative to the AsciiDoc configuration directory (the
|
|
|
directory containing the backend conf file).
|
|
|
|
|
|
|====================================================================
|
|
|
|
|
|
Themes
|
|
|
~~~~~~
|
|
|
|
|
|
The AsciiDoc 'theme' attribute is used to select an alternative CSS
|
|
|
stylesheet and to optionally include additional JavaScript code.
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
Lorem Ipsum Structure
|
|
|
------------------
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
Document ::= (Header?,Preamble?,Section*)
|
|
|
Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
|
|
|
AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
|
|
|
RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
|
|
|
Preamble ::= (SectionBody)
|
|
|
Section ::= (Title,SectionBody?,(Section)*)
|
|
|
SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
|
|
|
Block ::= (Paragraph|DelimitedBlock|List|Table)
|
|
|
List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
|
|
|
BulletedList ::= (ListItem)+
|
|
|
NumberedList ::= (ListItem)+
|
|
|
CalloutList ::= (ListItem)+
|
|
|
LabeledList ::= (ListEntry)+
|
|
|
ListEntry ::= (ListLabel,ListItem)
|
|
|
ListLabel ::= (ListTerm+)
|
|
|
ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
|
|
|
|
|
|
Where:
|
|
|
|
|
|
- '?' implies zero or one occurrence, '+' implies one or more
|
|
|
occurrences, '*' implies zero or more occurrences.
|
|
|
- All block elements are separated by line boundaries.
|
|
|
- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
|
|
|
shown) can occur almost anywhere.
|
|
|
- There are a number of document type and backend specific
|
|
|
restrictions imposed on the block syntax.
|
|
|
- The following elements cannot contain blank lines: Header, Title,
|
|
|
Paragraph, ItemText.
|
|
|
- A ListParagraph is a Paragraph with its 'listelement' option set.
|
|
|
- A ListContinuation is a <<X15,list continuation element>>.
|
|
|
|
|
|
[[X95]]
|
|
|
Header
|
|
|
~~~~~~
|
|
|
The Header contains document meta-data, typically title plus optional
|
|
|
authorship and revision information:
|
|
|
|
|
|
- The Header is optional, but if it is used it must start with a
|
|
|
document <<X17,title>>.
|
|
|
- Optional Author and Revision information immediately follows the
|
|
|
header title.
|
|
|
- The document header must be separated from the remainder of the
|
|
|
document by one or more blank lines and cannot contain blank lines.
|
|
|
- The header can include comments.
|
|
|
- The header can include <<X18,attribute entries>>, typically
|
|
|
'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc',
|
|
|
'numbered'.
|
|
|
- Header attributes are overridden by command-line attributes.
|
|
|
- If the header contains non-UTF-8 characters then the 'encoding' must
|
|
|
precede the header (either in the document or on the command-line).
|
|
|
|
|
|
Here's an example AsciiDoc document header:
|
|
|
|
|
|
Writing Documentation using AsciiDoc
|
|
|
====================================
|
|
|
Lory Ipps <Lor@lorie.ipsum>
|
|
|
v1.0, November 2019:
|
|
|
Lorem Ipsum Hello World
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
firstname[ [middlename ]lastname][ <email>]]
|
|
|
|
|
|
|
|
|
|
|
|
Special Section Titles
|
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
|
|
|
|
|
|
|
|
|
|
|
<title>=<template>
|
|
|
|
|
|
`<title>` is a Python regular expression and `<template>` is the name
|
|
|
of a configuration file markup template section.
|
|
|
|
|
|
.Special section titles vs. explicit template names
|
|
|
*********************************************************************
|
|
|
AsciiDoc has two mechanisms for specifying non-default section markup
|
|
|
templates: you can specify the template name explicitly (using the
|
|
|
'template' attribute) or indirectly (using 'special section titles').
|
|
|
Specifying a <<X93,section template>> attribute explicitly is
|
|
|
preferred. Auto-magical 'special section titles' have the following
|
|
|
drawbacks:
|
|
|
|
|
|
*********************************************************************
|
|
|
|
|
|
Inline Elements
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
|
Special chars::
|
|
|
Stuff like `<`, `>`, and `&` characters).
|
|
|
|
|
|
Quotes::
|
|
|
As you would expect block quotes to work etc
|
|
|
|
|
|
Special Words::
|
|
|
Mark it up right there kind of like latex math shortcut
|
|
|
|
|
|
Replacements::
|
|
|
Like a simple regex
|
|
|
|
|
|
Attribute references::
|
|
|
Document attribute names enclosed in braces are replaced by
|
|
|
the corresponding attribute value.
|
|
|
|
|
|
Inline Macros::
|
|
|
Inline macros are replaced by the contents of parametrized
|
|
|
configuration file sections.
|
|
|
|
|
|
|
|
|
Document Processing
|
|
|
-------------------
|
|
|
|
|
|
Order of precedent for substitution is:
|
|
|
|
|
|
1. Special characters
|
|
|
2. Quotes
|
|
|
3. Special words
|
|
|
4. Replacements
|
|
|
5. Attributes
|
|
|
6. Inline Macros
|
|
|
7. Replacements2
|
|
|
|
|
|
Text Formatting
|
|
|
---------------
|
|
|
|
|
|
Quoted Text
|
|
|
~~~~~~~~~~~
|
|
|
Words and phrases can be formatted by enclosing inline text with
|
|
|
quote characters:
|
|
|
|
|
|
_Emphasized text_::
|
|
|
Word phrases \'enclosed in single quote characters' (acute
|
|
|
accents) or \_underline characters_ are emphasized.
|
|
|
|
|
|
*Strong text*::
|
|
|
Word phrases \*enclosed in asterisk characters* are rendered
|
|
|
in a strong font (usually bold).
|
|
|
|
|
|
[[X81]]+Monospaced text+::
|
|
|
Word phrases \+enclosed in plus characters+ are rendered in a
|
|
|
monospaced font. Word phrases \`enclosed in backtick
|
|
|
characters` (grave accents) are also rendered in a monospaced
|
|
|
font but in this case the enclosed text is rendered literally
|
|
|
and is not subject to further expansion
|
|
|
|
|
|
`Single quoted text'::
|
|
|
Phrases enclosed with a \`single grave accent to the left and
|
|
|
a single acute accent to the right' are rendered in single
|
|
|
quotation marks.
|
|
|
|
|
|
``Double quoted text''::
|
|
|
Phrases enclosed with \\``two grave accents to the left and
|
|
|
two acute accents to the right'' are rendered in quotation
|
|
|
marks.
|
|
|
|
|
|
#Unquoted text#::
|
|
|
Placing \#hashes around text# does nothing, it is a mechanism
|
|
|
to allow inline attributes to be applied to otherwise
|
|
|
unformatted text.
|
|
|
|
|
|
|
|
|
Delimited Blocks
|
|
|
----------------
|
|
|
|
|
|
Predefined delimited block underlines:
|
|
|
|
|
|
CommentBlock: //////////////////////////
|
|
|
PassthroughBlock: ++++++++++++++++++++++++++
|
|
|
ListingBlock: --------------------------
|
|
|
LiteralBlock: ..........................
|
|
|
SidebarBlock: **************************
|
|
|
QuoteBlock: __________________________
|
|
|
ExampleBlock: ==========================
|
|
|
OpenBlock: --
|
|
|
|
|
|
.Default DelimitedBlock substitutions
|
|
|
[cols="2e,7*^",frame="topbot",options="header,autowidth"]
|
|
|
|=====================================================
|
|
|
| |Attributes |Callouts |Macros | Quotes |Replacements
|
|
|
|Special chars |Special words
|
|
|
|
|
|
|PassthroughBlock |Yes |No |Yes |No |No |No |No
|
|
|
|ListingBlock |No |Yes |No |No |No |Yes |No
|
|
|
|LiteralBlock |No |Yes |No |No |No |Yes |No
|
|
|
|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|
|
|
|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|
|
|
|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|
|
|
|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|
|
|
|=====================================================
|
|
|
|
|
|
|
|
|
Open Blocks
|
|
|
~~~~~~~~~~~
|
|
|
Open blocks are special:
|
|
|
|
|
|
- The open block delimiter is line containing two hyphen characters. Open blocks can be styled to behave like any other type of delimited
|
|
|
block.
|
|
|
|
|
|
[listing]
|
|
|
--
|
|
|
Lorum ipsum ...
|
|
|
--
|
|
|
|
|
|
---------------
|
|
|
Lorum ipsum ...
|
|
|
---------------
|
|
|
|
|
|
- An unstyled open block groups section elements but otherwise does
|
|
|
nothing.
|
|
|
|
|
|
Open blocks are used to generate document abstracts and book part
|
|
|
introductions:
|
|
|
|
|
|
- Apply the 'abstract' style to generate an abstract, for example:
|
|
|
|
|
|
[abstract]
|
|
|
--
|
|
|
In this paper we will ...
|
|
|
--
|
|
|
|
|
|
. Apply the 'partintro' style to generate a book part introduction for
|
|
|
a multi-part book, for example:
|
|
|
|
|
|
[partintro]
|
|
|
.Optional part introduction title
|
|
|
--
|
|
|
Optional part introduction goes here.
|
|
|
--
|
|
|
|
|
|
|
|
|
[[X64]]
|
|
|
Lists
|
|
|
-----
|
|
|
.List types
|
|
|
- Bulleted lists. Also known as itemized or unordered lists.
|
|
|
- Numbered lists. Also called ordered lists.
|
|
|
- Labeled lists. Sometimes called variable or definition lists.
|
|
|
- Callout lists (a list of callout annotations).
|
|
|
|
|
|
.List behavior
|
|
|
- List item indentation is optional and does not determine nesting,
|
|
|
indentation does however make the source more readable.
|
|
|
- Another list or a literal paragraph immediately following a list
|
|
|
item will be implicitly included in the list item; use <<X15, list
|
|
|
item continuation>> to explicitly append other block elements to a
|
|
|
list item.
|
|
|
- A comment block or a comment line block macro element will terminate
|
|
|
a list -- use inline comment lines to put comments inside lists.
|
|
|
- The `listindex` <<X60,intrinsic attribute>> is the current list item
|
|
|
index (1..). If this attribute is used outside a list then it's value
|
|
|
is the number of items in the most recently closed list. Useful for
|
|
|
displaying the number of items in a list.
|
|
|
|
|
|
Bulleted Lists
|
|
|
~~~~~~~~~~~~~~
|
|
|
Bulleted list items start with a single dash or one to five asterisks
|
|
|
followed by some white space then some text. Bulleted list syntaxes
|
|
|
are:
|
|
|
|
|
|
...................
|
|
|
- List item.
|
|
|
* List item.
|
|
|
** List item.
|
|
|
*** List item.
|
|
|
**** List item.
|
|
|
***** List item.
|
|
|
...................
|
|
|
|
|
|
Numbered Lists
|
|
|
~~~~~~~~~~~~~~
|
|
|
List item numbers are explicit or implicit.
|
|
|
|
|
|
.....................................................................
|
|
|
1. Arabic (decimal) numbered list item.
|
|
|
a. Lower case alpha (letter) numbered list item.
|
|
|
F. Upper case alpha (letter) numbered list item.
|
|
|
iii) Lower case roman numbered list item.
|
|
|
IX) Upper case roman numbered list item.
|
|
|
.....................................................................
|
|
|
|
|
|
.Implicit numbering
|
|
|
|
|
|
|
|
|
.....................................................................
|
|
|
. Arabic (decimal) numbered list item.
|
|
|
.. Lower case alpha (letter) numbered list item.
|
|
|
... Lower case roman numbered list item.
|
|
|
.... Upper case alpha (letter) numbered list item.
|
|
|
..... Upper case roman numbered list item.
|
|
|
.....................................................................
|
|
|
|
|
|
Here are some examples of bulleted and numbered lists:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
- Praesent eget purus quis magna eleifend eleifend.
|
|
|
1. Fusce euismod commodo velit.
|
|
|
a. Fusce euismod commodo velit.
|
|
|
b. Vivamus fringilla mi eu lacus.
|
|
|
c. Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
2. Vivamus fringilla mi eu lacus.
|
|
|
i) Fusce euismod commodo velit.
|
|
|
ii) Vivamus fringilla mi eu lacus.
|
|
|
3. Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
4. Nam fermentum mattis ante.
|
|
|
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
|
* Fusce euismod commodo velit.
|
|
|
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
|
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
|
vel.
|
|
|
** Vivamus fringilla mi eu lacus.
|
|
|
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
- Nulla porttitor vulputate libero.
|
|
|
. Fusce euismod commodo velit.
|
|
|
. Vivamus fringilla mi eu lacus.
|
|
|
[upperroman]
|
|
|
.. Fusce euismod commodo velit.
|
|
|
.. Vivamus fringilla mi eu lacus.
|
|
|
. Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
Which render as:
|
|
|
|
|
|
- Praesent eget purus quis magna eleifend eleifend.
|
|
|
1. Fusce euismod commodo velit.
|
|
|
a. Fusce euismod commodo velit.
|
|
|
b. Vivamus fringilla mi eu lacus.
|
|
|
c. Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
2. Vivamus fringilla mi eu lacus.
|
|
|
i) Fusce euismod commodo velit.
|
|
|
ii) Vivamus fringilla mi eu lacus.
|
|
|
3. Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
4. Nam fermentum mattis ante.
|
|
|
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
|
* Fusce euismod commodo velit.
|
|
|
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
|
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
|
vel.
|
|
|
** Vivamus fringilla mi eu lacus.
|
|
|
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
- Nulla porttitor vulputate libero.
|
|
|
. Fusce euismod commodo velit.
|
|
|
. Vivamus fringilla mi eu lacus.
|
|
|
[upperroman]
|
|
|
.. Fusce euismod commodo velit.
|
|
|
.. Vivamus fringilla mi eu lacus.
|
|
|
. Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
|
|
|
A predefined 'compact' option is available to bulleted and numbered
|
|
|
lists example:
|
|
|
|
|
|
[options="compact"]
|
|
|
- Compact list item.
|
|
|
- Another compact list item.
|
|
|
|
|
|
|
|
|
[start=7]
|
|
|
. List item 7.
|
|
|
. List item 8.
|
|
|
|
|
|
|
|
|
Labeled Lists
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
Here are some examples:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
In::
|
|
|
Lorem::
|
|
|
Fusce euismod commodo velit.
|
|
|
|
|
|
Fusce euismod commodo velit.
|
|
|
|
|
|
Ipsum:: Vivamus fringilla mi eu lacus.
|
|
|
* Vivamus fringilla mi eu lacus.
|
|
|
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
Dolor::
|
|
|
Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
Suspendisse;;
|
|
|
A massa id sem aliquam auctor.
|
|
|
Morbi;;
|
|
|
Pretium nulla vel lorem.
|
|
|
In;;
|
|
|
Dictum mauris in urna.
|
|
|
Vivamus::: Fringilla mi eu lacus.
|
|
|
Donec::: Eget arcu bibendum nunc consequat lobortis.
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
Which render as:
|
|
|
|
|
|
In::
|
|
|
Lorem::
|
|
|
Fusce euismod commodo velit.
|
|
|
|
|
|
Fusce euismod commodo velit.
|
|
|
|
|
|
Ipsum:: Vivamus fringilla mi eu lacus.
|
|
|
* Vivamus fringilla mi eu lacus.
|
|
|
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
Dolor::
|
|
|
Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
Suspendisse;;
|
|
|
A massa id sem aliquam auctor.
|
|
|
Morbi;;
|
|
|
Pretium nulla vel lorem.
|
|
|
In;;
|
|
|
Dictum mauris in urna.
|
|
|
Vivamus::: Fringilla mi eu lacus.
|
|
|
Donec::: Eget arcu bibendum nunc consequat lobortis.
|
|
|
|
|
|
Horizontal labeled list style
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
The 'horizontal' labeled list style (also the first positional
|
|
|
attribute) places the list text side-by-side with the label instead of
|
|
|
under the label. Here is an example:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
[horizontal]
|
|
|
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
|
|
|
labitur dolorum an. Est ne magna primis adolescens.
|
|
|
|
|
|
Fusce euismod commodo velit.
|
|
|
|
|
|
*Ipsum*:: Vivamus fringilla mi eu lacus.
|
|
|
- Vivamus fringilla mi eu lacus.
|
|
|
- Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
|
|
|
*Dolor*::
|
|
|
- Vivamus fringilla mi eu lacus.
|
|
|
- Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
Which render as:
|
|
|
|
|
|
[horizontal]
|
|
|
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
|
|
|
labitur dolorum an. Est ne magna primis adolescens.
|
|
|
|
|
|
Fusce euismod commodo velit.
|
|
|
|
|
|
*Ipsum*:: Vivamus fringilla mi eu lacus.
|
|
|
- Vivamus fringilla mi eu lacus.
|
|
|
- Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
|
|
|
*Dolor*::
|
|
|
- Vivamus fringilla mi eu lacus.
|
|
|
- Donec eget arcu bibendum nunc consequat lobortis.
|
|
|
|
|
|
[NOTE]
|
|
|
=====================================================================
|
|
|
- Current PDF toolchains do not make a good job of determining
|
|
|
the relative column widths for horizontal labeled lists.
|
|
|
- Nested horizontal labeled lists will generate DocBook validation
|
|
|
errors because the 'DocBook XML V4.2' DTD does not permit nested
|
|
|
informal tables (although <<X13,DocBook XSL Stylesheets>> and
|
|
|
<<X31,dblatex>> process them correctly).
|
|
|
- The label width can be set as a percentage of the total width by
|
|
|
setting the 'width' attribute e.g. `width="10%"`
|
|
|
=====================================================================
|
|
|
|
|
|
Question and Answer Lists
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
Example:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
[qanda]
|
|
|
Question one::
|
|
|
Answer one.
|
|
|
Question two::
|
|
|
Answer two.
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
Renders:
|
|
|
|
|
|
[qanda]
|
|
|
Question one::
|
|
|
Answer one.
|
|
|
Question two::
|
|
|
Answer two.
|
|
|
|
|
|
Glossary Lists
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
|
Example:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
[glossary]
|
|
|
A glossary term::
|
|
|
The corresponding definition.
|
|
|
A second glossary term::
|
|
|
The corresponding definition.
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
Bibliography Lists
|
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
Example:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
[bibliography]
|
|
|
.Optional list title
|
|
|
- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
|
|
|
Programming'. Addison-Wesley. ISBN 0-13-142901-9.
|
|
|
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
|
|
|
'DocBook - The Definitive Guide'. O'Reilly & Associates.
|
|
|
1999. ISBN 1-56592-580-7.
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
The `[[[<reference>]]]` syntax is a bibliography entry anchor, it
|
|
|
generates an anchor named `<reference>` and additionally displays
|
|
|
`[<reference>]` at the anchor position. For example `[[[taoup]]]`
|
|
|
generates an anchor named `taoup` that displays `[taoup]` at the
|
|
|
anchor position. Cite the reference from elsewhere your document using
|
|
|
`<<taoup>>`, this displays a hyperlink (`[taoup]`) to the
|
|
|
corresponding bibliography entry anchor.
|
|
|
|
|
|
|
|
|
Macros
|
|
|
------
|
|
|
Macros are a mechanism for substituting parametrized text into output
|
|
|
documents.
|
|
|
|
|
|
Macros have a 'name', a single 'target' argument and an 'attribute
|
|
|
list'. The usual syntax is `<name>:<target>[<attrlist>]` (for
|
|
|
inline macros) and `<name>::<target>[<attrlist>]` (for block
|
|
|
macros). Here are some examples:
|
|
|
|
|
|
http://www.docbook.org/[DocBook.org]
|
|
|
include::chapt1.txt[tabsize=2]
|
|
|
mailto:srackham@gmail.com[]
|
|
|
|
|
|
Here are some examples:
|
|
|
|
|
|
http://www.docbook.org/[DocBook.org]
|
|
|
http://www.docbook.org/
|
|
|
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
|
|
|
joe.bloggs@foobar.com
|
|
|
|
|
|
Which are rendered:
|
|
|
|
|
|
http://www.docbook.org/[DocBook.org]
|
|
|
|
|
|
http://www.docbook.org/
|
|
|
|
|
|
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
|
|
|
|
|
|
joe.bloggs@foobar.com
|
|
|
|
|
|
If the `<target>` necessitates space characters use `%20`, for example
|
|
|
`large%20image.png`.
|
|
|
|
|
|
Internal Cross References
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
anchor
|
|
|
++++++
|
|
|
Example anchor:
|
|
|
|
|
|
[[X1]]
|
|
|
|
|
|
xref
|
|
|
++++
|
|
|
Creates a hypertext link to a document anchor.
|
|
|
|
|
|
<<<id>,<caption>>>
|
|
|
xref:<id>[<caption>]
|
|
|
|
|
|
The `<id>` refers to an anchor ID. The optional `<caption>` is the
|
|
|
link's displayed text. Example:
|
|
|
|
|
|
<<X21,attribute lists>>
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
[[tiger_image]]
|
|
|
.Tyger tyger
|
|
|
image::tiger.png[]
|
|
|
|
|
|
This can be seen in <<tiger_image>>.
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
HTML 5 audio and video block macros
|
|
|
-----------------------------------
|
|
|
The 'html5' backend 'audio' and 'video' block macros generate the HTML
|
|
|
5 'audio' and 'video' elements respectively. They follow the usual
|
|
|
AsciiDoc block macro syntax `<name>::<target>[<attrlist>]` where:
|
|
|
|
|
|
[horizontal]
|
|
|
`<name>`:: 'audio' or 'video'.
|
|
|
`<target>`:: The URL or file name of the video or audio file.
|
|
|
`<attrlist>`:: A list of named attributes (see below).
|
|
|
|
|
|
.Audio macro attributes
|
|
|
[options="header",cols="1,5",frame="topbot"]
|
|
|
|====================================================================
|
|
|
|Name | Value
|
|
|
|options
|
|
|
|A comma separated list of one or more of the following items:
|
|
|
'autoplay', 'loop' which correspond to the same-named HTML 5 'audio'
|
|
|
element boolean attributes. By default the player 'controls' are
|
|
|
enabled, include the 'nocontrols' option value to hide them.
|
|
|
|====================================================================
|
|
|
|
|
|
.Video macro attributes
|
|
|
[options="header",cols="1,5",frame="topbot"]
|
|
|
|====================================================================
|
|
|
|Name | Value
|
|
|
|height | The height of the player in pixels.
|
|
|
|width | The width of the player in pixels.
|
|
|
|poster | The URL or file name of an image representing the video.
|
|
|
|options
|
|
|
|A comma separated list of one or more of the following items:
|
|
|
'autoplay', 'loop' and 'nocontrols'. The 'autoplay' and 'loop' options
|
|
|
correspond to the same-named HTML 5 'video' element boolean
|
|
|
attributes. By default the player 'controls' are enabled, include the
|
|
|
'nocontrols' option value to hide them.
|
|
|
|====================================================================
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
---------------------------------------------------------------------
|
|
|
audio::images/example.ogg[]
|
|
|
|
|
|
video::gizmo.ogv[width=200,options="nocontrols,autoplay"]
|
|
|
|
|
|
.Example video
|
|
|
video::gizmo.ogv[]
|
|
|
|
|
|
video::http://www.808.dk/pics/video/gizmo.ogv[]
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
Example:
|
|
|
---------------------------------------------------------------------
|
|
|
++++
|
|
|
<video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" >
|
|
|
<source src="pics/video/gizmo.mp4" />
|
|
|
<source src="pics/video/gizmo.webm" type="video/webm" />
|
|
|
<source src="pics/video/gizmo.ogv" type="video/ogg" />
|
|
|
Video not playing? <a href="pics/video/gizmo.mp4">Download file</a> instead.
|
|
|
</video>
|
|
|
|
|
|
<script type="text/javascript">
|
|
|
var video = document.getElementById('video');
|
|
|
video.addEventListener('click',function(){
|
|
|
video.play();
|
|
|
},false);
|
|
|
</script>
|
|
|
++++
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
Tables
|
|
|
------
|
|
|
Example tables
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
|
.Simple table
|
|
|
[width="15%"]
|
|
|
|=======
|
|
|
|1 |2 |A
|
|
|
|3 |4 |B
|
|
|
|5 |6 |C
|
|
|
|=======
|
|
|
|
|
|
.AsciiDoc source
|
|
|
---------------------------------------------------------------------
|
|
|
[width="15%"]
|
|
|
|=======
|
|
|
|1 |2 |A
|
|
|
|3 |4 |B
|
|
|
|5 |6 |C
|
|
|
|=======
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
.Columns formatted with strong, monospaced and emphasis styles
|
|
|
[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
|
|
|
|==========================
|
|
|
| 2+|Columns 2 and 3
|
|
|
|1 |Item 1 |Item 1
|
|
|
|2 |Item 2 |Item 2
|
|
|
|3 |Item 3 |Item 3
|
|
|
|4 |Item 4 |Item 4
|
|
|
|footer 1|footer 2|footer 3
|
|
|
|==========================
|
|
|
|
|
|
.AsciiDoc source
|
|
|
---------------------------------------------------------------------
|
|
|
.An example table
|
|
|
[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
|
|
|
|==========================
|
|
|
| 2+|Columns 2 and 3
|
|
|
|1 |Item 1 |Item 1
|
|
|
|2 |Item 2 |Item 2
|
|
|
|3 |Item 3 |Item 3
|
|
|
|4 |Item 4 |Item 4
|
|
|
|footer 1|footer 2|footer 3
|
|
|
|==========================
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
.Horizontal and vertical source data
|
|
|
[width="80%",cols="3,^2,^2,10",options="header"]
|
|
|
|=========================================================
|
|
|
|Date |Duration |Avg HR |Notes
|
|
|
|
|
|
|22-Aug-08 |10:24 | 157 |
|
|
|
Worked out MSHR (max sustainable heart rate) by going hard
|
|
|
for this interval.
|
|
|
|
|
|
|22-Aug-08 |23:03 | 152 |
|
|
|
Back-to-back with previous interval.
|
|
|
|
|
|
|24-Aug-08 |40:00 | 145 |
|
|
|
Moderately hard interspersed with 3x 3min intervals (2min
|
|
|
hard + 1min really hard taking the HR up to 160).
|
|
|
|
|
|
|=========================================================
|
|
|
|
|
|
.AsciiDoc source
|
|
|
---------------------------------------------------------------------
|
|
|
.Windtrainer workouts
|
|
|
[width="80%",cols="3,^2,^2,10",options="header"]
|
|
|
|=========================================================
|
|
|
|Date |Duration |Avg HR |Notes
|
|
|
|
|
|
|22-Aug-08 |10:24 | 157 |
|
|
|
Worked out MSHR (max sustainable heart rate) by going hard
|
|
|
for this interval.
|
|
|
|
|
|
|22-Aug-08 |23:03 | 152 |
|
|
|
Back-to-back with previous interval.
|
|
|
|
|
|
|24-Aug-08 |40:00 | 145 |
|
|
|
Lorem Lorem Lorim Lorum Lorem 3x 3min intervals (2min
|
|
|
hard + 1min really hard taking the HR up to 160).
|
|
|
|
|
|
|=========================================================
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
.A table with externally sourced CSV data
|
|
|
[format="csv",cols="^1,4*2",options="header"]
|
|
|
|===================================================
|
|
|
ID,Customer Name,Contact Name,Customer Address,Phone
|
|
|
include::customers.csv[]
|
|
|
|===================================================
|
|
|
|
|
|
.AsciiDoc source
|
|
|
---------------------------------------------------------------------
|
|
|
[format="csv",cols="^1,4*2",options="header"]
|
|
|
|===================================================
|
|
|
ID,Customer Name,Contact Name,Customer Address,Phone
|
|
|
\include::example.csv[]
|
|
|
|===================================================
|
|
|
---------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
.Cell spans, alignments and styles
|
|
|
[cols="e,m,^,>s",width="25%"]
|
|
|
|============================
|
|
|
|1 >s|2 |3 |4
|
|
|
^|5 2.2+^.^|6 .3+<.>m|7
|
|
|
^|8
|
|
|
|9 2+>|10
|
|
|
|============================
|
|
|
|