AsciiDoc User Guide Ascii Doc 2013 11

User Manual:

Open the PDF directly: View PDF .
Page Count: 96

Download
Open PDF In Browser	View PDF

AsciiDoc User Guide
i

AsciiDoc User Guide

AsciiDoc User Guide
ii

REVISION HISTORY
NUMBER

DATE

8.6.9

9 November 2013

DESCRIPTION

NAME
SJR

AsciiDoc User Guide
iii

Contents
1

Introduction

1

2

Getting Started

1

2.1

Installing AsciiDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1

2.2

Example AsciiDoc Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1

3

4

5

AsciiDoc Document Types

2

3.1

article . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

3.2

book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

3.3

manpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

AsciiDoc Backends

2

4.1

Backend Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3

4.2

Backend Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3

DocBook

3

5.1

Converting DocBook to other file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

5.2

a2x Toolchain Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

5.3

HTML generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

5.4

PDF generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

5.5

HTML Help generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

5.6

Toolchain components summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

5.7

AsciiDoc dblatex configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

5.8

AsciiDoc DocBook XSL Stylesheets drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

6

Generating Plain Text Files

6

7

HTML5 and XHTML 1.1

7

7.1

7

8

Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Document Structure

8

8.1

Block Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8

8.2

Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9

8.2.1

Additional document header information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

8.3

Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

8.4

Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

8.5

8.4.1

Section markup templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

8.4.2

Section IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

8.4.3

Special Section Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Inline Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

AsciiDoc User Guide
iv

9

Document Processing

10 Text Formatting

13
14

10.1 Quoted Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
10.1.1 Quoted text attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
10.1.2 Constrained and Unconstrained Quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Constrained quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Unconstrained quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.2 Superscripts and Subscripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.3 Line Breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.4 Page Breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.5 Rulers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.6 Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.7 Replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.8 Special Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
11 Titles

17

11.1 Two line titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
11.2 One line titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
11.3 Floating titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
12 Block Titles

18

13 BlockId Element

18

14 AttributeList Element

18

14.1 Attribute value substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
14.2 Common attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
15 Paragraphs

19

15.1 normal paragraph syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
15.2 literal paragraph syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
15.3 quote and verse paragraph styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
15.4 Admonition Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
15.4.1 Admonition Icons and Captions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
16 Delimited Blocks

21

16.1 Predefined Delimited Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
16.2 Listing Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
16.3 Literal Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
16.4 Sidebar Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
16.5 Comment Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

AsciiDoc User Guide
v

16.6 Passthrough Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
16.7 Quote Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
16.8 Example Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
16.9 Admonition Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
16.10Open Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
17 Lists

26

17.1 Bulleted Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
17.2 Numbered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
17.3 Labeled Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
17.3.1 Horizontal labeled list style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
17.4 Question and Answer Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
17.5 Glossary Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
17.6 Bibliography Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
17.7 List Item Continuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
18 Footnotes

32

19 Indexes

33

20 Callouts

33

20.1 Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
20.2 Including callouts in included code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
21 Macros

35

21.1 Inline Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
21.1.1 URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
21.1.2 Internal Cross References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
anchor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
xref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
21.1.3 Linking to Local Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
21.1.4 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
21.1.5 Comment Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
21.2 Block Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
21.2.1 Block Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
21.2.2 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
21.2.3 Comment Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
21.3 System Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
21.3.1 Include Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
21.3.2 Conditional Inclusion Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
21.3.3 Executable system macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
21.3.4 Template System Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
21.4 Passthrough macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
21.5 Macro Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

AsciiDoc User Guide
vi

22 HTML 5 audio and video block macros

44

23 Tables

45

23.1 Example tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
23.2 Table input data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
23.3 Table attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
23.4 Column Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
23.5 Cell Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
23.6 Table styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
23.7 Markup attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
23.8 Nested tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
23.9 DocBook table limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
24 Manpage Documents

52

24.1 Document Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
24.2 The NAME Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
24.3 The SYNOPSIS Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
24.4 refmiscinfo attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
25 Mathematical Formulas

53

25.1 LaTeX Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
25.2 ASCIIMathML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
25.3 LaTeXMathML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
25.4 MathML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
26 Configuration Files

54

26.1 Configuration File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
26.2 Miscellaneous section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
26.3 Titles section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
26.4 Tags section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
26.5 Attributes section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
26.6 Special Characters section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
26.7 Quoted Text section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
26.8 Special Words section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
26.9 Replacements section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
26.10Markup Template Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
26.11Configuration file names, precedence and locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
27 Document Attributes

61

28 Attribute Entries

61

28.1 Setting configuration entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

AsciiDoc User Guide
vii

29 Attribute Lists

64

29.1 Options attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
29.2 Macro Attribute lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
30 Attribute References

65

30.1 Simple Attributes References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
30.2 Conditional Attribute References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
30.2.1 Conditional attribute examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
30.3 System Attribute References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
31 Intrinsic Attributes

68

32 Block Element Definitions

70

32.1 Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
32.2 Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
32.3 Delimited Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
32.4 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
32.5 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
33 Filters

73

33.1 Filter Search Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
33.2 Filter Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
33.3 Example Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
33.4 Built-in filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
33.5 Filter plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
34 Plugins

75

35 Help Commands

75

35.1 Customizing Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
36 Tips and Tricks

76

36.1 Know Your Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
36.2 Vim Commands for Formatting AsciiDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
36.2.1 Text Wrap Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
36.2.2 Format Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
36.2.3 Indent Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
36.2.4 Example ~/.vimrc File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
36.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
36.4 Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
36.5 Combining separate documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
36.6 Processing document sections separately . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

AsciiDoc User Guide
viii

36.7 Processing document snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
36.8 Badges in HTML page footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
36.9 Pretty printing AsciiDoc output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
36.10Supporting minor DocBook DTD variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
36.11Creating stand-alone HTML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
36.12Shipping stand-alone AsciiDoc source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
36.13Inserting blank space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
36.14Closing open sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
36.15Validating output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
37 Glossary

