-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathasciidoc.txt
6030 lines (4843 loc) · 218 KB
/
asciidoc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
AsciiDoc User Guide
===================
Stuart Rackham <[email protected]>
:Author Initials: SJR
:toc:
:icons:
:numbered:
:website: http://asciidoc.org/
[role="summary"]
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 <<X6,Getting
Started>> section and take a look at the example AsciiDoc (`*.txt`)
source files in the distribution `doc` directory.
**********************************************************************
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 <<X11,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.
**********************************************************************
[[X6]]
Getting Started
---------------
Installing AsciiDoc
~~~~~~~~~~~~~~~~~~~
See the `README` and `INSTALL` files for install prerequisites and
procedures. Packagers take a look at <<X38,Packager Notes>>.
[[X11]]
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 {website}. 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 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.
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
<<X93,section markup templates>> (appendix, abstract, bibliography,
glossary, index).
book
~~~~
Books share the same format as articles, with the following
differences:
- The part titles in multi-part books are <<X17,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
<<X93,section markup templates>> (appendix, dedication, preface,
bibliography, glossary, index, colophon).
.Example 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.
manpage
~~~~~~~
Used to generate roff format UNIX manual pages. AsciiDoc manpage
documents observe special header title and section naming conventions
-- see the <<X1,Manpage Documents>> section for details.
AsciiDoc defines the 'synopsis' <<X93,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.
[[X5]]
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
<<X88,Backend Attributes>> section.
docbook45::
Outputs DocBook XML 4.5 markup.
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
<<X98,audio and video block macros>> it is functionally identical to
the 'xhtml11' backend.
slidy::
Use this backend to generate self-contained
http://www.w3.org/Talks/Tools/Slidy2/[Slidy] HTML slideshows for
your web browser from AsciiDoc documents. The Slidy backend is
documented in the distribution `doc/slidy.txt` file and
{website}slidy.html[online].
wordpress::
A minor variant of the 'html4' backend to support
http://srackham.wordpress.com/blogpost1/[blogpost].
latex::
Experimental LaTeX backend.
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-<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
[[X100]]
Backend Plugins
~~~~~~~~~~~~~~~
The asciidoc(1) `--backend` option is also used to install and manage
backend <<X101,plugins>>.
- A backend plugin is used just like the built-in backends.
- Backend plugins <<X27,take precedence>> over built-in backends with
the same name.
- You can use the `{asciidoc-confdir}` <<X60, intrinsic attribute>> to
refer to the built-in backend configuration file location from
backend plugin configuration files.
- You can use the `{backend-confdir}` <<X60, intrinsic attribute>> to
refer to the backend plugin configuration file location.
- By default backends plugins are installed in
`$HOME/.asciidoc/backends/<backend>` where `<backend>` is the
backend name.
DocBook
-------
AsciiDoc generates 'article', 'book' and 'refentry'
http://www.docbook.org/[DocBook] documents (corresponding to the
AsciiDoc 'article', 'book' and 'manpage' document types).
Most Linux distributions come with conversion tools (collectively
called a toolchain) for <<X12,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 http://live.gnome.org/Yelp[Yelp]
(the GNOME help viewer).
[[X12]]
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.
[[X43]]
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 <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and
optionally: <<X31,dblatex>> or <<X14,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-filter.txt` 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.
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 {website}[AsciiDoc
website]).
PDF generation
~~~~~~~~~~~~~~
There are two commonly used tools to generate PDFs from DocBook,
<<X31,dblatex>> and <<X14,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.
- '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 <<X13,DocBook XSL Stylesheets>>.
- 'FOP' is more feature complete (for example, callouts are processed
inside literal layouts) and arguably produces nicer looking output.
HTML Help generation
~~~~~~~~~~~~~~~~~~~~
. Convert DocBook XML documents to HTML Help compiler source files
using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>.
. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
(`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>.
Toolchain components summary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
AsciiDoc::
Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
[[X13]]http://docbook.sourceforge.net/projects/xsl/[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
<<X40,xsltproc(1)>>.
[[X40]]http://www.xmlsoft.org[xsltproc]::
An XML parser for applying XSLT stylesheets (in our case the
<<X13,DocBook XSL Stylesheets>>) to XML documents.
[[X31]]http://dblatex.sourceforge.net/[dblatex]::
Generates PDF, DVI, PostScript and LaTeX formats directly from
DocBook source via the intermediate LaTeX typesetting language --
uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and
`latex(1)`.
[[X14]]http://xml.apache.org/fop/[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 <<X13,DocBook XSL Stylesheets>> and
<<X40,xsltproc(1)>>.
[[X67]]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.
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 <<X31,dblatex>> output customization and are used by
<<X43,a2x(1)>>.
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-xsl.css` 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 <<X43,a2x(1)>>.
`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 <<X43,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`.
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 <<X43,a2x(1)>> toolchain wrapper
utility.
[[X35]]
HTML5 and XHTML 1.1
-------------------
The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript
files in their outputs, there is also a <<X99,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 <<X27,configuration directories>> to the correct location
relative to the output document.
.Stylesheet file locations
[cols="3*",frame="topbot",options="header"]
|====================================================================
|'stylesdir' attribute
|Linked location ('linkcss' attribute defined)
|Embedded location ('linkcss' attribute undefined)
|Undefined (default).
|Same directory as the output document.
|`stylesheets` subdirectory in the AsciiDoc configuration directory
(the directory containing the backend conf file).
|Absolute or relative directory name.
|Absolute or relative to the output document.
|Absolute or relative to the AsciiDoc configuration directory (the
directory containing the backend conf file).
|====================================================================
.JavaScript file locations
[cols="3*",frame="topbot",options="header"]
|====================================================================
|'scriptsdir' attribute
|Linked location ('linkcss' attribute defined)
|Embedded location ('linkcss' attribute undefined)
|Undefined (default).
|Same directory as the output document.
|`javascripts` subdirectory in the AsciiDoc configuration directory
(the directory containing the backend conf file).
|Absolute or relative directory name.
|Absolute or relative to the output document.
|Absolute or relative to the AsciiDoc configuration directory (the
directory containing the backend conf file).
|====================================================================
[[X99]]
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 <<X27,configuration directory>>
named `themes/<theme>/` (where `<theme>` 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 <<X101,plugins>>.
- AsciiDoc ships with two themes: 'flask' and 'volnitsky'.
- The `<theme>.css` file replaces the default `asciidoc.css` CSS file.
- The `<theme>.js` file is included in addition to the default
`asciidoc.js` JavaScript file.
- If the <<X66,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 <<X35,other CSS and JavaScript files>>.
For example, the command-line option `--theme foo` (or `--attribute
theme=foo`) will cause asciidoc(1) to search <<X27,configuration
file locations 1, 2 and 3>> for a sub-directory called `themes/foo`
containing the stylesheet `foo.css` and optionally a JavaScript file
name `foo.js`.
Document Structure
------------------
An AsciiDoc document consists of a series of <<X8,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.
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
footnote:[This is a rough structural guide, not a rigorous syntax
definition]:
Document ::= (Header?,Preamble?,Section*)
Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
Preamble ::= (SectionBody)
Section ::= (Title,SectionBody?,(Section)*)
SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
Block ::= (Paragraph|DelimitedBlock|List|Table)
List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
BulletedList ::= (ListItem)+
NumberedList ::= (ListItem)+
CalloutList ::= (ListItem)+
LabeledList ::= (ListEntry)+
ListEntry ::= (ListLabel,ListItem)
ListLabel ::= (ListTerm+)
ListItem ::= (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.
- 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 <<X15,list continuation element>>.
[[X95]]
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 <<X17,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 <<X18,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 <[email protected]>
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][ <email>]]
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 <[email protected]>
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:
. 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.
* 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.
--
. 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 <<X18,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.
[[X87]]
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 <<X7,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 <<X97,docinfo, docinfo1
and docinfo2>> 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.
[[X86]]
Preamble
~~~~~~~~
The Preamble is an optional untitled section body between the document
Header and the first Section title.
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 <<X17,titles>>. Sections are translated using
configuration file <<X93,section markup templates>>. AsciiDoc
generates the following <<X60,intrinsic attributes>> specifically for
use in section markup templates:
level::
The `level` attribute is the section level number, it is normally just
the <<X17,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 <<X90,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).
[[X93]]
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
<<X16,`[specialsections]`>> entry.
3. If neither of the above the default `sect<level>` template is used
(where `<level>` 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.
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:
- 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.
[[X16]]
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'
<<X93,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:
<title>=<template>
`<title>` is a Python regular expression and `<template>` is the name
of a configuration file markup template section. If the `<title>`
matches an AsciiDoc document section title then the backend output is
marked up using the `<template>` markup template (instead of the
default `sect<level>` section template). The `{title}` attribute value
is set to the value of the matched regular expression group named
'title', if there is no 'title' group `{title}` defaults to the whole
of the AsciiDoc section title. If `<template>` is blank then any
existing entry with the same `<title>` will be deleted.
.Special section titles vs. explicit template names
*********************************************************************
AsciiDoc has two mechanisms for specifying non-default section markup
templates: you can specify the template name explicitly (using the
'template' attribute) or indirectly (using 'special section titles').
Specifying a <<X93,section template>> attribute explicitly is
preferred. Auto-magical 'special section titles' have the following
drawbacks:
- They are non-obvious, you have to know the exact matching
title for each special section on a language by language basis.
- Section titles are predefined and can only be customised with a
configuration change.
- The implementation is complicated by multiple languages: every
special section title has to be defined for each language (in each
of the `lang-*.conf` files).
Specifying special section template names explicitly does add more
noise to the source document (the 'template' attribute declaration),
but the intention is obvious and the syntax is consistent with other
AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
Special section titles have been deprecated but are retained for
backward compatibility.
*********************************************************************
Inline Elements
~~~~~~~~~~~~~~~
<<X34,Inline document elements>> are used to format text and to
perform various types of text substitution. Inline elements and inline
element syntax is defined in the asciidoc(1) configuration files.
Here is a list of AsciiDoc inline elements in the (default) order in
which they are processed:
Special characters::
These character sequences escape special characters used by
the backend markup (typically `<`, `>`, and `&` characters).
See `[specialcharacters]` configuration file sections.
Quotes::
Elements that markup words and phrases; usually for character
formatting. See `[quotes]` configuration file sections.
Special Words::
Word or word phrase patterns singled out for markup without
the need for further annotation. See `[specialwords]`
configuration file sections.
Replacements::
Each replacement defines a word or word phrase pattern to
search for along with corresponding replacement text. See
`[replacements]` configuration file sections.
Attribute references::
Document attribute names enclosed in braces are replaced by
the corresponding attribute value.
Inline Macros::
Inline macros are replaced by the contents of parametrized
configuration file sections.
Document Processing
-------------------
The AsciiDoc source document is read and processed as follows:
1. The document 'Header' is parsed, header parameter values are
substituted into the configuration file `[header]` template section
which is then written to the output file.
2. Each document 'Section' is processed and its constituent elements
translated to the output file.
3. The configuration file `[footer]` template section is substituted
and written to the output file.
When a block element is encountered asciidoc(1) determines the type of
block by checking in the following order (first to last): (section)
Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
AttributeLists, BlockTitles, Paragraphs.
The default paragraph definition `[paradef-default]` is last element
to be checked.
Knowing the parsing order will help you devise unambiguous macro, list
and block syntax rules.
Inline substitutions within block elements are performed in the
following default order:
1. Special characters
2. Quotes
3. Special words
4. Replacements
5. Attributes
6. Inline Macros
7. Replacements2
The substitutions and substitution order performed on
Title, Paragraph and DelimitedBlock elements is determined by
configuration file parameters.
Text Formatting
---------------
[[X51]]
Quoted Text
~~~~~~~~~~~
Words and phrases can be formatted by enclosing inline text with
quote characters:
_Emphasized text_::
Word phrases \'enclosed in single quote characters' (acute
accents) or \_underline characters_ are emphasized.
*Strong text*::
Word phrases \*enclosed in asterisk characters* are rendered
in a strong font (usually bold).
[[X81]]+Monospaced text+::
Word phrases \+enclosed in plus characters+ are rendered in a
monospaced font. Word phrases \`enclosed in backtick
characters` (grave accents) are also rendered in a monospaced
font but in this case the enclosed text is rendered literally
and is not subject to further expansion (see <<X80,inline
literal passthrough>>).
`Single quoted text'::
Phrases enclosed with a \`single grave accent to the left and
a single acute accent to the right' are rendered in single
quotation marks.
``Double quoted text''::
Phrases enclosed with \\``two grave accents to the left and
two acute accents to the right'' are rendered in quotation
marks.
#Unquoted text#::
Placing \#hashes around text# does nothing, it is a mechanism
to allow inline attributes to be applied to otherwise
unformatted text.
New quote types can be defined by editing asciidoc(1) configuration
files. See the <<X7,Configuration Files>> section for details.
.Quoted text behavior
- Quoting cannot be overlapped.
- Different quoting types can be nested.
- To suppress quoted text formatting place a backslash character
immediately in front of the leading quote character(s). In the case
of ambiguity between escaped and non-escaped text you will need to
escape both leading and trailing quotes, in the case of
multi-character quotes you may even need to escape individual
characters.
[[X96]]
Quoted text attributes