| 1 | # AsciiDoc help file. |
|---|
| 2 | # |
|---|
| 3 | # INI section format, each section contains a topic. |
|---|
| 4 | # Displayed with 'asciidoc --help sectionname' command. |
|---|
| 5 | # |
|---|
| 6 | |
|---|
| 7 | # |
|---|
| 8 | # Default help topic. |
|---|
| 9 | # |
|---|
| 10 | [default] |
|---|
| 11 | |
|---|
| 12 | Man page: asciidoc --help manpage |
|---|
| 13 | Syntax: asciidoc --help syntax |
|---|
| 14 | |
|---|
| 15 | [manpage] |
|---|
| 16 | |
|---|
| 17 | NAME |
|---|
| 18 | |
|---|
| 19 | asciidoc - converts an AsciiDoc text file to HTML or DocBook |
|---|
| 20 | |
|---|
| 21 | SYNOPSIS |
|---|
| 22 | |
|---|
| 23 | asciidoc [OPTIONS] FILE |
|---|
| 24 | |
|---|
| 25 | DESCRIPTION |
|---|
| 26 | |
|---|
| 27 | The asciidoc(1) command translates the AsciiDoc text file FILE to |
|---|
| 28 | DocBook or HTML. If FILE is - then the standard input is used. |
|---|
| 29 | |
|---|
| 30 | OPTIONS |
|---|
| 31 | |
|---|
| 32 | -a, --attribute=ATTRIBUTE |
|---|
| 33 | Define or delete document attribute. ATTRIBUTE is formatted like |
|---|
| 34 | NAME=VALUE. Command-line attributes take precedence over |
|---|
| 35 | document and configuration file attributes. Alternate acceptable |
|---|
| 36 | forms are NAME (the VALUE defaults to an empty string); NAME! |
|---|
| 37 | (delete the NAME attribute); NAME=VALUE@ (do not override |
|---|
| 38 | document or configuration file attributes). Values containing |
|---|
| 39 | spaces should be enclosed in double-quote characters. This |
|---|
| 40 | option may be specified more than once. A special attribute |
|---|
| 41 | named trace controls the output of diagnostic information. |
|---|
| 42 | |
|---|
| 43 | -b, --backend=BACKEND |
|---|
| 44 | Backend output file format: docbook45, xhtml11, html4, html5, |
|---|
| 45 | slidy, wordpress or latex (the latex backend is experimental). |
|---|
| 46 | You can also use the backend alias names html (aliased to |
|---|
| 47 | xhtml11) or docbook (aliased to docbook45). Defaults to |
|---|
| 48 | html. The --backend option is also used to manage backend |
|---|
| 49 | plugins (see [1]PLUGIN COMMANDS). |
|---|
| 50 | |
|---|
| 51 | -f, --conf-file=CONF_FILE |
|---|
| 52 | Use configuration file CONF_FILE.Configuration files processed |
|---|
| 53 | in command-line order (after implicit configuration files). This |
|---|
| 54 | option may be specified more than once. |
|---|
| 55 | |
|---|
| 56 | --doctest |
|---|
| 57 | Run Python doctests in asciidoc module. |
|---|
| 58 | |
|---|
| 59 | -d, --doctype=DOCTYPE |
|---|
| 60 | Document type: article, manpage or book. The book document type |
|---|
| 61 | is only supported by the docbook backend. Default document type |
|---|
| 62 | is article. |
|---|
| 63 | |
|---|
| 64 | -c, --dump-conf |
|---|
| 65 | Dump configuration to stdout. |
|---|
| 66 | |
|---|
| 67 | --filter=FILTER |
|---|
| 68 | Specify the name of a filter to be loaded (used to load filters |
|---|
| 69 | that are not auto-loaded). This option may be specified more |
|---|
| 70 | than once. The --filter option is also used to manage filter |
|---|
| 71 | plugins (see [2]PLUGIN COMMANDS). |
|---|
| 72 | |
|---|
| 73 | -h, --help [TOPIC] |
|---|
| 74 | Print help TOPIC. --help topics will print a list of help |
|---|
| 75 | topics, --help syntax summarizes AsciiDoc syntax, --help manpage |
|---|
| 76 | prints the AsciiDoc manpage. |
|---|
| 77 | |
|---|
| 78 | -e, --no-conf |
|---|
| 79 | Exclude implicitly loaded configuration files except for those |
|---|
| 80 | named like the input file (infile.conf and infile-backend.conf). |
|---|
| 81 | |
|---|
| 82 | -s, --no-header-footer |
|---|
| 83 | Suppress document header and footer output. |
|---|
| 84 | |
|---|
| 85 | -o, --out-file=OUT_FILE |
|---|
| 86 | Write output to file OUT_FILE. Defaults to the base name of |
|---|
| 87 | input file with backend extension. If the input is stdin then |
|---|
| 88 | the outfile defaults to stdout. If OUT_FILE is - then the |
|---|
| 89 | standard output is used. |
|---|
| 90 | |
|---|
| 91 | -n, --section-numbers |
|---|
| 92 | Auto-number HTML article section titles. Synonym for --attribute |
|---|
| 93 | numbered. |
|---|
| 94 | |
|---|
| 95 | --safe |
|---|
| 96 | Enable safe mode. Safe mode is disabled by default. AsciiDoc |
|---|
| 97 | safe mode skips potentially dangerous scripted sections in |
|---|
| 98 | AsciiDoc source files. |
|---|
| 99 | |
|---|
| 100 | --theme=THEME |
|---|
| 101 | Specify a theme name. Synonym for --attribute theme=THEME. The |
|---|
| 102 | --theme option is also used to manage theme plugins (see |
|---|
| 103 | [3]PLUGIN COMMANDS). |
|---|
| 104 | |
|---|
| 105 | -v, --verbose |
|---|
| 106 | Verbosely print processing information and configuration file |
|---|
| 107 | checks to stderr. |
|---|
| 108 | |
|---|
| 109 | --version |
|---|
| 110 | Print program version number. |
|---|
| 111 | |
|---|
| 112 | PLUGIN COMMANDS |
|---|
| 113 | |
|---|
| 114 | The asciidoc(1) --filter, --backend and --theme options are used to |
|---|
| 115 | install, remove and list AsciiDoc filter, backend and theme plugins. |
|---|
| 116 | Syntax: |
|---|
| 117 | |
|---|
| 118 | asciidoc OPTION install ZIP_FILE [PLUGINS_DIR] |
|---|
| 119 | asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR] |
|---|
| 120 | asciidoc OPTION list |
|---|
| 121 | asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE |
|---|
| 122 | |
|---|
| 123 | Where: |
|---|
| 124 | |
|---|
| 125 | OPTION |
|---|
| 126 | asciidoc(1) --filter, --backend or --theme option specifying the |
|---|
| 127 | type of plugin. |
|---|
| 128 | |
|---|
| 129 | PLUGIN_NAME |
|---|
| 130 | A unique plugin name containing only alphanumeric or underscore |
|---|
| 131 | characters. |
|---|
| 132 | |
|---|
| 133 | ZIP_FILE |
|---|
| 134 | A Zip file containing plugin resources, the name must start with |
|---|
| 135 | the plugin name e.g. my_filter-1.0.zip packages filter |
|---|
| 136 | my_filter. |
|---|
| 137 | |
|---|
| 138 | PLUGINS_DIR |
|---|
| 139 | The directory containing installed plugins. Each plugin is |
|---|
| 140 | contained in its own separate subdirectory which has the same |
|---|
| 141 | name as the plugin. PLUGINS_DIR defaults to the |
|---|
| 142 | $HOME/.asciidoc/filters (for filter plugins) or |
|---|
| 143 | $HOME/.asciidoc/backends (for backend plugins) or |
|---|
| 144 | $HOME/.asciidoc/themes (for theme plugins). |
|---|
| 145 | |
|---|
| 146 | PLUGIN_SOURCE |
|---|
| 147 | The name of a directory containing the plugin source files or |
|---|
| 148 | the name of a single source file. |
|---|
| 149 | |
|---|
| 150 | The plugin commands perform as follows: |
|---|
| 151 | |
|---|
| 152 | install |
|---|
| 153 | Create a subdirectory in PLUGINS_DIR with the same name as the |
|---|
| 154 | plugin then extract the ZIP_FILE into it. |
|---|
| 155 | |
|---|
| 156 | remove |
|---|
| 157 | Delete the PLUGIN_NAME plugin subdirectory and all its contents |
|---|
| 158 | from the PLUGINS_DIR. |
|---|
| 159 | |
|---|
| 160 | list |
|---|
| 161 | List the names and locations of all installed filter or theme |
|---|
| 162 | plugins (including standard plugins installed in the global |
|---|
| 163 | configuration directory). |
|---|
| 164 | |
|---|
| 165 | build |
|---|
| 166 | Create a plugin file named ZIP_FILE containing the files and |
|---|
| 167 | subdirectories specified by PLUGIN_SOURCE. File and directory |
|---|
| 168 | names starting with a period are skipped. |
|---|
| 169 | |
|---|
| 170 | EXIT STATUS |
|---|
| 171 | |
|---|
| 172 | 0 |
|---|
| 173 | Success |
|---|
| 174 | |
|---|
| 175 | 1 |
|---|
| 176 | Failure (syntax or usage error; configuration error; document |
|---|
| 177 | processing failure; unexpected error). |
|---|
| 178 | |
|---|
| 179 | BUGS |
|---|
| 180 | |
|---|
| 181 | See the AsciiDoc distribution BUGS file. |
|---|
| 182 | |
|---|
| 183 | AUTHOR |
|---|
| 184 | |
|---|
| 185 | AsciiDoc was originally written by Stuart Rackham. Many people have |
|---|
| 186 | contributed to it. |
|---|
| 187 | |
|---|
| 188 | RESOURCES |
|---|
| 189 | |
|---|
| 190 | SourceForge: [4]http://sourceforge.net/projects/asciidoc/ |
|---|
| 191 | |
|---|
| 192 | Main web site: [5]http://asciidoc.org/ |
|---|
| 193 | |
|---|
| 194 | COPYING |
|---|
| 195 | |
|---|
| 196 | Copyright (C) 2002-2011 Stuart Rackham. Free use of this software is |
|---|
| 197 | granted under the terms of the GNU General Public License (GPL). |
|---|
| 198 | |
|---|
| 199 | |
|---|
| 200 | [syntax] |
|---|
| 201 | |
|---|
| 202 | AsciiDoc Markup Syntax Summary |
|---|
| 203 | ============================== |
|---|
| 204 | |
|---|
| 205 | A summary of the most commonly used markup. |
|---|
| 206 | For a complete reference see the 'AsciiDoc User Guide'. |
|---|
| 207 | |
|---|
| 208 | Text formatting |
|---|
| 209 | --------------- |
|---|
| 210 | *bold text* (boldface font) |
|---|
| 211 | _emphasized text_ (normally italics) |
|---|
| 212 | 'emphasized text' |
|---|
| 213 | +monospaced text+ (proportional font) |
|---|
| 214 | `monospaced text` (inline literal passthrough) |
|---|
| 215 | |
|---|
| 216 | Document links |
|---|
| 217 | -------------- |
|---|
| 218 | [[id]] (define link target) |
|---|
| 219 | <<id,caption>> (link to target id) |
|---|
| 220 | link:filename#id[caption] (link to external HTML file) |
|---|
| 221 | |
|---|
| 222 | URLs |
|---|
| 223 | ---- |
|---|
| 224 | Use normal URL and email addess syntax or: |
|---|
| 225 | |
|---|
| 226 | http:address[caption] (link to web page) |
|---|
| 227 | mailto:address[caption] (link to mail recipient) |
|---|
| 228 | |
|---|
| 229 | Images |
|---|
| 230 | ------ |
|---|
| 231 | image:filename[caption] (inline image) |
|---|
| 232 | image::filename[caption] (block image) |
|---|
| 233 | |
|---|
| 234 | Document header |
|---|
| 235 | --------------- |
|---|
| 236 | |
|---|
| 237 | The Document Title |
|---|
| 238 | ================== |
|---|
| 239 | author <email> |
|---|
| 240 | revision, date |
|---|
| 241 | |
|---|
| 242 | author, email, revision and date are optional. |
|---|
| 243 | |
|---|
| 244 | Section title underlines |
|---|
| 245 | ------------------------ |
|---|
| 246 | Underlined: |
|---|
| 247 | |
|---|
| 248 | Level 0 (document title) |
|---|
| 249 | ======= |
|---|
| 250 | Level 1 |
|---|
| 251 | ------- |
|---|
| 252 | Level 2 |
|---|
| 253 | ~~~~~~~ |
|---|
| 254 | Level 3 |
|---|
| 255 | ^^^^^^^ |
|---|
| 256 | Level 4 (bottom level) |
|---|
| 257 | +++++++ |
|---|
| 258 | |
|---|
| 259 | Single line: |
|---|
| 260 | |
|---|
| 261 | = Level 0 = (document title) |
|---|
| 262 | == Level 1 == |
|---|
| 263 | === Level 2 === |
|---|
| 264 | ==== Level 3 ==== |
|---|
| 265 | ===== Level 4 ===== (bottom level) |
|---|
| 266 | |
|---|
| 267 | Paragraphs |
|---|
| 268 | ---------- |
|---|
| 269 | A normal paragraph. (styles: literal,verse,quote,listing, |
|---|
| 270 | NOTE,TIP,WARNING,IMPORTANT,CAUTION) |
|---|
| 271 | An indented literal |
|---|
| 272 | paragraph. |
|---|
| 273 | |
|---|
| 274 | Delimited blocks |
|---|
| 275 | ---------------- |
|---|
| 276 | Delimiters must begin at left margin. |
|---|
| 277 | |
|---|
| 278 | ------------------- (styles: source,music,graphviz) |
|---|
| 279 | listing block |
|---|
| 280 | ------------------- |
|---|
| 281 | |
|---|
| 282 | ................... (styles: listing,verse) |
|---|
| 283 | literal block |
|---|
| 284 | ................... |
|---|
| 285 | |
|---|
| 286 | ******************* |
|---|
| 287 | sidebar block |
|---|
| 288 | ******************* |
|---|
| 289 | |
|---|
| 290 | [style, author, cite] |
|---|
| 291 | ___________________ (styles: quote,verse) |
|---|
| 292 | quote block |
|---|
| 293 | ___________________ |
|---|
| 294 | |
|---|
| 295 | =================== (styles: NOTE,TIP,WARNING, |
|---|
| 296 | example block IMPORTANT,CAUTION) |
|---|
| 297 | =================== |
|---|
| 298 | |
|---|
| 299 | /////////////////// |
|---|
| 300 | comment block |
|---|
| 301 | /////////////////// |
|---|
| 302 | |
|---|
| 303 | +++++++++++++++++++ (styles: pass,asciimath,latexmath) |
|---|
| 304 | passthrough block |
|---|
| 305 | +++++++++++++++++++ |
|---|
| 306 | |
|---|
| 307 | [style] (styles: abstract,partintro) |
|---|
| 308 | -- |
|---|
| 309 | open block |
|---|
| 310 | -- |
|---|
| 311 | |
|---|
| 312 | More block elements |
|---|
| 313 | ------------------- |
|---|
| 314 | [attributes list] |
|---|
| 315 | .Block title |
|---|
| 316 | // Comment line |
|---|
| 317 | include::filename[] |
|---|
| 318 | |
|---|
| 319 | Tables |
|---|
| 320 | ------ |
|---|
| 321 | .An example table |
|---|
| 322 | [width="40%",cols="^,2m",frame="topbot",options="header,footer"] |
|---|
| 323 | |====================== |
|---|
| 324 | |Column 1 |Column 2 |
|---|
| 325 | |1 |Item 1 |
|---|
| 326 | |2 |Item 2 |
|---|
| 327 | |3 |Item 3 |
|---|
| 328 | |6 |Three items |
|---|
| 329 | |====================== |
|---|
| 330 | |
|---|
| 331 | Common attributes: |
|---|
| 332 | |
|---|
| 333 | grid: none,cols,rows,all |
|---|
| 334 | frame: topbot,none,sides,all |
|---|
| 335 | options: header,footer |
|---|
| 336 | format: psv,csv,dsv |
|---|
| 337 | valign: top,bottom,middle |
|---|
| 338 | width: 1%..100% |
|---|
| 339 | cols: colspec[,colspec,...] |
|---|
| 340 | |
|---|
| 341 | colspec: [multiplier*][align][width][style] |
|---|
| 342 | multiplier: 1... |
|---|
| 343 | width: 1... or 1%...100% |
|---|
| 344 | align: [horiz][.vert] |
|---|
| 345 | horiz: < (left), ^ (center), > (right) |
|---|
| 346 | vert: < (top), ^ (middle), > (bottom) |
|---|
| 347 | style: d[efault], e[mphasis], m[onospaced], a[sciidoc], |
|---|
| 348 | s[trong], l[iteral], v[erse], h[eader] |
|---|
| 349 | cell: [cellspec]|data |
|---|
| 350 | cellspec: [span*|+][align][style] |
|---|
| 351 | span: [colspan][.rowspan] |
|---|
| 352 | colspan: 1... |
|---|
| 353 | rowspan: 1... |
|---|
| 354 | |
|---|
| 355 | Bulleted lists |
|---|
| 356 | -------------- |
|---|
| 357 | - item text |
|---|
| 358 | * item text |
|---|
| 359 | ** item text |
|---|
| 360 | *** item text |
|---|
| 361 | **** item text |
|---|
| 362 | ***** item text |
|---|
| 363 | |
|---|
| 364 | (styles: callout,bibliography) |
|---|
| 365 | |
|---|
| 366 | Numbered lists |
|---|
| 367 | -------------- |
|---|
| 368 | 1. arabic (decimal) numbering |
|---|
| 369 | a. loweralpha numbering |
|---|
| 370 | F. upperalpha numbering |
|---|
| 371 | iii) lowerroman numbering |
|---|
| 372 | IX) upperroman numbering |
|---|
| 373 | |
|---|
| 374 | . arabic (decimal) numbering |
|---|
| 375 | .. loweralpha numbering |
|---|
| 376 | ... lowerroman numbering |
|---|
| 377 | .... upperalpha numbering |
|---|
| 378 | ..... upperroman numbering |
|---|
| 379 | |
|---|
| 380 | (styles: arabic,loweralpha,upperalpha,lowerroman,upperroman) |
|---|
| 381 | |
|---|
| 382 | Labeled lists |
|---|
| 383 | ------------- |
|---|
| 384 | label:: item text |
|---|
| 385 | label;; item text |
|---|
| 386 | label::: item text |
|---|
| 387 | label:::: item text |
|---|
| 388 | |
|---|
| 389 | (styles: horizontal,vertical,glossary,qanda,bibliograpy) |
|---|
| 390 | |
|---|
| 391 | More inline elements |
|---|
| 392 | -------------------- |
|---|
| 393 | footnote:[footnote text] (document footnote) |
|---|
| 394 | |
|---|
![[RTEMS Logo]](/images/logo.png){kind=logo}