81

A Migration Notes

81

A.1 Version 7 to version 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
B Packager Notes

82

C AsciiDoc Safe Mode

82

D Using AsciiDoc with non-English Languages

82

E Vim Syntax Highlighter

83

F Attribute Options

83

G Diagnostics

83

H Backend Attributes

85

I

88

License

AsciiDoc User Guide
1 / 88

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, blogs
and UNIX man pages. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page. AsciiDoc
is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of
SGML/XML markup) can be customized and extended by the user.
This document
This is an overly large document, it probably needs to be refactored into a Tutorial, Quick Reference and Formal Reference.
If you’re new to AsciiDoc read this section and the Getting Started section and take a look at the example AsciiDoc
(*.txt) source files in the distribution doc directory.

1

Introduction

AsciiDoc is a plain text human readable/writable document format that can be translated to DocBook or HTML using the
asciidoc(1) command. You can then either use asciidoc(1) generated HTML directly or run asciidoc(1) DocBook
output through your favorite DocBook toolchain or use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,
LaTeX, PostScript, man page, HTML and text formats.
The AsciiDoc format is a useful presentation format in its own right: AsciiDoc markup is simple, intuitive and as such is easily
proofed and edited.
AsciiDoc is light weight: it consists of a single Python script and a bunch of configuration files. Apart from asciidoc(1) and
a Python interpreter, no other programs are required to convert AsciiDoc text files to DocBook or HTML. See Example AsciiDoc
Documents below.
Text markup conventions tend to be a matter of (often strong) personal preference: if the default syntax is not to your liking
you can define your own by editing the text based asciidoc(1) configuration files. You can also create configuration files to
translate AsciiDoc documents to almost any SGML/XML markup.
asciidoc(1) comes with a set of configuration files to translate AsciiDoc articles, books and man pages to HTML or DocBook
backend formats.
My AsciiDoc Itch
DocBook has emerged as the de facto standard Open Source documentation format. But DocBook is a complex language,
the markup is difficult to read and even more difficult to write directly — I found I was spending more time typing markup
tags, consulting reference manuals and fixing syntax errors, than I was writing the documentation.

2
2.1

Getting Started
Installing AsciiDoc

See the README and INSTALL files for install prerequisites and procedures. Packagers take a look at Packager Notes.

2.2

Example AsciiDoc Documents

The best way to quickly get a feel for AsciiDoc is to view the AsciiDoc web site and/or distributed examples:
• Take a look at the linked examples on the AsciiDoc web site home page http://asciidoc.org/. Press the Page Source sidebar
menu item to view corresponding AsciiDoc source.
• Read the *.txt source files in the distribution ./doc directory along with the corresponding HTML and DocBook XML
files.

AsciiDoc User Guide
2 / 88

3

AsciiDoc Document Types

There are three types of AsciiDoc documents: article, book and manpage. All document types share the same AsciiDoc format
with some minor variations. If you are familiar with DocBook you will have noticed that AsciiDoc document types correspond
to the same-named DocBook document types.
Use the asciidoc(1) -d (--doctype) option to specify the AsciiDoc document type — the default document type is article.
By convention the .txt file extension is used for AsciiDoc document source files.

3.1

article

Used for short documents, articles and general documentation. See the AsciiDoc distribution ./doc/article.txt example.
AsciiDoc defines standard DocBook article frontmatter and backmatter section markup templates (appendix, abstract, bibliography, glossary, index).

3.2

book

Books share the same format as articles, with the following differences:
• The part titles in multi-part books are top level titles (same level as book title).
• Some sections are book specific e.g. preface and colophon.
Book documents will normally be used to produce DocBook output since DocBook processors can automatically generate footnotes, table of contents, list of tables, list of figures, list of examples and indexes.
AsciiDoc defines standard DocBook book frontmatter and backmatter section markup templates (appendix, dedication, preface,
bibliography, glossary, index, colophon).
E XAMPLE BOOK DOCUMENTS
Book
The ./doc/book.txt file in the AsciiDoc distribution.
Multi-part book
The ./doc/book-multi.txt file in the AsciiDoc distribution.

3.3

manpage

Used to generate roff format UNIX manual pages. AsciiDoc manpage documents observe special header title and section naming
conventions — see the Manpage Documents section for details.
AsciiDoc defines the synopsis section markup template to generate the DocBook refsynopsisdiv section.
See also the asciidoc(1) man page source (./doc/asciidoc.1.txt) from the AsciiDoc distribution.

4

AsciiDoc Backends

The asciidoc(1) command translates an AsciiDoc formatted file to the backend format specified by the -b (--backend)
command-line option. asciidoc(1) itself has little intrinsic knowledge of backend formats, all translation rules are contained
in customizable cascading configuration files. Backend specific attributes are listed in the Backend Attributes section.
docbook45
Outputs DocBook XML 4.5 markup.

AsciiDoc User Guide
3 / 88

html4
This backend generates plain HTML 4.01 Transitional markup.
xhtml11
This backend generates XHTML 1.1 markup styled with CSS2. Output files have an .html extension.
html5
This backend generates HTML 5 markup, apart from the inclusion of audio and video block macros it is functionally
identical to the xhtml11 backend.
slidy
Use this backend to generate self-contained Slidy HTML slideshows for your web browser from AsciiDoc documents. The
Slidy backend is documented in the distribution doc/slidy.txt file and online.
wordpress
A minor variant of the html4 backend to support blogpost.
latex
Experimental LaTeX backend.

4.1

Backend Aliases

Backend aliases are alternative names for AsciiDoc backends. AsciiDoc comes with two backend aliases: html (aliased to
xhtml11) and docbook (aliased to docbook45).
You can assign (or reassign) backend aliases by setting an AsciiDoc attribute named like backend-alias- to an
AsciiDoc backend name. For example, the following backend alias attribute definitions appear in the [attributes] section
of the global asciidoc.conf configuration file:
backend-alias-html=xhtml11
backend-alias-docbook=docbook45

