ASCIIDOC(1) =========== :doctype: 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', 'docbook5', '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 <>). *-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' backends. 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 <>). *-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 <>). *-v, --verbose*:: Verbosely print processing information and configuration file checks to stderr. *--version*:: Print program version number. [[X1]] 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. ENVIRONMENT VARIABLES --------------------- *`SOURCE_DATE_EPOCH`*:: If the `SOURCE_DATE_EPOCH` environment variable is set to a UNIX timestamp, then the `{docdate}`, `{doctime}`, `{localdate}`, and `{localtime}` attributes are computed in the UTC time zone, with any timestamps newer than `SOURCE_DATE_EPOCH` replaced by `SOURCE_DATE_EPOCH`. (This helps software using AsciiDoc to build reproducibly.) EXAMPLES -------- `asciidoc asciidoc_file_name.txt`:: Simply generate an html file from the asciidoc_file_name.txt that is in current directory using asciidoc. `asciidoc -b html5 asciidoc_file_name.txt`:: Use the `-b` switch to use one of the proposed backend or another one you installed on your computer. `asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt`:: Use the `-a` switch to set attributes from command-line. AsciiDoc generated its stand-alone HTML user guide containing embedded CSS, JavaScript and images from the AsciiDoc article template with this command. `asciidoc -b html5 -d manpage asciidoc.1.txt`:: Generating the asciidoc manpage using the html5 backend. 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 --------- GitHub: Main web site: SEE ALSO -------- a2x(1) COPYING ------- Copyright \(C) 2002-2013 Stuart Rackham. Copyright \(C) 2013-2022 AsciiDoc Contributors. Free use of this software is granted under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.