Blame | Last modification | View Log | RSS feed
# AsciiDoc help file.
#
# INI section format, each section contains a topic.
# Displayed with 'asciidoc --help sectionname' command.
#
#
# Default help topic.
#
[default]
Man page: asciidoc --help manpage
Syntax: asciidoc --help syntax
[manpage]
NAME
asciidoc - converts an AsciiDoc text file to HTML or DocBook
SYNOPSIS
asciidoc [OPTIONS] FILE
DESCRIPTION
The asciidoc(1) command translates the AsciiDoc text file FILE to
DocBook or HTML. If FILE is - then the standard input is used.
OPTIONS
-a, --attribute=ATTRIBUTE
Define or delete document attribute. ATTRIBUTE is formatted like
NAME=VALUE. Command-line attributes take precedence over
document and configuration file attributes. Alternate acceptable
forms are NAME (the VALUE defaults to an empty string); NAME!
(delete the NAME attribute); NAME=VALUE@ (do not override
document or configuration file attributes). Values containing
spaces should be enclosed in double-quote characters. This
option may be specified more than once. A special attribute
named trace controls the output of diagnostic information.
-b, --backend=BACKEND
Backend output file format: docbook45, xhtml11, html4, html5,
slidy, wordpress or latex (the latex backend is experimental).
You can also use the backend alias names html (aliased to
xhtml11) or docbook (aliased to docbook45). Defaults to
html. The --backend option is also used to manage backend
plugins (see [1]PLUGIN COMMANDS).
-f, --conf-file=CONF_FILE
Use configuration file CONF_FILE.Configuration files processed
in command-line order (after implicit configuration files). This
option may be specified more than once.
--doctest
Run Python doctests in asciidoc module.
-d, --doctype=DOCTYPE
Document type: article, manpage or book. The book document type
is only supported by the docbook backend. Default document type
is article.
-c, --dump-conf
Dump configuration to stdout.
--filter=FILTER
Specify the name of a filter to be loaded (used to load filters
that are not auto-loaded). This option may be specified more
than once. The --filter option is also used to manage filter
plugins (see [2]PLUGIN COMMANDS).
-h, --help [TOPIC]
Print help TOPIC. --help topics will print a list of help
topics, --help syntax summarizes AsciiDoc syntax, --help manpage
prints the AsciiDoc manpage.
-e, --no-conf
Exclude implicitly loaded configuration files except for those
named like the input file (infile.conf and infile-backend.conf).
-s, --no-header-footer
Suppress document header and footer output.
-o, --out-file=OUT_FILE
Write output to file OUT_FILE. Defaults to the base name of
input file with backend extension. If the input is stdin then
the outfile defaults to stdout. If OUT_FILE is - then the
standard output is used.
-n, --section-numbers
Auto-number HTML article section titles. Synonym for --attribute
numbered.
--safe
Enable safe mode. Safe mode is disabled by default. AsciiDoc
safe mode skips potentially dangerous scripted sections in
AsciiDoc source files.
--theme=THEME
Specify a theme name. Synonym for --attribute theme=THEME. The
--theme option is also used to manage theme plugins (see
[3]PLUGIN COMMANDS).
-v, --verbose
Verbosely print processing information and configuration file
checks to stderr.
--version
Print program version number.
PLUGIN COMMANDS
The asciidoc(1) --filter, --backend and --theme options are used to
install, remove and list AsciiDoc filter, backend and theme plugins.
Syntax:
asciidoc OPTION install ZIP_FILE [PLUGINS_DIR]
asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR]
asciidoc OPTION list
asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE
Where:
OPTION
asciidoc(1) --filter, --backend or --theme option specifying the
type of plugin.
PLUGIN_NAME
A unique plugin name containing only alphanumeric or underscore
characters.
ZIP_FILE
A Zip file containing plugin resources, the name must start with
the plugin name e.g. my_filter-1.0.zip packages filter
my_filter.
PLUGINS_DIR
The directory containing installed plugins. Each plugin is
contained in its own separate subdirectory which has the same
name as the plugin. PLUGINS_DIR defaults to the
$HOME/.asciidoc/filters (for filter plugins) or
$HOME/.asciidoc/backends (for backend plugins) or
$HOME/.asciidoc/themes (for theme plugins).
PLUGIN_SOURCE
The name of a directory containing the plugin source files or
the name of a single source file.
The plugin commands perform as follows:
install
Create a subdirectory in PLUGINS_DIR with the same name as the
plugin then extract the ZIP_FILE into it.
remove
Delete the PLUGIN_NAME plugin subdirectory and all its contents
from the PLUGINS_DIR.
list
List the names and locations of all installed filter or theme
plugins (including standard plugins installed in the global
configuration directory).
build
Create a plugin file named ZIP_FILE containing the files and
subdirectories specified by PLUGIN_SOURCE. File and directory
names starting with a period are skipped.
EXIT STATUS
0
Success
1
Failure (syntax or usage error; configuration error; document
processing failure; unexpected error).
BUGS
See the AsciiDoc distribution BUGS file.
AUTHOR
AsciiDoc was originally written by Stuart Rackham. Many people have
contributed to it.
RESOURCES
SourceForge: [4]http://sourceforge.net/projects/asciidoc/
Main web site: [5]http://asciidoc.org/
COPYING
Copyright (C) 2002-2011 Stuart Rackham. Free use of this software is
granted under the terms of the GNU General Public License (GPL).
[syntax]
AsciiDoc Markup Syntax Summary
==============================
A summary of the most commonly used markup.
For a complete reference see the 'AsciiDoc User Guide'.
Text formatting
---------------
*bold text* (boldface font)
_emphasized text_ (normally italics)
'emphasized text'
+monospaced text+ (proportional font)
`monospaced text` (inline literal passthrough)
Document links
--------------
[[id]] (define link target)
<<id,caption>> (link to target id)
link:filename#id[caption] (link to external HTML file)
URLs
----
Use normal URL and email addess syntax or:
http:address[caption] (link to web page)
mailto:address[caption] (link to mail recipient)
Images
------
image:filename[caption] (inline image)
image::filename[caption] (block image)
Document header
---------------
The Document Title
==================
author <email>
revision, date
author, email, revision and date are optional.
Section title underlines
------------------------
Underlined:
Level 0 (document title)
=======
Level 1
-------
Level 2
~~~~~~~
Level 3
^^^^^^^
Level 4 (bottom level)
+++++++
Single line:
= Level 0 = (document title)
== Level 1 ==
=== Level 2 ===
==== Level 3 ====
===== Level 4 ===== (bottom level)
Paragraphs
----------
A normal paragraph. (styles: literal,verse,quote,listing,
NOTE,TIP,WARNING,IMPORTANT,CAUTION)
An indented literal
paragraph.
Delimited blocks
----------------
Delimiters must begin at left margin.
------------------- (styles: source,music,graphviz)
listing block
-------------------
................... (styles: listing,verse)
literal block
...................
*******************
sidebar block
*******************
[style, author, cite]
___________________ (styles: quote,verse)
quote block
___________________
=================== (styles: NOTE,TIP,WARNING,
example block IMPORTANT,CAUTION)
===================
///////////////////
comment block
///////////////////
+++++++++++++++++++ (styles: pass,asciimath,latexmath)
passthrough block
+++++++++++++++++++
[style] (styles: abstract,partintro)
--
open block
--
More block elements
-------------------
[attributes list]
.Block title
// Comment line
include::filename[]
Tables
------
.An example table
[width="40%",cols="^,2m",frame="topbot",options="header,footer"]
|======================
|Column 1 |Column 2
|1 |Item 1
|2 |Item 2
|3 |Item 3
|6 |Three items
|======================
Common attributes:
grid: none,cols,rows,all
frame: topbot,none,sides,all
options: header,footer
format: psv,csv,dsv
valign: top,bottom,middle
width: 1%..100%
cols: colspec[,colspec,...]
colspec: [multiplier*][align][width][style]
multiplier: 1...
width: 1... or 1%...100%
align: [horiz][.vert]
horiz: < (left), ^ (center), > (right)
vert: < (top), ^ (middle), > (bottom)
style: d[efault], e[mphasis], m[onospaced], a[sciidoc],
s[trong], l[iteral], v[erse], h[eader]
cell: [cellspec]|data
cellspec: [span*|+][align][style]
span: [colspan][.rowspan]
colspan: 1...
rowspan: 1...
Bulleted lists
--------------
- item text
* item text
** item text
*** item text
**** item text
***** item text
(styles: callout,bibliography)
Numbered lists
--------------
1. arabic (decimal) numbering
a. loweralpha numbering
F. upperalpha numbering
iii) lowerroman numbering
IX) upperroman numbering
. arabic (decimal) numbering
.. loweralpha numbering
... lowerroman numbering
.... upperalpha numbering
..... upperroman numbering
(styles: arabic,loweralpha,upperalpha,lowerroman,upperroman)
Labeled lists
-------------
label:: item text
label;; item text
label::: item text
label:::: item text
(styles: horizontal,vertical,glossary,qanda,bibliograpy)
More inline elements
--------------------
footnote:[footnote text] (document footnote)