4.2

Backend Plugins

The asciidoc(1) --backend option is also used to install and manage backend plugins.
• A backend plugin is used just like the built-in backends.
• Backend plugins take precedence over built-in backends with the same name.
• You can use the {asciidoc-confdir} intrinsic attribute to refer to the built-in backend configuration file location from
backend plugin configuration files.
• You can use the {backend-confdir} intrinsic attribute to refer to the backend plugin configuration file location.
• By default backends plugins are installed in $HOME/.asciidoc/backends/ where  is the
backend name.

5

DocBook

AsciiDoc generates article, book and refentry DocBook documents (corresponding to the AsciiDoc article, book and manpage
document types).
Most Linux distributions come with conversion tools (collectively called a toolchain) for converting DocBook files to presentation formats such as Postscript, HTML, PDF, EPUB, DVI, PostScript, LaTeX, roff (the native man page format), HTMLHelp,
JavaHelp and text. There are also programs that allow you to view DocBook files directly, for example Yelp (the GNOME help
viewer).

AsciiDoc User Guide
4 / 88

5.1

Converting DocBook to other file formats

DocBook files are validated, parsed and translated various presentation file formats using a combination of applications collectively called a DocBook tool chain. The function of a tool chain is to read the DocBook markup (produced by AsciiDoc) and
transform it to a presentation format (for example HTML, PDF, HTML Help, EPUB, DVI, PostScript, LaTeX).
A wide range of user output format requirements coupled with a choice of available tools and stylesheets results in many valid
tool chain combinations.

5.2

a2x Toolchain Wrapper

One of the biggest hurdles for new users is installing, configuring and using a DocBook XML toolchain. a2x(1) can help — it’s
a toolchain wrapper command that will generate XHTML (chunked and unchunked), PDF, EPUB, DVI, PS, LaTeX, man page,
HTML Help and text file outputs from an AsciiDoc text file. a2x(1) does all the grunt work associated with generating and
sequencing the toolchain commands and managing intermediate and output files. a2x(1) also optionally deploys admonition
and navigation icons and a CSS stylesheet. See the a2x(1) man page for more details. In addition to asciidoc(1) you
also need xsltproc(1), DocBook XSL Stylesheets and optionally: dblatex or FOP (to generate PDF); w3m(1) or lynx(1) (to
generate text).

The following examples generate doc/source-highlight-filter.pdf from the AsciiDoc doc/source-highlight-filt
source file. The first example uses dblatex(1) (the default PDF generator) the second example forces FOP to be used:
$ a2x -f pdf doc/source-highlight-filter.txt
$ a2x -f pdf --fop doc/source-highlight-filter.txt
See the a2x(1) man page for details.
Tip
Use the --verbose command-line option to view executed toolchain commands.

5.3

HTML generation

AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going
the DocBook route:
• HTML from DocBook can optionally include automatically generated indexes, tables of contents, footnotes, lists of figures
and tables.
• DocBook toolchains can also (optionally) generate separate (chunked) linked HTML pages for each document section.
• Toolchain processing performs link and document validity checks.
• If the DocBook lang attribute is set then things like table of contents, figure and table captions and admonition captions will
be output in the specified language (setting the AsciiDoc lang attribute sets the DocBook lang attribute).
On the other hand, HTML output directly from AsciiDoc is much faster, is easily customized and can be used in situations where
there is no suitable DocBook toolchain (for example, see the AsciiDoc website).

5.4

PDF generation

There are two commonly used tools to generate PDFs from DocBook, dblatex and FOP.
DBLATEX OR

FOP?

• dblatex is easier to install, there’s zero configuration required and no Java VM to install — it just works out of the box.

AsciiDoc User Guide
5 / 88

• dblatex source code highlighting and numbering is superb.
• dblatex is easier to use as it converts DocBook directly to PDF whereas before using FOP you have to convert DocBook to
XML-FO using DocBook XSL Stylesheets.
• FOP is more feature complete (for example, callouts are processed inside literal layouts) and arguably produces nicer looking
output.

5.5

HTML Help generation

1. Convert DocBook XML documents to HTML Help compiler source files using DocBook XSL Stylesheets and xsltproc(1).
2. Convert the HTML Help source (.hhp and .html) files to HTML Help (.chm) files using the Microsoft HTML Help
Compiler.

5.6

Toolchain components summary

AsciiDoc
Converts AsciiDoc (.txt) files to DocBook XML (.xml) files.
DocBook XSL Stylesheets
These are a set of XSL stylesheets containing rules for converting DocBook XML documents to HTML, XSL-FO, manpage
and HTML Help files. The stylesheets are used in conjunction with an XML parser such as xsltproc(1).
xsltproc
An XML parser for applying XSLT stylesheets (in our case the DocBook XSL Stylesheets) to XML documents.
dblatex
Generates PDF, DVI, PostScript and LaTeX formats directly from DocBook source via the intermediate LaTeX typesetting
language — uses DocBook XSL Stylesheets, xsltproc(1) and latex(1).
FOP
The Apache Formatting Objects Processor converts XSL-FO (.fo) files to PDF files. The XSL-FO files are generated
from DocBook source files using DocBook XSL Stylesheets and xsltproc(1).
Microsoft Help Compiler
The Microsoft HTML Help Compiler (hhc.exe) is a command-line tool that converts HTML Help source files to a single
HTML Help (.chm) file. It runs on MS Windows platforms and can be downloaded from http://www.microsoft.com.

5.7

AsciiDoc dblatex configuration files

The AsciiDoc distribution ./dblatex directory contains asciidoc-dblatex.xsl (customized XSL parameter settings)
and asciidoc-dblatex.sty (customized LaTeX settings). These are examples of optional dblatex output customization
and are used by a2x(1).

5.8

