path: root/doc/asciidoc/help.conf

# 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://www.methods.co.nz/asciidoc/

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)