ASCIIDOC3(1)
===========


NAME
----
asciidoc3 - converts an AsciiDoc3 text file to HTML or DocBook45
or DocBook51


SYNOPSIS
--------
*asciidoc3* ['OPTIONS'] 'FILE'


DESCRIPTION
-----------
The asciidoc3(1) command translates the AsciiDoc3 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', 'docbook51', 'xhtml11',
    'html4', 'html5', 'slidy', 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 <<X1,*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 'asciidoc3' 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 <<X1,*PLUGIN COMMANDS*>>).

*-h, --help* ['TOPIC']::
    Print help TOPIC. *--help* 'topics' will print a list of help
    topics, *--help* 'syntax' summarizes AsciiDoc3 syntax,
    *--help* 'manpage' prints the AsciiDoc3 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.  AsciiDoc3
    'safe mode' skips potentially dangerous scripted sections in
    AsciiDoc3 source files.

*--theme*='THEME'::
    Specify a theme name.  Synonym for *--attribute theme*='THEME'.
    The *--theme* option is also used to manage theme plugins (see
    <<X1,*PLUGIN COMMANDS*>>).

*-v, --verbose*::
    Verbosely print processing information and configuration file
    checks to stderr.

*--version*::
    Print program version number.


[[X1]]
PLUGIN COMMANDS
---------------
The asciidoc3(1) *--filter*, *--backend* and *--theme* options are used
to install, remove and list AsciiDoc3 filter, backend and theme
plugins. Syntax:

  asciidoc3 OPTION install ZIP_FILE [PLUGINS_DIR]
  asciidoc3 OPTION remove PLUGIN_NAME [PLUGINS_DIR]
  asciidoc3 OPTION list
  asciidoc3 OPTION build ZIP_FILE PLUGIN_SOURCE

Where:

*OPTION*::
  asciidoc3(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/.asciidoc3/filters` (for
  filter plugins) or `$HOME/.asciidoc3/backends` (for backend plugins) or
  `$HOME/.asciidoc3/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 AsciiDoc3 distribution BUGS file.


AUTHOR
------
AsciiDoc was originally written by Stuart Rackham. Many people have
contributed to it. Porting to Python3 (AsciiDoc3) and additional work
was done by Berthold Gehrke berthold.gehrke@gmail.com


RESOURCES
---------
Main web site: <https://asciidoc3.org/>


COPYING
-------
Copyright \(C) 2002-2011 Stuart Rackham.
Copyright \(C) 2018-2020 Berthold Gehrke. Free use of this software
is granted under the terms of the GNU General Public License v2 
GPLv2 or (at your option) any later version.
