Skip to content
100644 793 lines (637 sloc) 29.8 KB
694b268 @mojombo add asciidoc example
1 AsciiDoc User Guide
2 ===================
4 AsciiDoc is a text document format for writing documentation,
5 articles, manuals, books and UNIX man pages. AsciiDoc files can be
6 translated to HTML and DocBook markups using the asciidoc(1) command.
7 AsciiDoc is highly configurable: both the AsciiDoc source file syntax
8 and the backend output markups (which can be almost any type of
9 SGML/XML markup) can be customized and extended by the user.
11 Introduction
12 ------------
13 **********************************************************************
14 This is an overly large document, it probably needs to be refactored
15 into a Tutorial, Quick Reference and Formal Reference.
17 If you're new to AsciiDoc read this section and the <<X6,Getting
18 Started>> section and take a look at the example AsciiDoc (`*.txt`)
19 source files in the distribution `doc` directory.
20 **********************************************************************
22 Plain text is the most universal electronic document format,
23 regardless of your computing environment you can always read and write
24 plain text documentation. But for many applications plain text is not
25 the preferred presentation format -- HTML and PDF formats are widely
26 used as is the roff man page format. DocBook is a popular
27 documentation markup format which can be translated to HTML, PDF and
28 other presentation formats.
30 AsciiDoc is a plain text human readable/writable document format that
31 can be translated to DocBook or HTML using the asciidoc(1) command.
32 You can then either use asciidoc(1) generated HTML directly or run
33 asciidoc(1) DocBook output through your favorite DocBook toolchain or
34 use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,
35 LaTeX, PostScript, man page, HTML and text formats.
37 The AsciiDoc format is a useful presentation format in its own right:
38 AsciiDoc markup is simple, intuitive and as such is easily proofed and
39 edited.
41 AsciiDoc is light weight: it consists of a single Python script and a
42 bunch of configuration files. Apart from asciidoc(1) and a Python
43 interpreter, no other programs are required to convert AsciiDoc text
44 files to DocBook or HTML. See <<X11,Example AsciiDoc Documents>>
45 below.
47 Text markup conventions tend to be a matter of (often strong) personal
48 preference: if the default syntax is not to your liking you can define
49 your own by editing the text based asciidoc(1) configuration files.
50 You can also create configuration files to translate AsciiDoc
51 documents to almost any SGML/XML markup.
53 asciidoc(1) comes with a set of configuration files to translate
54 AsciiDoc articles, books and man pages to HTML or DocBook backend
55 formats.
57 .My AsciiDoc Itch
58 **********************************************************************
59 DocBook has emerged as the de facto standard Open Source documentation
60 format. But DocBook is a complex language, the markup is difficult to
61 read and even more difficult to write directly -- I found I was
62 spending more time typing markup tags, consulting reference manuals
63 and fixing syntax errors, than I was writing the documentation.
64 **********************************************************************
67 [[X6]]
68 Getting Started
69 ---------------
70 Installing AsciiDoc
71 ~~~~~~~~~~~~~~~~~~~
72 See the `README` and `INSTALL` files for install prerequisites and
73 procedures. Packagers take a look at <<X38,Packager Notes>>.
75 [[X11]]
76 Example AsciiDoc Documents
77 ~~~~~~~~~~~~~~~~~~~~~~~~~~
78 The best way to quickly get a feel for AsciiDoc is to view the
79 AsciiDoc web site and/or distributed examples:
81 - Take a look at the linked examples on the AsciiDoc web site home
82 page Press the 'Page Source'
83 sidebar menu item to view corresponding AsciiDoc source.
84 - Read the `*.txt` source files in the distribution `./doc` directory
85 along with the corresponding HTML and DocBook XML files.
88 AsciiDoc Document Types
89 -----------------------
90 There are three types of AsciiDoc documents: article, book and
91 manpage. All document types share the same AsciiDoc format with some
92 minor variations. If you are familiar with DocBook you will have
93 noticed that AsciiDoc document types correspond to the same-named
94 DocBook document types).
96 Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc
97 document type -- the default document type is 'article'.
99 By convention the `.txt` file extension is used for AsciiDoc document
100 source files.
102 article
103 ~~~~~~~
104 Used for short documents, articles and general documentation. See the
105 AsciiDoc distribution `./doc/article.txt` example.
107 AsciiDoc defines standard DocBook article frontmatter and backmatter
108 <<X93,section markup templates>> (appendix, abstract, bibliography,
109 glossary, index).
111 book
112 ~~~~
113 Books share the same format as articles; in addition there is the
114 option to add level 0 book part sections.
116 Book documents will normally be used to produce DocBook output since
117 DocBook processors can automatically generate footnotes, table of
118 contents, list of tables, list of figures, list of examples and
119 indexes.
121 AsciiDoc defines standard DocBook book frontmatter and backmatter
122 <<X93,section markup templates>> (appendix, dedication, preface,
123 bibliography, glossary, index, colophon).
125 .Example book documents
126 Book::
127 The `./doc/book.txt` file in the AsciiDoc distribution.
129 Multi-part book::
130 The `./doc/book-multi.txt` file in the AsciiDoc distribution.
132 manpage
133 ~~~~~~~
134 Used to generate roff format UNIX manual pages. AsciiDoc manpage
135 documents observe special header title and section naming conventions
136 -- see the <<X1,Manpage Documents>> section for details.
138 AsciiDoc defines the 'synopsis' <<X93,section markup template>> to
139 generate the DocBook `refsynopsisdiv` section.
141 See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from
142 the AsciiDoc distribution.
145 [[X5]]
146 AsciiDoc Backends
147 -----------------
148 The asciidoc(1) command translates an AsciiDoc formatted file to the
149 backend format specified by the `-b` (`--backend`) command-line
150 option. asciidoc(1) itself has little intrinsic knowledge of backend
151 formats, all translation rules are contained in customizable cascading
152 configuration files. Backend specific attributes are listed in the
153 <<X88,Backend Attributes>> section.
155 AsciiDoc ships with the following predefined backend output formats:
157 docbook
158 ~~~~~~~
159 AsciiDoc generates the following DocBook document types: article, book
160 and refentry (corresponding to the AsciiDoc 'article', 'book' and
161 'manpage' document types).
163 DocBook documents are not designed to be viewed directly. Most Linux
164 distributions come with conversion tools (collectively called a
165 toolchain) for <<X12,converting DocBook files>> to presentation
166 formats such as Postscript, HTML, PDF, EPUB, DVI, PostScript, LaTeX,
167 roff (the native man page format), HTMLHelp, JavaHelp and text.
169 The AsciiDoc <<X86,Preamble>> element generates a DocBook book
170 'preface'.
172 [[X33]]
173 xhtml11
174 ~~~~~~~
175 The default asciidoc(1) backend is `xhtml11` -- XHTML 1.1 markup
176 styled with CSS2. Output files have a `.html` extension. 'xhtml11'
177 document generation is influenced by the following optional attributes
178 (the default behavior is to generate XHTML with no section numbers,
179 embedded CSS and no linked admonition icon images):
181 [[X35]]
182 Stylesheets
183 ^^^^^^^^^^^
184 AsciiDoc XHTML output is styled using CSS2 stylesheets from the
185 distribution `./stylesheets/` directory.
188 =====================================================================
189 All browsers have CSS quirks, but Microsoft's IE6 has so many
190 omissions and errors that the `xhtml11-quirks.css` stylesheet and
191 `xhtml11-quirks.conf` configuration files are included during XHTML
192 backend processing to to implement workarounds for IE6. If you don't
193 use IE6 then the quirks stylesheet and configuration files can be
194 omitted using the `--attribute quirks!` command-line option.
195 =====================================================================
197 Default 'xhtml11' stylesheets:
199 `./stylesheets/xhtml11.css`::
200 The main stylesheet.
202 `./stylesheets/xhtml11-manpage.css`::
203 Tweaks for manpage document type generation.
205 `./stylesheets/xhtml11-quirks.css`::
206 Stylesheet modifications to work around IE6 browser
207 incompatibilities.
209 Use the 'theme' attribute to select an alternative set of stylesheets.
210 For example, the command-line option `-a theme=foo` will use
211 stylesheets `foo.css`, `foo-manpage.css` and `foo-quirks.css` instead
212 of the default stylesheets.
214 Use the 'stylesheet' attribute to include an additional stylesheet in
215 XHTML documents. For example, the command-line option `-a
216 stylesheet=newsletter.css` will use stylesheets `newsletter.css`.
218 html4
219 ~~~~~
220 This backend generates plain (unstyled) HTML 4.01 Transitional markup.
223 Document Structure
224 ------------------
225 An AsciiDoc document consists of a series of <<X8,block elements>>
226 starting with an optional document Header, followed by an optional
227 Preamble, followed by zero or more document Sections.
229 Almost any combination of zero or more elements constitutes a valid
230 AsciiDoc document: documents can range from a single sentence to a
231 multi-part book.
233 Block Elements
234 ~~~~~~~~~~~~~~
235 Block elements consist of one or more lines of text and may contain
236 other block elements.
238 The AsciiDoc block structure can be informally summarized as follows
239 footnote:[This is a rough structural guide, not a rigorous syntax
240 definition]:
242 Document ::= (Header?,Preamble?,Section*)
243 Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
244 AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
245 RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
246 Preamble ::= (SectionBody)
247 Section ::= (Title,SectionBody?,(Section)*)
248 SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
249 Block ::= (Paragraph|DelimitedBlock|List|Table)
250 List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
251 BulletedList ::= (ListItem)+
252 NumberedList ::= (ListItem)+
253 CalloutList ::= (ListItem)+
254 LabeledList ::= (ListEntry)+
255 ListEntry ::= (ListLabel,ListItem)
256 ListLabel ::= (ListTerm+)
257 ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
259 Where:
261 - '?' implies zero or one occurrence, '+' implies one or more
262 occurrences, '*' implies zero or more occurrences.
263 - All block elements are separated by line boundaries.
264 - `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
265 shown) can occur almost anywhere.
266 - There are a number of document type and backend specific
267 restrictions imposed on the block syntax.
268 - The following elements cannot contain blank lines: Header, Title,
269 Paragraph, ItemText.
270 - A ListParagraph is a Paragraph with its 'listelement' option set.
271 - A ListContinuation is a <<X15,list continuation element>>.
273 [[X95]]
274 Header
275 ~~~~~~
276 The Header contains a document title plus optional authorship and
277 revision information:
279 - The Header is optional, but if it is used it must start with a
280 document <<X17,title>>.
281 - The header can be preceded by comments and <<X18,attribute
282 entries>>.
283 - Optional Author and Revision information immediately follows the
284 header title.
285 - The header can include attribute entries.
286 - The document header must be separated from the remainder of the
287 document by one or more blank lines.
289 Here's an example AsciiDoc document header:
291 Writing Documentation using AsciiDoc
292 ====================================
293 Joe Bloggs <>
294 v2.0, February 2003:
295 Rewritten for version 2 release.
297 The author information line contains the author's name optionally
298 followed by the author's email address. The author's name consists of
299 a first name followed by optional middle and last names separated by
300 white space. Multi-word first, middle and last names can be entered
301 in the header author line using the underscore as a word separator.
302 The email address comes last and must be enclosed in angle <>
303 brackets. Author names cannot contain angle <> bracket characters.
304 Here a some examples of author information lines:
306 Joe Bloggs <>
307 Joe Bloggs
308 Vincent Willem van_Gogh
310 The optional revision information line follows the author information
311 line. The revision information can be one of two formats:
313 . An optional document revision number followed by an optional
314 revision date followed by an optional revision remark:
316 * If the revision number is specified it must be followed by a
317 comma.
318 * The revision number must contain at least one numeric character.
319 * Any non-numeric characters preceding the first numeric character
320 will be dropped.
321 * If a revision remark is specified it must be preceded by a colon.
322 The revision remark extends from the colon up to the next blank
323 line or attribute entry and is subject to normal text
324 substitutions.
325 * If a revision number or remark has been set but the revision date
326 has not been set then the revision date is set to the value of the
327 'docdate' attribute.
329 . An RCS/CSV/SVN $Id$ marker (if an $Id$ revision marker is used the
330 header author line can be omitted).
332 Here a some examples of header revision lines:
334 v2.0, February 2003
335 February 2003
336 v2.0,
337 v2.0, February 2003: Rewritten for version 2 release.
338 February 2003: Rewritten for version 2 release.
339 v2.0,: Rewritten for version 2 release.
340 :Rewritten for version 2 release.
342 You can override or set header parameters by passing 'revnumber',
343 'revremark', 'revdate', 'email', 'author', 'authorinitials',
344 'firstname' and 'lastname' attributes using the asciidoc(1) `-a`
345 (`--attribute`) command-line option. For example:
347 $ asciidoc -a revdate=2004/07/27 article.txt
349 The 'revnumber' attribute can be an RCS/CSV/SVN $Id$ marker.
350 Attributes can also be added to the header for substitution in the
351 header template with <<X18,Attribute Entry>> elements.
353 [[X87]]
354 Additional document header information
355 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
356 DocBook defines numerous elements for document meta-data, for example:
357 copyrights, document history and authorship information. The AsciiDoc
358 header syntax provides for basic revision and author information --
359 additional information such as copyrights, document history authorship
360 details can be optionally included from a separate 'document
361 information file'. The document information file can contain any
362 DocBook elements that are allowed inside the DocBook 'articleinfo' and
363 'bookinfo' elements:
365 - The document information file must be in the same directory as the
366 source document and must be named like `<docname>-docinfo.xml`. For
367 example, if the source document is called `mydoc.txt` then the
368 document information file would be named `mydoc-docinfo.xml`.
369 - The document information file will only be included in the DocBook
370 output if the `docinfo` attribute is defined, for example:
372 $ asciidoc -a docinfo -b docbook mydoc.txt
374 - See the `./doc/article-docinfo.xml` example that comes with the
375 AsciiDoc distribution.
376 - Similarly AsciiDoc will include a docinfo file named like
377 `<docname>-docinfo.html` (if it exists) into HTML backend outputs.
378 In the case of HTML outputs however it's usually easier to put
379 AsciiDoc markup in your source file directly after the header.
381 NOTE: DocBook has a rich set of meta data elements, just which of
382 these elements are rendered is DocBook processor dependent.
384 [[X86]]
385 Preamble
386 ~~~~~~~~
387 The Preamble is an optional untitled section body between the document
388 Header and the first Section title.
390 Sections
391 ~~~~~~~~
392 In addition to the document title (level 0), AsciiDoc supports four
393 section levels: 1 (top) to 4 (bottom). Section levels are delimited
394 by section <<X17,titles>>. Sections are translated using
395 configuration file <<X93,section markup templates>>. AsciiDoc
396 generates the following <<X60,intrinsic attributes>> specifically for
397 use in section markup templates:
399 level::
400 The `level` attribute is the section level number, it is normally just
401 the <<X17,title>> level number (1..4). However, if the `leveloffset`
402 attribute is defined it will be added to the `level` attribute. The
403 `leveloffset` attribute is useful for <<X90,combining documents>>.
405 sectnum::
406 The `-n` (`--section-numbers`) command-line option generates the
407 `sectnum` (section number) attribute. The `sectnum` attribute is used
408 for section numbers in HTML outputs (DocBook section numbering are
409 handled automatically by the DocBook toolchain commands).
411 [[X93]]
412 Section markup templates
413 ^^^^^^^^^^^^^^^^^^^^^^^^
414 Section markup templates specify output markup and are defined in
415 AsciiDoc configuration files. Section markup template names are
416 derived as follows (in order of precedence):
418 1. From the title's first positional attribute or 'template'
419 attribute. For example, the following three section titles are
420 functionally equivalent:
421 +
422 .....................................................................
423 [[terms]]
424 [glossary]
425 List of Terms
426 -------------
428 ["glossary",id="terms"]
429 List of Terms
430 -------------
432 [template="glossary",id="terms"]
433 List of Terms
434 -------------
435 .....................................................................
437 2. When the title text matches a configuration file
438 <<X16,`[specialsections]`>> entry.
439 3. If neither of the above the default `sect<level>` template is used
440 (where `<level>` is a number from 1 to 4).
442 In addition to the normal section template names ('sect1', 'sect2',
443 'sect3', 'sect4') AsciiDoc has the following templates for
444 frontmatter, backmatter and other special sections: 'abstract',
445 'preface', 'colophon', 'dedication', 'glossary', 'bibliography',
446 'synopsis', 'appendix', 'index'. These special section templates
447 generate the corresponding Docbook elements; for HTML outputs they
448 default to the 'sect1' section template.
450 Section IDs
451 ^^^^^^^^^^^
452 If no explicit section ID is specified an ID will be synthesised from
453 the section title. The primary purpose of this feature is to ensure
454 persistence of table of contents links (permalinks): the missing
455 section IDs are generated dynamically by the JavaScript TOC generator
456 *after* the page is loaded. If you link to a dynamically generated TOC
457 address the page will load but the browser will ignore the (as yet
458 ungenerated) section ID.
460 The IDs are generated by the following algorithm:
462 - Replace all non-alphanumeric title characters with underscores.
463 - Strip leading or trailing underscores.
464 - Convert to lowercase.
465 - Prepend the `idprefix` attribute (so there's no possibility of name
466 clashes with existing document IDs). Prepend an underscore if the
467 `idprefix` attribute is not defined.
468 - A numbered suffix (`_2`, `_3` ...) is added if a same named
469 auto-generated section ID exists.
471 For example the title 'Jim's House' would generate the ID
472 `_jim_s_house`.
474 Section ID synthesis can be disabled by undefining the `sectids`
475 attribute.
477 [[X16]]
478 Special Section Titles
479 ^^^^^^^^^^^^^^^^^^^^^^
480 AsciiDoc has a mechanism for mapping predefined section titles
481 auto-magically to specific markup templates. For example a title
482 'Appendix A: Code Reference' will automatically use the 'appendix'
483 <<X93,section markup template>>. The mappings from title to template
484 name are specified in `[specialsections]` sections in the Asciidoc
485 language configuration files (`lang-*.conf`). Section entries are
486 formatted like:
488 <title>=<template>
490 `<title>` is a Python regular expression and `<template>` is the name
491 of a configuration file markup template section. If the `<title>`
492 matches an AsciiDoc document section title then the backend output is
493 marked up using the `<template>` markup template (instead of the
494 default `sect<level>` section template). The `{title}` attribute value
495 is set to the value of the matched regular expression group named
496 'title', if there is no 'title' group `{title}` defaults to the whole
497 of the AsciiDoc section title. If `<template>` is blank then any
498 existing entry with the same `<title>` will be deleted.
500 .Special section titles vs. explicit template names
501 *********************************************************************
502 AsciiDoc has two mechanisms for specifying non-default section markup
503 templates: you can specify the template name explicitly (using the
504 'template' attribute) or indirectly (using 'special section titles').
505 Specifying a <<X93,section template>> attribute explicitly is
506 preferred. Auto-magical 'special section titles' have the following
507 drawbacks:
509 - They are non-obvious, you have to know the exact matching
510 title for each special section on a language by language basis.
511 - Section titles are predefined and can only be customised with a
512 configuration change.
513 - The implementation is complicated by multiple languages: every
514 special section title has to be defined for each language (in each
515 of the `lang-*.conf` files).
517 Specifying special section template names explicitly does add more
518 noise to the source document (the 'template' attribute declaration),
519 but the intention is obvious and the syntax is consistent with other
520 AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
522 Special section titles have been deprecated but are retained for
523 backward compatibility.
525 *********************************************************************
527 Inline Elements
528 ~~~~~~~~~~~~~~~
529 <<X34,Inline document elements>> are used to format text and to
530 perform various types of text substitution. Inline elements and inline
531 element syntax is defined in the asciidoc(1) configuration files.
533 Here is a list of AsciiDoc inline elements in the (default) order in
534 which they are processed:
536 Special characters::
537 These character sequences escape special characters used by
538 the backend markup (typically `<`, `>`, and `&` characters).
539 See `[specialcharacters]` configuration file sections.
542 Elements that markup words and phrases; usually for character
543 formatting. See `[quotes]` configuration file sections.
545 Special Words::
546 Word or word phrase patterns singled out for markup without
547 the need for further annotation. See `[specialwords]`
548 configuration file sections.
550 Replacements::
551 Each replacement defines a word or word phrase pattern to
552 search for along with corresponding replacement text. See
553 `[replacements]` configuration file sections.
555 Attribute references::
556 Document attribute names enclosed in braces are replaced by
557 the corresponding attribute value.
559 Inline Macros::
560 Inline macros are replaced by the contents of parametrized
561 configuration file sections.
564 Document Processing
565 -------------------
566 The AsciiDoc source document is read and processed as follows:
568 1. The document 'Header' is parsed, header parameter values are
569 substituted into the configuration file `[header]` template section
570 which is then written to the output file.
571 2. Each document 'Section' is processed and its constituent elements
572 translated to the output file.
573 3. The configuration file `[footer]` template section is substituted
574 and written to the output file.
576 When a block element is encountered asciidoc(1) determines the type of
577 block by checking in the following order (first to last): (section)
578 Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
579 AttributeLists, BlockTitles, Paragraphs.
581 The default paragraph definition `[paradef-default]` is last element
582 to be checked.
584 Knowing the parsing order will help you devise unambiguous macro, list
585 and block syntax rules.
587 Inline substitutions within block elements are performed in the
588 following default order:
590 1. Special characters
591 2. Quotes
592 3. Special words
593 4. Replacements
594 5. Attributes
595 6. Inline Macros
596 7. Replacements2
598 The substitutions and substitution order performed on
599 Title, Paragraph and DelimitedBlock elements is determined by
600 configuration file parameters.
603 Text Formatting
604 ---------------
605 [[X51]]
606 Quoted Text
607 ~~~~~~~~~~~
608 Words and phrases can be formatted by enclosing inline text with
609 quote characters:
611 _Emphasized text_::
612 Word phrases \'enclosed in single quote characters' (acute
613 accents) or \_underline characters_ are emphasized.
615 *Strong text*::
616 Word phrases \*enclosed in asterisk characters* are rendered
617 in a strong font (usually bold).
619 [[X81]]+Monospaced text+::
620 Word phrases \+enclosed in plus characters+ are rendered in a
621 monospaced font. Word phrases \`enclosed in backtick
622 characters` (grave accents) are also rendered in a monospaced
623 font but in this case the enclosed text is rendered literally
624 and is not subject to further expansion (see <<X80,inline
625 literal>>).
627 `Single quoted text'::
628 Phrases enclosed with a \`single grave accent to the left and
629 a single acute accent to the right' are rendered in single
630 quotation marks.
632 ``Double quoted text''::
633 Phrases enclosed with \\``two grave accents to the left and
634 two acute accents to the right'' are rendered in quotation
635 marks.
637 #Unquoted text#::
638 Placing \#hashes around text# does nothing, it is a mechanism
639 to allow inline attributes to be applied to otherwise
640 unformatted text (see example below).
642 .Quoted text behavior
643 - Quoting cannot be overlapped.
644 - Different quoting types can be nested.
645 - To suppress quoted text formatting place a backslash character
646 immediately in front of the leading quote character(s). In the case
647 of ambiguity between escaped and non-escaped text you will need to
648 escape both leading and trailing quotes, in the case of
649 multi-character quotes you may even need to escape individual
650 characters.
652 Quoted text can be prefixed with an <<X21,attribute list>>:
654 . Setting the AsciiDoc 'role' attribute will enclose DocBook markup in
655 a 'phrase' element and HTML markup in a 'span' element. For example
656 this AsciiDoc: `[role="foo"]'Hello World'` generates this DocBook:
657 `<phrase role="foo"><emphasis>Hello World</emphasis></phrase>` and
658 this HTML: `<span class="foo"><em>Hello World</em></span>`
660 . You can set the font color, background color and size using the
661 first three positional attribute arguments (HTML outputs only). The
662 first argument is the text color; the second the background color;
663 the third is the font size. Colors are valid CSS colors and the font
664 size is a number which treated as em units. Here are some examples:
666 [red]#Red text#.
667 [,yellow]*bold text on a yellow background*.
668 [blue,#b0e0e6]+Monospaced blue text on a light blue background+
669 [,,2]#Double sized text#.
671 New quotes can be defined by editing asciidoc(1) configuration files.
672 See the <<X7,Configuration Files>> section for details.
674 [[X52]]
675 Constrained and Unconstrained Quotes
676 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
677 There are actually two types of quotes:
679 Constrained quotes
680 ++++++++++++++++++
681 Quoted must be bounded by white space or commonly adjoining
682 punctuation characters. These are the most commonly used type of
683 quote.
685 Unconstrained quotes
686 ++++++++++++++++++++
687 Unconstrained quotes have no boundary constraints and can be placed
688 anywhere within inline text. For consistency and to make them easier
689 to remember unconstrained quotes are double-ups of the `_`, `*`, `+`
690 and `#` constrained quotes:
692 __unconstrained emphasized text__
693 **unconstrained strong text**
694 ++unconstrained monospaced text++
695 ##unconstrained unquoted text##
697 The following example emboldens the letter F:
699 **F**ile Open...
701 Superscripts and Subscripts
702 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
703 Put \^carets on either^ side of the text to be superscripted, put
704 \~tildes on either side~ of text to be subscripted. For example, the
705 following line:
707 e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
708 and ~some sub text~
710 Is rendered like:
712 e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
713 and ~some sub text~
715 Superscripts and subscripts are implemented as <<X52,unconstrained
716 quotes>> and they can be escaped with a leading backslash and prefixed
717 with with an attribute list.
719 Line Breaks
720 ~~~~~~~~~~~
721 A plus character preceded by at least one space character at the end
722 of a non-blank line forces a line break. It generates a line break
723 (`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing
724 instruction for DocBook outputs. The `asciidoc-br` processing
725 instruction is handled by <<X43,a2x(1)>>.
727 Page Breaks
728 ~~~~~~~~~~~
729 A line of three or more less-than (`<<<`) characters will generate a
730 hard page break in DocBook and printed HTML outputs. It uses the CSS
731 `page-break-after` property for HTML outputs and a custom XML
732 `asciidoc-pagebreak` processing instruction for DocBook outputs. The
733 `asciidoc-pagebreak` processing instruction is handled by
734 <<X43,a2x(1)>>. Hard page breaks are sometimes handy but as a general
735 rule you should let your page processor generate page breaks for you.
737 Rulers
738 ~~~~~~
739 A line of three or more apostrophe characters will generate a ruler
740 line. It generates a ruler (`hr`) tag for HTML outputs and a custom
741 XML `asciidoc-hr` processing instruction for DocBook outputs. The
742 `asciidoc-hr` processing instruction is handled by <<X43,a2x(1)>>.
744 Tabs
745 ~~~~
746 By default tab characters input files will translated to 8 spaces. Tab
747 expansion is set with the 'tabsize' entry in the configuration file
748 `[miscellaneous]` section and can be overridden in included files by
749 setting a 'tabsize' attribute in the `include` macro's attribute list.
750 For example:
752 include::addendum.txt[tabsize=2]
754 The tab size can also be set using the attribute command-line option,
755 for example `--attribute tabsize=4`
757 Replacements
758 ~~~~~~~~~~~~
759 The following replacements are defined in the default AsciiDoc
760 configuration:
762 (C) copyright, (TM) trademark, (R) registered trademark,
763 -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
764 double arrow, <= left double arrow.
766 Which are rendered as:
768 (C) copyright, (TM) trademark, (R) registered trademark,
769 -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
770 double arrow, <= left double arrow.
772 You can also include arbitrary entity references in the AsciiDoc
773 source. Examples:
775 &#x278a; &#182;
777 renders:
779 &#x278a; &#182;
781 To render a replacement literally escape it with a leading back-slash.
783 The <<X7,Configuration Files>> section explains how to configure your
784 own replacements.
786 Special Words
787 ~~~~~~~~~~~~~
788 Words defined in `[specialwords]` configuration file sections are
789 automatically marked up without having to be explicitly notated.
791 The <<X7,Configuration Files>> section explains how to add and replace
792 special words.
Something went wrong with that request. Please try again.