AsciiDoc DocBook XSL Stylesheets drivers

You will have noticed that the distributed HTML and HTML Help documentation files (for example ./doc/asciidoc.html)
are not the plain outputs produced using the default DocBook XSL Stylesheets configuration. This is because they have been processed using customized DocBook XSL Stylesheets along with (in the case of HTML outputs) the custom ./stylesheets/docbook
CSS stylesheet.
You’ll find the customized DocBook XSL drivers along with additional documentation in the distribution ./docbook-xsl
directory. The examples that follow are executed from the distribution documentation (./doc) directory. These drivers are also
used by a2x(1).

AsciiDoc User Guide
6 / 88

common.xsl
Shared driver parameters. This file is not used directly but is included in all the following drivers.
chunked.xsl
Generate chunked XHTML (separate HTML pages for each document section) in the ./doc/chunked directory. For
example:
$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
epub.xsl
Used by a2x(1) to generate EPUB formatted documents.
fo.xsl
Generate XSL Formatting Object (.fo) files for subsequent PDF file generation using FOP. For example:
$ python ../asciidoc.py -b docbook article.txt
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
$ fop article.fo article.pdf
htmlhelp.xsl
Generate Microsoft HTML Help source files for the MS HTML Help Compiler in the ./doc/htmlhelp directory. This
example is run on MS Windows from a Cygwin shell prompt:
$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
manpage.xsl
Generate a roff(1) format UNIX man page from a DocBook XML refentry document. This example generates an
asciidoc.1 man page file:
$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
xhtml.xsl
Convert a DocBook XML file to a single XHTML file. For example:
$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
If you want to see how the complete documentation set is processed take a look at the A-A-P script ./doc/main.aap.

6

Generating Plain Text Files

AsciiDoc does not have a text backend (for most purposes AsciiDoc source text is fine), however you can convert AsciiDoc text
files to formatted text using the AsciiDoc a2x(1) toolchain wrapper utility.

AsciiDoc User Guide
7 / 88

7

HTML5 and XHTML 1.1

The xhtml11 and html5 backends embed or link CSS and JavaScript files in their outputs, there is also a themes plugin framework.
• If the AsciiDoc linkcss attribute is defined then CSS and JavaScript files are linked to the output document, otherwise they are
embedded (the default behavior).
• The default locations for CSS and JavaScript files can be changed by setting the AsciiDoc stylesdir and scriptsdir attributes
respectively.
• The default locations for embedded and linked files differ and are calculated at different times — embedded files are loaded
when asciidoc(1) generates the output document, linked files are loaded by the browser when the user views the output
document.
• Embedded files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files
from AsciiDoc configuration directories to the correct location relative to the output document.
Table 1: Stylesheet file locations
stylesdir attribute
Undefined (default).

Absolute or relative directory name.

Linked location (linkcss attribute
defined)
Same directory as the output
document.

Absolute or relative to the output
document.

Embedded location (linkcss
attribute undefined)
stylesheets subdirectory in the
AsciiDoc configuration directory (the
directory containing the backend conf
file).
Absolute or relative to the AsciiDoc
configuration directory (the directory
containing the backend conf file).

Table 2: JavaScript file locations
scriptsdir attribute
Undefined (default).

Absolute or relative directory name.

7.1

Linked location (linkcss attribute
defined)
Same directory as the output
document.

Absolute or relative to the output
document.

Embedded location (linkcss
attribute undefined)
javascripts subdirectory in the
AsciiDoc configuration directory (the
directory containing the backend conf
file).
Absolute or relative to the AsciiDoc
configuration directory (the directory
containing the backend conf file).

Themes

The AsciiDoc theme attribute is used to select an alternative CSS stylesheet and to optionally include additional JavaScript code.
• Theme files reside in an AsciiDoc configuration directory named themes// (where  is the the theme
name set by the theme attribute). asciidoc(1) sets the themedir attribute to the theme directory path name.
• The theme attribute can also be set using the asciidoc(1) --theme option, the --theme option can also be used to
manage theme plugins.

AsciiDoc User Guide
8 / 88

• AsciiDoc ships with two themes: flask and volnitsky.
• The .css file replaces the default asciidoc.css CSS file.
• The .js file is included in addition to the default asciidoc.js JavaScript file.
• If the data-uri attribute is defined then icons are loaded from the theme icons sub-directory if it exists (i.e. the iconsdir
attribute is set to theme icons sub-directory path).
• Embedded theme files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript
files to the location of the output documents.
• Linked CSS and JavaScript theme files are linked to the same linked locations as other CSS and JavaScript files.
For example, the command-line option --theme foo (or --attribute theme=foo) will cause asciidoc(1) to
search configuration file locations 1 for a sub-directory called themes/foo containing the stylesheet foo.css and optionally
a JavaScript file name foo.js.

8

Document Structure

An AsciiDoc document consists of a series of block elements starting with an optional document Header, followed by an optional
Preamble, followed by zero or more document Sections.
Almost any combination of zero or more elements constitutes a valid AsciiDoc document: documents can range from a single
sentence to a multi-part book.

8.1

Block Elements

Block elements consist of one or more lines of text and may contain other block elements.
The AsciiDoc block structure can be informally summarized as follows 1 :
Document
Header
AuthorInfo
RevisionInfo
Preamble
Section
SectionBody
Block
List
BulletedList
NumberedList
CalloutList
LabeledList
ListEntry
ListLabel
ListItem

::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=

(Header?,Preamble?,Section*)
(Title,(AuthorInfo,RevisionInfo?)?)
(FirstName,(MiddleName?,LastName)?,EmailAddress?)
(RevisionNumber?,RevisionDate,RevisionRemark?)
(SectionBody)
(Title,SectionBody?,(Section)*)
((BlockTitle?,Block)|BlockMacro)+
(Paragraph|DelimitedBlock|List|Table)
(BulletedList|NumberedList|LabeledList|CalloutList)
(ListItem)+
(ListItem)+
(ListItem)+
(ListEntry)+
(ListLabel,ListItem)
(ListTerm+)
(ItemText,(List|ListParagraph|ListContinuation)*)

