Skip to content
Newer
Older
100644 793 lines (637 sloc) 29.8 KB
694b268 @mojombo add asciidoc example
authored
1 AsciiDoc User Guide
2 ===================
3
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.
10
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.
16
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 **********************************************************************
21
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.
29
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.
36
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.
40
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.
46
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.
52
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.
56
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 **********************************************************************
65
66
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>>.
74
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:
80
81 - Take a look at the linked examples on the AsciiDoc web site home
82 page http://www.methods.co.nz/asciidoc/. 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.
86
87
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).
95
96 Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc
97 document type -- the default document type is 'article'.
98
99 By convention the `.txt` file extension is used for AsciiDoc document
100 source files.
101
102 article
103 ~~~~~~~
104 Used for short documents, articles and general documentation. See the
105 AsciiDoc distribution `./doc/article.txt` example.
106
107 AsciiDoc defines standard DocBook article frontmatter and backmatter
108 <<X93,section markup templates>> (appendix, abstract, bibliography,
109 glossary, index).
110
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.
115
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.
120
121 AsciiDoc defines standard DocBook book frontmatter and backmatter
122 <<X93,section markup templates>> (appendix, dedication, preface,
123 bibliography, glossary, index, colophon).
124
125 .Example book documents
126 Book::
127 The `./doc/book.txt` file in the AsciiDoc distribution.
128
129 Multi-part book::
130 The `./doc/book-multi.txt` file in the AsciiDoc distribution.
131
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.
137
138 AsciiDoc defines the 'synopsis' <<X93,section markup template>> to
139 generate the DocBook `refsynopsisdiv` section.
140
141 See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from
142 the AsciiDoc distribution.
143
144
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.
154
155 AsciiDoc ships with the following predefined backend output formats:
156
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).
162
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.
168
169 The AsciiDoc <<X86,Preamble>> element generates a DocBook book
170 'preface'.
171
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):
180
181 [[X35]]
182 Stylesheets
183 ^^^^^^^^^^^
184 AsciiDoc XHTML output is styled using CSS2 stylesheets from the
185 distribution `./stylesheets/` directory.
186
187 [IMPORTANT]
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 =====================================================================
196
197 Default 'xhtml11' stylesheets:
198
199 `./stylesheets/xhtml11.css`::
200 The main stylesheet.
201
202 `./stylesheets/xhtml11-manpage.css`::
203 Tweaks for manpage document type generation.
204
205 `./stylesheets/xhtml11-quirks.css`::
206 Stylesheet modifications to work around IE6 browser
207 incompatibilities.
208
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.
213
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`.
217
218 html4
219 ~~~~~
220 This backend generates plain (unstyled) HTML 4.01 Transitional markup.
221
222
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.
228
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.
232
233 Block Elements
234 ~~~~~~~~~~~~~~
235 Block elements consist of one or more lines of text and may contain
236 other block elements.
237
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]:
241
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)*)
258
259 Where:
260
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>>.
272
273 [[X95]]
274 Header
275 ~~~~~~
276 The Header contains a document title plus optional authorship and
277 revision information:
278
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.
288
289 Here's an example AsciiDoc document header:
290
291 Writing Documentation using AsciiDoc
292 ====================================
293 Joe Bloggs <jbloggs@mymail.com>
294 v2.0, February 2003:
295 Rewritten for version 2 release.
296
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:
305
306 Joe Bloggs <jbloggs@mymail.com>
307 Joe Bloggs
308 Vincent Willem van_Gogh
309
310 The optional revision information line follows the author information
311 line. The revision information can be one of two formats:
312
313 . An optional document revision number followed by an optional
314 revision date followed by an optional revision remark:
315
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.
328
329 . An RCS/CSV/SVN $Id$ marker (if an $Id$ revision marker is used the
330 header author line can be omitted).
331
332 Here a some examples of header revision lines:
333
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.
341
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:
346
347 $ asciidoc -a revdate=2004/07/27 article.txt
348
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.
352
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:
364
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:
371
372 $ asciidoc -a docinfo -b docbook mydoc.txt
373
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.
380
381 NOTE: DocBook has a rich set of meta data elements, just which of
382 these elements are rendered is DocBook processor dependent.
383
384 [[X86]]
385 Preamble
386 ~~~~~~~~
387 The Preamble is an optional untitled section body between the document
388 Header and the first Section title.
389
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:
398
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>>.
404
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).
410
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):
417
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 -------------
427
428 ["glossary",id="terms"]
429 List of Terms
430 -------------
431
432 [template="glossary",id="terms"]
433 List of Terms
434 -------------
435 .....................................................................
436
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).
441
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.
449
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.
459
460 The IDs are generated by the following algorithm:
461
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.
470
471 For example the title 'Jim's House' would generate the ID
472 `_jim_s_house`.
473
474 Section ID synthesis can be disabled by undefining the `sectids`
475 attribute.
476
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:
487
488 <title>=<template>
489
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.
499
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:
508
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).
516
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.
521
522 Special section titles have been deprecated but are retained for
523 backward compatibility.
524
525 *********************************************************************
526
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.
532
533 Here is a list of AsciiDoc inline elements in the (default) order in
534 which they are processed:
535
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.
540
541 Quotes::
542 Elements that markup words and phrases; usually for character
543 formatting. See `[quotes]` configuration file sections.
544
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.
549
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.
554
555 Attribute references::
556 Document attribute names enclosed in braces are replaced by
557 the corresponding attribute value.
558
559 Inline Macros::
560 Inline macros are replaced by the contents of parametrized
561 configuration file sections.
562
563
564 Document Processing
565 -------------------
566 The AsciiDoc source document is read and processed as follows:
567
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.
575
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.
580
581 The default paragraph definition `[paradef-default]` is last element
582 to be checked.
583
584 Knowing the parsing order will help you devise unambiguous macro, list
585 and block syntax rules.
586
587 Inline substitutions within block elements are performed in the
588 following default order:
589
590 1. Special characters
591 2. Quotes
592 3. Special words
593 4. Replacements
594 5. Attributes
595 6. Inline Macros
596 7. Replacements2
597
598 The substitutions and substitution order performed on
599 Title, Paragraph and DelimitedBlock elements is determined by
600 configuration file parameters.
601
602
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:
610
611 _Emphasized text_::
612 Word phrases \'enclosed in single quote characters' (acute
613 accents) or \_underline characters_ are emphasized.
614
615 *Strong text*::
616 Word phrases \*enclosed in asterisk characters* are rendered
617 in a strong font (usually bold).
618
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>>).
626
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.
631
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.
636
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).
641
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.
651
652 Quoted text can be prefixed with an <<X21,attribute list>>:
653
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>`
659
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:
665
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#.
670
671 New quotes can be defined by editing asciidoc(1) configuration files.
672 See the <<X7,Configuration Files>> section for details.
673
674 [[X52]]
675 Constrained and Unconstrained Quotes
676 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
677 There are actually two types of quotes:
678
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.
684
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:
691
692 __unconstrained emphasized text__
693 **unconstrained strong text**
694 ++unconstrained monospaced text++
695 ##unconstrained unquoted text##
696
697 The following example emboldens the letter F:
698
699 **F**ile Open...
700
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:
706
707 e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
708 and ~some sub text~
709
710 Is rendered like:
711
712 e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
713 and ~some sub text~
714
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.
718
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)>>.
726
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.
736
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)>>.
743
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:
751
752 include::addendum.txt[tabsize=2]
753
754 The tab size can also be set using the attribute command-line option,
755 for example `--attribute tabsize=4`
756
757 Replacements
758 ~~~~~~~~~~~~
759 The following replacements are defined in the default AsciiDoc
760 configuration:
761
762 (C) copyright, (TM) trademark, (R) registered trademark,
763 -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
764 double arrow, <= left double arrow.
765
766 Which are rendered as:
767
768 (C) copyright, (TM) trademark, (R) registered trademark,
769 -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
770 double arrow, <= left double arrow.
771
772 You can also include arbitrary entity references in the AsciiDoc
773 source. Examples:
774
775 &#x278a; &#182;
776
777 renders:
778
779 &#x278a; &#182;
780
781 To render a replacement literally escape it with a leading back-slash.
782
783 The <<X7,Configuration Files>> section explains how to configure your
784 own replacements.
785
786 Special Words
787 ~~~~~~~~~~~~~
788 Words defined in `[specialwords]` configuration file sections are
789 automatically marked up without having to be explicitly notated.
790
791 The <<X7,Configuration Files>> section explains how to add and replace
792 special words.
Something went wrong with that request. Please try again.