1 | ASCIIDOC(1) |
---|
2 | =========== |
---|
3 | :doctype: manpage |
---|
4 | |
---|
5 | |
---|
6 | NAME |
---|
7 | ---- |
---|
8 | asciidoc - converts an AsciiDoc text file to HTML or DocBook |
---|
9 | |
---|
10 | |
---|
11 | SYNOPSIS |
---|
12 | -------- |
---|
13 | *asciidoc* ['OPTIONS'] 'FILE' |
---|
14 | |
---|
15 | |
---|
16 | DESCRIPTION |
---|
17 | ----------- |
---|
18 | The asciidoc(1) command translates the AsciiDoc text file 'FILE' to |
---|
19 | DocBook or HTML. If 'FILE' is '-' then the standard input is used. |
---|
20 | |
---|
21 | |
---|
22 | OPTIONS |
---|
23 | ------- |
---|
24 | *-a, --attribute*='ATTRIBUTE':: |
---|
25 | Define or delete document attribute. 'ATTRIBUTE' is formatted like |
---|
26 | 'NAME=VALUE'. Command-line attributes take precedence over |
---|
27 | document and configuration file attributes. Alternate acceptable |
---|
28 | forms are 'NAME' (the 'VALUE' defaults to an empty string); |
---|
29 | 'NAME!' (delete the 'NAME' attribute); 'NAME=VALUE@' (do not override |
---|
30 | document or configuration file attributes). Values containing |
---|
31 | spaces should be enclosed in double-quote characters. This option |
---|
32 | may be specified more than once. A special attribute named |
---|
33 | 'trace' controls the output of diagnostic information. |
---|
34 | |
---|
35 | *-b, --backend*='BACKEND':: |
---|
36 | Backend output file format: 'docbook45', 'xhtml11', 'html4', |
---|
37 | 'html5', 'slidy', 'wordpress' or 'latex' (the 'latex' backend is |
---|
38 | experimental). You can also use the backend alias names 'html' |
---|
39 | (aliased to 'xhtml11') or 'docbook' (aliased to 'docbook45'). |
---|
40 | Defaults to 'html'. The *--backend* option is also used to manage |
---|
41 | backend plugins (see <<X1,*PLUGIN COMMANDS*>>). |
---|
42 | |
---|
43 | *-f, --conf-file*='CONF_FILE':: |
---|
44 | Use configuration file 'CONF_FILE'.Configuration files processed |
---|
45 | in command-line order (after implicit configuration files). This |
---|
46 | option may be specified more than once. |
---|
47 | |
---|
48 | *--doctest*:: |
---|
49 | Run Python doctests in 'asciidoc' module. |
---|
50 | |
---|
51 | *-d, --doctype*='DOCTYPE':: |
---|
52 | Document type: 'article', 'manpage' or 'book'. The 'book' document |
---|
53 | type is only supported by the 'docbook' backend. Default document |
---|
54 | type is 'article'. |
---|
55 | |
---|
56 | *-c, --dump-conf*:: |
---|
57 | Dump configuration to stdout. |
---|
58 | |
---|
59 | *--filter*='FILTER':: |
---|
60 | Specify the name of a filter to be loaded (used to load filters |
---|
61 | that are not auto-loaded). This option may be specified more than |
---|
62 | once. The *--filter* option is also used to manage filter plugins |
---|
63 | (see <<X1,*PLUGIN COMMANDS*>>). |
---|
64 | |
---|
65 | *-h, --help* ['TOPIC']:: |
---|
66 | Print help TOPIC. *--help* 'topics' will print a list of help |
---|
67 | topics, *--help* 'syntax' summarizes AsciiDoc syntax, |
---|
68 | *--help* 'manpage' prints the AsciiDoc manpage. |
---|
69 | |
---|
70 | *-e, --no-conf*:: |
---|
71 | Exclude implicitly loaded configuration files except for those |
---|
72 | named like the input file ('infile.conf' and |
---|
73 | 'infile-backend.conf'). |
---|
74 | |
---|
75 | *-s, --no-header-footer*:: |
---|
76 | Suppress document header and footer output. |
---|
77 | |
---|
78 | *-o, --out-file*='OUT_FILE':: |
---|
79 | Write output to file 'OUT_FILE'. Defaults to the base name of |
---|
80 | input file with 'backend' extension. If the input is stdin then |
---|
81 | the outfile defaults to stdout. If 'OUT_FILE' is '-' then the |
---|
82 | standard output is used. |
---|
83 | |
---|
84 | *-n, --section-numbers*:: |
---|
85 | Auto-number HTML article section titles. Synonym for |
---|
86 | *--attribute numbered*. |
---|
87 | |
---|
88 | *--safe*:: |
---|
89 | Enable safe mode. Safe mode is disabled by default. AsciiDoc |
---|
90 | 'safe mode' skips potentially dangerous scripted sections in |
---|
91 | AsciiDoc source files. |
---|
92 | |
---|
93 | *--theme*='THEME':: |
---|
94 | Specify a theme name. Synonym for *--attribute theme*='THEME'. |
---|
95 | The *--theme* option is also used to manage theme plugins (see |
---|
96 | <<X1,*PLUGIN COMMANDS*>>). |
---|
97 | |
---|
98 | *-v, --verbose*:: |
---|
99 | Verbosely print processing information and configuration file |
---|
100 | checks to stderr. |
---|
101 | |
---|
102 | *--version*:: |
---|
103 | Print program version number. |
---|
104 | |
---|
105 | |
---|
106 | [[X1]] |
---|
107 | PLUGIN COMMANDS |
---|
108 | --------------- |
---|
109 | The asciidoc(1) *--filter*, *--backend* and *--theme* options are used |
---|
110 | to install, remove and list AsciiDoc filter, backend and theme |
---|
111 | plugins. Syntax: |
---|
112 | |
---|
113 | asciidoc OPTION install ZIP_FILE [PLUGINS_DIR] |
---|
114 | asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR] |
---|
115 | asciidoc OPTION list |
---|
116 | asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE |
---|
117 | |
---|
118 | Where: |
---|
119 | |
---|
120 | *OPTION*:: |
---|
121 | asciidoc(1) *--filter*, *--backend* or *--theme* option specifying |
---|
122 | the type of plugin. |
---|
123 | |
---|
124 | *PLUGIN_NAME*:: |
---|
125 | A unique plugin name containing only alphanumeric or underscore |
---|
126 | characters. |
---|
127 | |
---|
128 | *ZIP_FILE*:: |
---|
129 | A Zip file containing plugin resources, the name must start with the |
---|
130 | plugin name e.g. `my_filter-1.0.zip` packages filter `my_filter`. |
---|
131 | |
---|
132 | *PLUGINS_DIR*:: |
---|
133 | The directory containing installed plugins. Each plugin is contained |
---|
134 | in its own separate subdirectory which has the same name as the |
---|
135 | plugin. |
---|
136 | *PLUGINS_DIR* defaults to the `$HOME/.asciidoc/filters` (for |
---|
137 | filter plugins) or `$HOME/.asciidoc/backends` (for backend plugins) or |
---|
138 | `$HOME/.asciidoc/themes` (for theme plugins). |
---|
139 | |
---|
140 | *PLUGIN_SOURCE*:: |
---|
141 | The name of a directory containing the plugin source files or the |
---|
142 | name of a single source file. |
---|
143 | |
---|
144 | The plugin commands perform as follows: |
---|
145 | |
---|
146 | *install*:: |
---|
147 | Create a subdirectory in *PLUGINS_DIR* with the same name as the |
---|
148 | plugin then extract the *ZIP_FILE* into it. |
---|
149 | |
---|
150 | *remove*:: |
---|
151 | Delete the *PLUGIN_NAME* plugin subdirectory and all its contents |
---|
152 | from the *PLUGINS_DIR*. |
---|
153 | |
---|
154 | *list*:: |
---|
155 | List the names and locations of all installed filter or theme |
---|
156 | plugins (including standard plugins installed in the global |
---|
157 | configuration directory). |
---|
158 | |
---|
159 | *build*:: |
---|
160 | Create a plugin file named *ZIP_FILE* containing the files and |
---|
161 | subdirectories specified by *PLUGIN_SOURCE*. File and directory |
---|
162 | names starting with a period are skipped. |
---|
163 | |
---|
164 | |
---|
165 | EXIT STATUS |
---|
166 | ----------- |
---|
167 | *0*:: |
---|
168 | Success |
---|
169 | |
---|
170 | *1*:: |
---|
171 | Failure (syntax or usage error; configuration error; document |
---|
172 | processing failure; unexpected error). |
---|
173 | |
---|
174 | |
---|
175 | BUGS |
---|
176 | ---- |
---|
177 | See the AsciiDoc distribution BUGS file. |
---|
178 | |
---|
179 | |
---|
180 | AUTHOR |
---|
181 | ------ |
---|
182 | AsciiDoc was originally written by Stuart Rackham. Many people have |
---|
183 | contributed to it. |
---|
184 | |
---|
185 | |
---|
186 | RESOURCES |
---|
187 | --------- |
---|
188 | SourceForge: <http://sourceforge.net/projects/asciidoc/> |
---|
189 | |
---|
190 | Main web site: <http://www.methods.co.nz/asciidoc/> |
---|
191 | |
---|
192 | |
---|
193 | COPYING |
---|
194 | ------- |
---|
195 | Copyright \(C) 2002-2011 Stuart Rackham. Free use of this software is |
---|
196 | granted under the terms of the GNU General Public License (GPL). |
---|
197 | |
---|