Where:
• ? implies zero or one occurrence, + implies one or more occurrences, * implies zero or more occurrences.
• All block elements are separated by line boundaries.
• BlockId, AttributeEntry and AttributeList block elements (not shown) can occur almost anywhere.
1 This

is a rough structural guide, not a rigorous syntax definition

AsciiDoc User Guide
9 / 88

• There are a number of document type and backend specific restrictions imposed on the block syntax.
• The following elements cannot contain blank lines: Header, Title, Paragraph, ItemText.
• A ListParagraph is a Paragraph with its listelement option set.
• A ListContinuation is a list continuation element.

8.2

Header

The Header contains document meta-data, typically title plus optional authorship and revision information:
• The Header is optional, but if it is used it must start with a document title.
• Optional Author and Revision information immediately follows the header title.
• The document header must be separated from the remainder of the document by one or more blank lines and cannot contain
blank lines.
• The header can include comments.
• The header can include attribute entries, typically doctype, lang, encoding, icons, data-uri, toc, numbered.
• Header attributes are overridden by command-line attributes.
• If the header contains non-UTF-8 characters then the encoding must precede the header (either in the document or on the
command-line).
Here’s an example AsciiDoc document header:
Writing Documentation using AsciiDoc
====================================
Joe Bloggs 
v2.0, February 2003:
Rewritten for version 2 release.
The author information line contains the author’s name optionally followed by the author’s email address. The author’s name is
formatted like:
firstname[ [middlename ]lastname][ ]]
i.e. a first name followed by optional middle and last names followed by an email address in that order. Multi-word first, middle
and last names can be entered using the underscore as a word separator. The email address comes last and must be enclosed in
angle <> brackets. Here a some examples of author information lines:
Joe Bloggs 
Joe Bloggs
Vincent Willem van_Gogh
If the author line does not match the above specification then the entire author line is treated as the first name.
The optional revision information line follows the author information line. The revision information can be one of two formats:
1. An optional document revision number followed by an optional revision date followed by an optional revision remark:
• If the revision number is specified it must be followed by a comma.
• The revision number must contain at least one numeric character.
• Any non-numeric characters preceding the first numeric character will be dropped.

AsciiDoc User Guide
10 / 88

• If a revision remark is specified it must be preceded by a colon. The revision remark extends from the colon up to the
next blank line, attribute entry or comment and is subject to normal text substitutions.
• If a revision number or remark has been set but the revision date has not been set then the revision date is set to the value
of the docdate attribute.
Examples:
v2.0, February 2003
February 2003
v2.0,
v2.0, February 2003: Rewritten for version 2 release.
February 2003: Rewritten for version 2 release.
v2.0,: Rewritten for version 2 release.
:Rewritten for version 2 release.
2. The revision information line can also be an RCS/CVS/SVN $Id$ marker:
• AsciiDoc extracts the revnumber, revdate, and author attributes from the $Id$ revision marker and displays them in the
document header.
• If an $Id$ revision marker is used the header author line can be omitted.
Example:
$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $
You can override or set header parameters by passing revnumber, revremark, revdate, email, author, authorinitials, firstname and
lastname attributes using the asciidoc(1) -a (--attribute) command-line option. For example:
$ asciidoc -a revdate=2004/07/27 article.txt
Attribute entries can also be added to the header for substitution in the header template with Attribute Entry elements.
The title element in HTML outputs is set to the AsciiDoc document title, you can set it to a different value by including a title
attribute entry in the document header.
8.2.1

Additional document header information

AsciiDoc has two mechanisms for optionally including additional meta-data in the header of the output document:
docinfo configuration file sections
If a configuration file section named docinfo has been loaded then it will be included in the document header. Typically
the docinfo section name will be prefixed with a + character so that it is appended to (rather than replace) other docinfo
sections.
docinfo files
Two docinfo files are recognized: one named docinfo and a second named like the AsciiDoc source file with a
-docinfo suffix. For example, if the source document is called mydoc.txt then the document information files would
be docinfo.xml and mydoc-docinfo.xml (for DocBook outputs) and docinfo.html and mydoc-docinfo.html
(for HTML outputs). The docinfo attributes control which docinfo files are included in the output files.
The contents docinfo templates and files is dependent on the type of output:
HTML
Valid head child elements. Typically style and script elements for CSS and JavaScript inclusion.
DocBook
Valid articleinfo or bookinfo child elements. DocBook defines numerous elements for document meta-data, for example:
copyrights, document history and authorship information. See the DocBook ./doc/article-docinfo.xml example
that comes with the AsciiDoc distribution. The rendering of meta-data elements (or not) is DocBook processor dependent.

AsciiDoc User Guide
11 / 88

8.3

Preamble

The Preamble is an optional untitled section body between the document Header and the first Section title.

8.4

Sections

In addition to the document title (level 0), AsciiDoc supports four section levels: 1 (top) to 4 (bottom). Section levels are
delimited by section titles. Sections are translated using configuration file section markup templates. AsciiDoc generates the
following intrinsic attributes specifically for use in section markup templates:
level
The level attribute is the section level number, it is normally just the title level number (1..4). However, if the
leveloffset attribute is defined it will be added to the level attribute. The leveloffset attribute is useful
for combining documents.
sectnum
The -n (--section-numbers) command-line option generates the sectnum (section number) attribute. The sectnum
attribute is used for section numbers in HTML outputs (DocBook section numbering are handled automatically by the DocBook toolchain commands).
8.4.1

Section markup templates

Section markup templates specify output markup and are defined in AsciiDoc configuration files. Section markup template names
are derived as follows (in order of precedence):
1. From the title’s first positional attribute or template attribute. For example, the following three section titles are functionally
equivalent:
[[terms]]
[glossary]
List of Terms
------------["glossary",id="terms"]
List of Terms
------------[template="glossary",id="terms"]
List of Terms
------------2. When the title text matches a configuration file [specialsections] entry.
3. If neither of the above the default sect template is used (where  is a number from 1 to 4).
In addition to the normal section template names (sect1, sect2, sect3, sect4) AsciiDoc has the following templates for frontmatter,
backmatter and other special sections: abstract, preface, colophon, dedication, glossary, bibliography, synopsis, appendix, index.
These special section templates generate the corresponding Docbook elements; for HTML outputs they default to the sect1
section template.
8.4.2

Section IDs

If no explicit section ID is specified an ID will be synthesised from the section title. The primary purpose of this feature is to
ensure persistence of table of contents links (permalinks): the missing section IDs are generated dynamically by the JavaScript
TOC generator after the page is loaded. If you link to a dynamically generated TOC address the page will load but the browser
will ignore the (as yet ungenerated) section ID.
The IDs are generated by the following algorithm:

AsciiDoc User Guide
12 / 88

• Replace all non-alphanumeric title characters with underscores.
• Strip leading or trailing underscores.
• Convert to lowercase.
• Prepend the idprefix attribute (so there’s no possibility of name clashes with existing document IDs). Prepend an underscore if the idprefix attribute is not defined.
• A numbered suffix (_2, _3 . . . ) is added if a same named auto-generated section ID exists.
• If the ascii-ids attribute is defined then non-ASCII characters are replaced with ASCII equivalents. This attribute may be
deprecated in future releases and should be avoided, it’s sole purpose is to accommodate deficient downstream applications
that cannot process non-ASCII ID attributes.
Example: the title Jim’s House would generate the ID _jim_s_house.
Section ID synthesis can be disabled by undefining the sectids attribute.
8.4.3

Special Section Titles

AsciiDoc has a mechanism for mapping predefined section titles auto-magically to specific markup templates. For example a title
Appendix A: Code Reference will automatically use the appendix section markup template. The mappings from title to template
name are specified in [specialsections] sections in the Asciidoc language configuration files (lang-*.conf). Section
entries are formatted like:


...


+++++++++++++++++++++++++++++++
endif::basebackend-docbook[]

AsciiDoc User Guide
81 / 88

36.15

Validating output files

Use xmllint(1) to check the AsciiDoc generated markup is both well formed and valid. Here are some examples:
$ xmllint --nonet --noout --valid docbook-file.xml
$ xmllint --nonet --noout --valid xhtml11-file.html
$ xmllint --nonet --noout --valid --html html4-file.html
The --valid option checks the file is valid against the document type’s DTD, if the DTD is not installed in your system’s
catalog then it will be fetched from its Internet location. If you omit the --valid option the document will only be checked
that it is well formed.
The online W3C Markup Validation Service is the defacto standard when it comes to validating HTML (it validates all HTML
standards including HTML5).

37

Glossary

Block element
An AsciiDoc block element is a document entity composed of one or more whole lines of text.
Inline element
AsciiDoc inline elements occur within block element textual content, they perform formatting and substitution tasks.
Formal element
An AsciiDoc block element that has a BlockTitle. Formal elements are normally listed in front or back matter, for example
lists of tables, examples and figures.
Verbatim element
The word verbatim indicates that white space and line breaks in the source document are to be preserved in the output
document.

A
A.1

Migration Notes
Version 7 to version 8

• A new set of quotes has been introduced which may match inline text in existing documents — if they do you’ll need to escape
the matched text with backslashes.
• The index entry inline macro syntax has changed — if your documents include indexes you may need to edit them.
• Replaced a2x(1) --no-icons and --no-copy options with their negated equivalents: --icons and --copy respectively. The default behavior has also changed — the use of icons and copying of icon and CSS files must be specified explicitly
with the --icons and --copy options.
The rationale for the changes can be found in the AsciiDoc CHANGELOG.
Note
If you want to disable unconstrained quotes, the new alternative constrained quotes syntax and the new index entry syntax then
you can define the attribute asciidoc7compatible (for example by using the -a asciidoc7compatible commandline option).

AsciiDoc User Guide
82 / 88

B

Packager Notes

Read the README and INSTALL files (in the distribution root directory) for install prerequisites and procedures. The distribution
Makefile.in (used by configure to generate the Makefile) is the canonical installation procedure.

C

AsciiDoc Safe Mode

AsciiDoc safe mode skips potentially dangerous scripted sections in AsciiDoc source files by inhibiting the execution of arbitrary
code or the inclusion of arbitrary files.
The safe mode is disabled by default, it can be enabled with the asciidoc(1) --safe command-line option.
S AFE MODE CONSTRAINTS
• eval, sys and sys2 executable attributes and block macros are not executed.
• include::[] and include1::[] block macro files must reside inside the parent file’s
directory.
• {include:} executable attribute files must reside inside the source document directory.
• Passthrough Blocks are dropped.
Warning
The safe mode is not designed to protect against unsafe AsciiDoc configuration files. Be especially careful when:
1. Implementing filters.
2. Implementing elements that don’t escape special characters.
3. Accepting configuration files from untrusted sources.

D

Using AsciiDoc with non-English Languages

AsciiDoc can process UTF-8 character sets but there are some things you need to be aware of:
• If you are generating output documents using a DocBook toolchain then you should set the AsciiDoc lang attribute to the
appropriate language (it defaults to en (English)). This will ensure things like table of contents, figure and table captions and
admonition captions are output in the specified language. For example:
$ a2x -a lang=es doc/article.txt
• If you are outputting HTML directly from asciidoc(1) you’ll need to set the various *_caption attributes to match your
target language (see the list of captions and titles in the [attributes] section of the distribution lang-*.conf files).
The easiest way is to create a language .conf file (see the AsciiDoc’s lang-en.conf file).
Note
You still use the NOTE, CAUTION, TIP, WARNING, IMPORTANT captions in the AsciiDoc source, they get translated in the
HTML output file.

• asciidoc(1) automatically loads configuration files named like lang-.conf where  is a two letter
language code that matches the current AsciiDoc lang attribute. See also Configuration File Names and Locations.

AsciiDoc User Guide
83 / 88

E

Vim Syntax Highlighter

Syntax highlighting is incredibly useful, in addition to making reading AsciiDoc documents much easier syntax highlighting also
helps you catch AsciiDoc syntax errors as you write your documents.
The AsciiDoc distribution directory contains a Vim syntax highlighter for AsciiDoc (./vim/syntax/asciidoc.vim), you
can find the latest version in the online AsciiDoc repository.
Install the highlighter by copying asciidoc.vim to your $HOME/.vim/syntax directory (create it if it doesn’t already
exist).
To enable syntax highlighing:
• Put a Vim autocmd in your Vim configuration file (see the example vimrc file).
• or execute the Vim command :set syntax=asciidoc.
• or add the following line to the end of you AsciiDoc source files:
// vim: set syntax=asciidoc:

F

Attribute Options

Here is the list of predefined attribute list options:
Option
autowidth

Backends
xhtml11, html5,
html4

AsciiDoc Elements
table

unbreakable

xhtml11, html5

block elements

breakable,
unbreakable

docbook (XSL/FO)

table, example,
block image

compact

docbook, xhtml11,
html5
docbook, xhtml11,
html5, html4
docbook, xhtml11,
html5, html4
docbook (XSL/FO)

bulleted list,
numbered list
table

footer
header
pgwide

strong

G

xhtml11, html5,
html4

Description
The column widths are determined by the browser,
not the AsciiDoc cols attribute. If there is no width
attribute the table width is also left up to the
browser.
unbreakable attempts to keep the block element
together on a single printed page c.f. the breakable
and unbreakable docbook (XSL/FO) options
below.
The breakable options allows block elements to
break across page boundaries; unbreakable
attempts to keep the block element together on a
single page. If neither option is specified the
default XSL stylesheet behavior prevails.
Minimizes vertical space in the list
The last row of the table is rendered as a footer.

table

The first row of the table is rendered as a header.

table, block image,
horizontal labeled
list
labeled lists

Specifies that the element should be rendered
across the full text width of the page irrespective of
the current indentation.
Emboldens label text.

Diagnostics

The asciidoc(1) --verbose command-line option prints additional information to stderr: files processed, filters processed,
warnings, system attribute evaluation.

AsciiDoc User Guide
84 / 88

A special attribute named trace enables the output of element-by-element diagnostic messages detailing output markup generation
to stderr. The trace attribute can be set on the command-line or from within the document using Attribute Entries (the latter allows
tracing to be confined to specific portions of the document).
• Trace messages print the source file name and line number and the trace name followed by related markup.
• trace names are normally the names of AsciiDoc elements (see the list below).
• The trace message is only printed if the trace attribute value matches the start of a trace name. The trace attribute value can
be any Python regular expression. If a trace value is not specified all trace messages will be printed (this can result in large
amounts of output if applied to the whole document).
• In the case of inline substitutions:
– The text before and after the substitution is printed; the before text is preceded by a line containing <<< and the after text
by a line containing >>>.
– The subs trace value is an alias for all inline substitutions.
Trace names
 block close
 block open

dropped line (a line containing an undefined attribute reference).
floating title
footer
header
list close
list entry close
list entry open
list item close
list item open
list label close
list label open
list open
macro block (a block macro)
name (man page NAME section)
paragraph
preamble close
preamble open
push blockname
pop blockname
section close
section open: level 
subs (all inline substitutions)
table
Where:
•  is section level number 0. . . 4.
•  is a delimited block name: comment, sidebar, open, pass, listing, literal, quote, example.
•  is an inline substitution type: specialcharacters,quotes,specialwords, replacements, attributes,macros,callouts, replacements2, replacements3.
Command-line examples:

AsciiDoc User Guide
85 / 88

1. Trace the entire document.
$ asciidoc -a trace mydoc.txt
2. Trace messages whose names start with quotes or macros:
$ asciidoc -a ’trace=quotes|macros’

mydoc.txt

3. Print the first line of each trace message:
$ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE:
Attribute Entry examples:
1. Begin printing all trace messages:
:trace:
2. Print only matched trace messages:
:trace: quotes|macros
3. Turn trace messages off:
:trace!:

H

Backend Attributes

This table contains a list of optional attributes that influence the generated outputs.
Name
badges

Backends
xhtml11, html5

Description
Link badges (XHTML 1.1 and CSS) in document footers. By default badges are
omitted (badges is undefined).
Note
The path names of images, icons and scripts are relative path names to the output
document not the source document.

data-uri
css-signature

xhtml11, html5
html5, xhtml11

disablejavascript

xhtml11, html5

Embed images using the data: uri scheme.
Set a CSS signature for the document (sets the id attribute of the HTML body
element). CSS signatures provide a mechanism that allows users to personalize the
document appearance. The term CSS signature was coined by Eric Meyer.
If the disable-javascript attribute is defined the asciidoc.js
JavaScript is not embedded or linked to the output document. By default AsciiDoc
automatically embeds or links the asciidoc.js JavaScript to the output
document. The script dynamically generates table of contents and footnotes.

AsciiDoc User Guide
86 / 88

Name
docinfo,
docinfo1,
docinfo2

Backends
All backends

Description
These three attributes control which document information files will be included in
the the header of the output file:
docinfo
Include -docinfo.
docinfo1
Include docinfo.
docinfo2
Include docinfo. and -docinfo.
Where  is the file name (sans extension) of the AsciiDoc input file
and  is .html for HTML outputs or .xml for DocBook outputs. If the
input file is the standard input then the output file name is used. The following
example will include the mydoc-docinfo.xml docinfo file in the DocBook
mydoc.xml output file:
$ asciidoc -a docinfo -b docbook mydoc.txt
This next example will include docinfo.html and mydoc-docinfo.html
docinfo files in the HTML output file:
$ asciidoc -a docinfo2 -b html4 mydoc.txt

encoding

html4, html5,
xhtml11,
docbook

Set the input and output document character set encoding. For example the
--attribute encoding=ISO-8859-1 command-line option will set the
character set encoding to ISO-8859-1.
• The default encoding is UTF-8.
• This attribute specifies the character set in the output document.
• The encoding name must correspond to a Python codec name or alias.
• The encoding attribute can be set using an AttributeEntry inside the document
header. For example:
:encoding: ISO-8859-1

hr

html4

icons

xhtml11, html5

iconsdir

html4, html5,
xhtml11,
docbook

imagesdir

html4, html5,
xhtml11,
docbook
html4, html5,
xhtml11

keywords,
description, title

Defines the html4 inter-section horizontal ruler element. By default html4 top level
sections are separated by a horizontal ruler element, undefine this attribute or set it
to an empty string if you do not want them. The default html4 backend value for
the hr attribute is 
.
Link admonition paragraph and admonition block icon images and badge images.
By default icons is undefined and text is used in place of icon images.
The name of the directory containing linked admonition icons, navigation icons
and the callouts sub-directory (the callouts sub-directory contains callout
number images). iconsdir defaults to ./images/icons. If admonition icons are
embedded using the data-uri scheme then the iconsdir attribute defaults to the
location of the icons installed in the AsciiDoc configuration directory.
If this attribute is defined it is prepended to the target image file name paths in
inline and block image macros.
The keywords and description attributes set the correspondingly named HTML
meta tag contents; the title attribute sets the HTML title tag contents. Their
principle use is for SEO (Search Engine Optimisation). All three are optional, but
if they are used they must appear in the document header (or on the
command-line). If title is not specified the AsciiDoc document title is used.

AsciiDoc User Guide
87 / 88

Name
linkcss

Backends
html5, xhtml11

max-width

html5, xhtml11

numbered

plaintext

html4, html5,
xhtml11,
docbook (XSL
Stylesheets)
All backends

quirks

xhtml11

revremark

docbook

scriptsdir

html5, xhtml11

sgml

docbook45

stylesdir

html5, xhtml11

stylesheet
theme
toc

html5, xhtml11
html5, xhtml11
html5, xhtml11,
docbook (XSL
Stylesheets)

Description
Link CSS stylesheets and JavaScripts. By default linkcss is undefined in which
case stylesheets and scripts are automatically embedded in the output document.
Set the document maximum display width (sets the body element CSS max-width
property).
Adds section numbers to section titles. The docbook backend ignores numbered
attribute entries after the document header.

If this global attribute is defined all inline substitutions are suppressed and block
indents are retained. This option is useful when dealing with large amounts of
imported plain text.
Include the xhtml11-quirks.conf configuration file and
xhtml11-quirks.css stylesheet to work around IE6 browser
incompatibilities. This feature is deprecated and its use is discouraged —
documents are still viewable in IE6 without it.
A short summary of changes in this document revision. Must be defined prior to the
first document section. The document also needs to be dated to output this attribute.
The name of the directory containing linked JavaScripts. See HTML stylesheets
and JavaScript locations.
The --backend=docbook45 command-line option produces DocBook 4.5
XML. You can produce the older DocBook SGML format using the
--attribute sgml command-line option.
The name of the directory containing linked or embedded stylesheets. See HTML
stylesheets and JavaScript locations.
The file name of an optional additional CSS stylesheet.
Use alternative stylesheet (see Stylesheets).
Adds a table of contents to the start of an article or book document. The toc
attribute can be specified using the --attribute toc command-line option or
a :toc: attribute entry in the document header. The toc attribute is defined by
default when the docbook backend is used. To disable table of contents generation
undefine the toc attribute by putting a :toc!: attribute entry in the document
header or from the command-line with an --attribute toc! option.
xhtml11 and html5 backends
• JavaScript needs to be enabled in your browser.
• The following example generates a numbered table of contents using a
JavaScript embedded in the mydoc.html output document:
$ asciidoc -a toc -a numbered mydoc.txt

toc2

html5, xhtml11

toc-placement

html5, xhtml11

Adds a scrollable table of contents in the left hand margin of an article or book
document. Use the max-width attribute to change the content width. In all other
respects behaves the same as the toc attribute.
When set to auto (the default value) asciidoc(1) will place the table of
contents in the document header. When toc-placement is set to manual the TOC
can be positioned anywhere in the document by placing the toc::[] block macro
at the point you want the TOC to appear.
Note
If you use toc-placement then you also have to define the toc attribute.

toc-title

html5, xhtml11

Sets the table of contents title (defaults to Table of Contents).

AsciiDoc User Guide
88 / 88

Name
toclevels

Backends
html5, xhtml11

Description
Sets the number of title levels (1..4) reported in the table of contents (see the toc
attribute above). Defaults to 2 and must be used with the toc attribute. Example
usage:
$ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt

I

License

AsciiDoc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2
(GPLv2) as published by the Free Software Foundation.
AsciiDoc 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 version 2 for
more details.
Copyright © 2002-2011 Stuart Rackham.



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Page Count                      : 96
Page Mode                       : UseOutlines
Author                          : Stuart Rackham
Title                           : AsciiDoc User Guide
Subject                         : 
Creator                         : DBLaTeX-0.3.2-2
Producer                        : pdfTeX-1.40.10
Create Date                     : 2013:11:06 16:05:19+13:00
Modify Date                     : 2013:11:06 16:05:19+13:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.1415926-1.40.10-2.2 (TeX Live 2009/Debian) kpathsea version 5.0.0

EXIF Metadata provided by EXIF.tools