Source

asciidoc / doc / faq.txt

Full commit
   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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
AsciiDoc Frequently Asked Questions
===================================


[NOTE]
======
- New FAQs are normally added at the top of this document.
- The FAQ may be updated between AsciiDoc releases so some of the
  newer FAQs may apply to the trunk and not the current release.
======

[[X5]]
== How can I include embedded fonts in an EPUB document
This is a two step process:

1. Declare the font files and their use in your document's CSS
   stylesheet. For example:
+
[listing]
.........................................
@font-face {
  font-family : LiberationSerif-Regular;
  font-weight : normal;
  font-style: normal;
  src : url(LiberationSerif-Regular.ttf);
}

body {
  font-family: LiberationSerif-Regular, serif;
}
.........................................

2. Declare the the font file as resource when you use `a2x(1)` to
   compile the EPUB. For example:

  a2x -f epub -d book --epubcheck --stylesheet epubtest.css --resource .ttf=application/x-font-ttf --resource LiberationSerif-Regular.ttf epubtest.txt

[NOTE]
======
- Requires AsciiDoc 8.6.5 or better.
- The True Type Font mimetype had to be declared explicitly with the
  `--resource .ttf=application/x-font-ttf` option because it wasn't
  registered on my Linux system.
- In the above example the font file is in the same directory as the
  AsciiDoc source file and is installed to the same relative location
  in the EPUB archive OEBPS directory -- if your font file resides in
  a different location you'll need to adjust the `--resource` option
  accordingly (see the 'RESOURCES' section in the `a2x(1)` man page
  for details).
- The URL value of the CSS 'src' property is set to the destination
  font file relative the the CSS file.
- The `--resource` option allows you to inject any file (not just font
  files) into the EPUB output document.
- Using the CSS '@font-face' rule is a complex subject and is outside
  the scope of the FAQ.
- Many EPUB readers do not process embedded fonts.
======


== What's the difference between + quoted text and ` quoted monospaced text?
`+` (plus) quoted text is implemented as an AsciiDoc 'quotes' whereas
+`+ (grave accent or backtick) quoted text is implemented as an
AsciiDoc 'inline literal' passthrough macro. The semantics are
different:

1. Inline passthrough macros are processed before any other inline
   substitutions e.g. all of the following line will be processed as a
   single inline passthrough and rendered as monospaced text (which is
   not the intended result):
+
--
  `single quoted text' and `monospaced quoted text`

This line works as expected:

  `single quoted text' and +monospaced quoted text+
--

2. Backtick quoted text is rendered literally i.e. no substitutions
   are performed on the enclosed text.  Here are some examples that
   would have to be escaped if plus quoting were used (<<X4,see
   also>>):

  The `++i` and `++j` auto-increments.
  Paths `~/.vim` and `~/docs`.
  The `__init__` method.
  The `{id}` attribute.


== Why is the generated HTML title element text invalid?
Probably because your document title contains formatting that has
generated HTML title markup. You can resolve this by explicitly
defining the 'title' attribute in your document's header.


== AsciiDoc sometimes generates invalid output markup, why?
AsciiDoc is backend agnostic, the 'asciidoc' command has no knowledge
of the syntax or structure of the backend format that it generates.
Output document validation (syntactic and structural) should be
performed separately by external validation tools. For example,
AsciiDoc's 'a2x' toolchain command automatically performs validation
checks using 'xmllint'.


== The AsciiDoc toclevels attribute does not work with DocBook outputs, why?
DocBook has no provision for specifying table of contents levels but
you can set the TOC level further down the toolchain by passing the
DocBook XSL Stylesheets
http://docbook.sourceforge.net/release/xsl/current/doc/html/toc.section.depth.html[toc.section.depth]
parameter to 'dblatex' (using the `--param` option) or 'xsltproc'
(using the `--stringparam` option).  For example to show only chapter
titles in the TOC of a 'book' document set 'toc.section.depth' to '0'.
Increment the 'toc.section.depth' value to show more sub-section
titles. If you are using 'a2x' you can set the options in the source
file, for example:

  // a2x: --xsltproc-opts "--stringparam toc.section.depth 0"
  // a2x: --dblatex-opts "--param toc.section.depth=0"

If the document is of type 'article' use the value '1' to show only
top level section titles in the TOC, use the value '2' for two levels
etc.


== How can I include chapter and section tables of contents?
DocBook outputs processed by DocBook XSL Stylesheets (either manually
or via 'a2x') can generate additional separate section and chapter
tables of contents using combinations of the
http://www.sagehill.net/docbookxsl/TOCcontrol.html[TOC parameters].
Here are some examples using combinations of the
`generate.section.toc.level` and `toc.section.depth` DocBook XSL
Stylesheets parameters:

[cols="2*l,4",width="90%",frame="topbot",options="header"]
|======================================================
|generate.section.toc.level |toc.section.depth |
|1 |
|Single level book chapter TOCs or article section TOCs

|1 | 3
|Article section TOCs with two levels

|1 | 2
|Book chapter TOCs with two levels
|======================================================


== How can I customize the appearance of XHTML and EPUB documents generated by a2x?
You can customize the appearance of an EPUB document with CSS.  See
the link:publishing-ebooks-with-asciidoc.html[Sherlock Holmes eBook
example] on the AsciiDoc website.


== DocBook has many elements for document meta-data -- how can I use them from AsciiDoc?
The 'docinfo', 'docinfo1' and 'docinfo2' attributes allow you include
link:userguide.html#X97[document information files] containing DocBook
XML into the header of the output file.


== Do element titles automatically generate link captions?
If you go the DocBook route then yes -- just omit the caption from the
AsciiDoc 'xref' (`<<...>>`) macro. Both dblatex and DocBook XSL will
use the target element's title text. Examples:

[listing]
..................................................................
[[X1]]
Section One
-----------
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta

See also <<X3>> (this link displays the text 'A titled paragraph').

[id="X2",reftext="2nd section"]
Section Two
-----------
See also <<X1>> (this link displays the text 'Section One').

[[X3]]
.A titled paragraph
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

See also <<X2>> (this link displays the text '2nd section').
..................................................................

The AsciiDoc 'reftext' attribute has been used to explicitly set the
link text to '2nd section' for 'Section Two'.


== Can I define my own table styles?
In addition to the built-in styles you can define your own. This
example (for the 'xhtml11' backend) defines a table style called 'red'
which sets the background cell color to red. First put the definition
in a configuration file:

[listing]
.........................................
[tabledef-default]
red-style=tags="red"

[tabletags-red]
bodydata=<td style="background-color:red;">|</td>
.........................................

Now you can use the style name to style cells or columns (in this
example we use an unambiguous shortened abbreviation 'r'):

[listing]
.........................................
|==================================
|Normal cell      r|Red cell
|==================================
.........................................


== How can I add highlighted editorial comments to an AsciiDoc document?
Both block and inline link:userguide.html#X25[comment lines] are
displayed on the output if the 'showcomments' attribute is defined.
Example:

[listing]
.........................................
:showcomments:
// A block comment line.

Qui in magna commodo, est labitur dolorum an. Est ne magna primis
// An inline comment line.
adolescens.
.........................................

Is rendered as:

:showcomments:
// A block comment line.

Qui in magna commodo, est labitur dolorum an. Est ne magna primis
// An inline comment line.
adolescens.

NOTE: link:userguide.html#X26[Comment blocks] are never displayed.


== What is the preferred file name extension for AsciiDoc files?
The `.txt` http://en.wikipedia.org/wiki/Text_file[text file] extension
is preferred, but it's just a convention and it's not enforced by the
software.

AsciiDoc source files are human readable
http://en.wikipedia.org/wiki/Plain_text[plain text] files which is
what the `.txt` extension is for. All text editors recognize and open
files with a `.txt` extension. The `.txt` extension is universally
recognized and unambiguous -- you are not left asking questions like
``What on earth is this file with the funny extension?'', ``How do I
open it?'' and ``Is it safe to open?''.


== How can I generate numbered bibliographic entries?
If your outputs are DocBook generated then adding the following inline
macro to a custom configuration file will result in auto-incrementing
bibliography entry numbers (instead of displaying the bibliographic
identifiers):

  [anchor3-inlinemacro]
  <anchor id="{1}" xreflabel="[{counter:bibliography1}]"/>[{counter:bibliography2}]

This FAQ submitted by Bela Hausmann.


== How can I include lines of dashes inside a listing block?
A line of four or more dashes will be mistaken for the ListingBlock
terminator, one way round this problem is to use a LiteralBlock styled
as a listing block. For example:

  [listing]
  ...........................
  Lorum ipsum
  -----------
  ...........................


== How can I customize PDF files generated by dblatex?

There are a number of dblatex XSL parameters that can be used to
customize PDF output. You can set them globally in the AsciiDoc
`./dblatex/asciidoc-dblatex.xsl` configuration file or you can also
pass them on the a2x(1) command-line. Here are some examples:

The
http://dblatex.sourceforge.net/doc/manual/latex.output.revhistory.html[latex.output.revhistory]
parameter is used to suppress the revision history:

  a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt

The
http://dblatex.sourceforge.net/doc/manual/doc.layout.html[doc.layout]
parameter is used to include the cover page and document body (i.e. excludes
table of contents and index), the
http://dblatex.sourceforge.net/doc/manual/doc.publisher.show.html[doc.publisher.show]
parameter is used to exclude the cover page logo:

  a2x -f pdf --dblatex-opts " -P doc.layout=\"coverpage mainmatter\" -P doc.publisher.show=0" doc/article.txt

See also the
http://dblatex.sourceforge.net/doc/manual/sec-params.html[dblatex XSL
parameter reference].


== How can I add lists of figures and tables to PDFs created by dblatex?
Set the
http://dblatex.sourceforge.net/doc/sec-custom.html[doc.lot.show XSL
parameter] -- you can set it using the dblatex `--param` command-line
option, for example:

  $ a2x --dblatex-opts="--param=doc.lot.show=figure,table" doc/article.txt


== How can I stop the document title being displayed?
You could simply omit the document title, but this will result in a
blank 'title' element in HTML outputs. If you want the HTML 'title'
element to contain the document title then define the 'notitle'
attribute (this will just suppress displaying the title), for example:

  My document title
  =================
  :no title:


== Why am I having trouble getting nested macros to work?
The following example expands the 'image' inline macro, but the
expansion contains double-quote characters which confuses the ensuing
'footnoteref' macro expansion:

  footnoteref:["F1","A footnote, with an image image:smallnew.png[]"]

The solution is to use unquoted attribute values, replacing embedded
commas with the comma character entity (`&#44;`):

  footnoteref:[F1,A footnote&#44; with an image image:smallnew.png[]]

Similarly, you can embed double-quote characters in unquoted attribute
values using the `&#34;` character entity.


== Why am I getting DocBook validation errors?
Not all valid AsciiDoc source generates valid DocBook, for example
'special sections' (abstract, preface, colophon, dedication,
bibliography, glossary, appendix, index, synopsis) have different
DocBook schema's to normal document sections. For example, a paragraph
is illegal in a bibliography.

Don't forget if your document is a book you need to specify the
asciidoc `-d book` command option, if you don't an article DocBook
document will be generated, possibly containing book specific
sections, resulting in validation errors.


== How can I disable special section titles?
For example, you want to use 'References' as a normal section name but
AsciiDoc is auto-magically generating a DocBook 'bibliography'
section. All you need to do is explicitly specify the section template
name, for example:

  [sect1]
  References
  ----------


== How can I insert XML processing instructions into output documents?
Use an inline or block passthrough macros. This example inserts
`<?dblatex bgcolor="#cceeff"?>` into the DocBook output generated by
AsciiDoc:

  pass::[<?dblatex bgcolor="#cceeff"?>]

NOTE: XML processing instructions are specific to the application that
processes the XML (the previous `dblatex` processing instruction is
recognized by `dblatex(1)` when it processes the DocBook XML generated
by Asciidoc).


[[X4]]
== How do I prevent double-quoted text being mistaken for an inline literal?
Mixing doubled-quoted text with inline literal passthroughs can
produce undesired results, for example, all of the following line is
interpreted as an inline literal passthrough:

  ``XXX'' `YYY`

In this case the solution is to use monospace quoting instead of the
inline literal:

  ``XXX'' +YYY+

Use the +\pass:[]+ macro if it's necessary to suppress
substitutions in the monospaced text, for example:

  ``XXX'' +pass:[don't `quote` me]+


== How can I generate a single HTML document file containing images and CSS styles?
With the advent of Internet Explorer 8 all major web browsers now
support the
http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme] for
embedded images. The AsciiDoc 'xhtml11' backend supports the data URI
scheme for embedded images and by default it embeds the CSS
stylesheet. For example the following command will generate a single
`article.html` file containing embedded images, admonition icons and the CSS
stylesheet:

  $ asciidoc -a data-uri -a icons article.txt


== Are there any tools to help me understand what's going on inside AsciiDoc?

AsciiDoc has a built-in trace mechanism which is controlled by the
'trace' attribute; there is also the `--verbose` command-line option.
These features are detailed in
http://www.methods.co.nz/asciidoc/userguide.html#X82[Appendix G of the
User Guide].


== One-liner ifdef::[]'s are disproportionately verbose can they shortened?

This is the response to a question posted on the AsciiDoc discussion
list, it illustrates a number of useful techniques. The question arose
because the source highlight filter language identifier for the C++
language is `c++` when generating PDFs via dblatex (LaTeX listings
package) or `cpp` when generating HTML (GNU source-highlight).

Using straight `ifdef::[]` block macros we have:

[listing]
.........................................
\ifdef::basebackend-docbook[]
[source,c++]
\endif::basebackend-docbook[]
\ifdef::basebackend-html[]
[source,cpp]
\endif::basebackend-html[]
-----------------------------------------
class FooParser {
public:
        virtual void startDocument() = 0;
        virtual void endDocument() = 0;
};
-----------------------------------------
.........................................


This can be shortened using the short form of the `ifdef::[]` macro:

[listing]
.........................................
\ifdef::basebackend-docbook[[source,c++]]
\ifdef::basebackend-html[[source,cpp]]
-----------------------------------------
class FooParser {
public:
        virtual void startDocument() = 0;
        virtual void endDocument() = 0;
};
-----------------------------------------
.........................................


Using a conditional attribute instead of the `ifdef::[]` macro is even
shorter:

[listing]
.........................................
[source,{basebackend@docbook:c++:cpp}]
-----------------------------------------
class FooParser {
public:
        virtual void startDocument() = 0;
        virtual void endDocument() = 0;
};
-----------------------------------------
.........................................


If you have a number of listings it makes sense to factor the
conditional attribute to a normal attribute:

[listing]
.........................................
:cpp: {basebackend@docbook:c++:cpp}

[source,{cpp}]
-----------------------------------------
class FooParser {
public:
        virtual void startDocument() = 0;
        virtual void endDocument() = 0;
};
-----------------------------------------
.........................................


Even shorter, set the default source highlight filter `language`
attribute so you don't have to specify it every time:

[listing]
.........................................
:language: {basebackend@docbook:c++:cpp}

[source]
-----------------------------------------
class FooParser {
public:
        virtual void startDocument() = 0;
        virtual void endDocument() = 0;
};
-----------------------------------------
.........................................


== Some of my inline passthroughs are not passed through, why?

Most likely the passthrough encloses another passthrough with a higher
precedence. For example trying to render this +\pass:[]+ with this
+\`\pass:[]`+ results in a blank string because the +\pass:[]+
passthrough evaluates first, instead use monospaced quoting  and escape
the passthrough i.e. ++ \+\\pass:[]+ ++


== How can I place an anchor (link target) on a list item?

You can't use a 'BlockId' block element inside a list but you can use
the syntactically identical 'anchor' inline macro. For example:

---------------------
one:: Item one.
[[X2]]two:: Item two.
three:: Item three.
---------------------

This *will not* work:

---------------------
one:: Item one.
[[X2]]
two:: Item two.
three:: Item three.
---------------------


== How can I stop lists from nesting?

If you place two lists with different syntax hard up against each
other then the second list will be nested in the first. If you don't
want the second list to be nested separate them with a comment line
block macro. For example:

-------------------
1. List 1.
2. List 1.

//
a. List 2.
b. List 2.
-------------------


== Is it possible to include charts in AsciiDoc documents?

There are a number of programs available that generate presentation
charts from textual specification, for example
http://home.gna.org/pychart/[Pychart] is a library for writing chart
scripts in Python. Here's an example from the 'Pychart' documentation:

.barchart.py
---------------------------------------------------------------------
#
# Example bar chart (from Pychart documentation http://home.gna.org/pychart/).
#
from pychart import *
theme.get_options()

data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7),
        (50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5),
        (90, 42, 39, 5), (100, 32, 39, 4)]

# The attribute y_coord=... tells that the Y axis values
# should be taken from samples.
# In this example, Y values will be [40,50,60,70,80].
ar = area.T(y_coord = category_coord.T(data[3:8], 0),
            x_grid_style=line_style.gray50_dash1,
            x_grid_interval=20, x_range = (0,100),
            x_axis=axis.X(label="X label"),
            y_axis=axis.Y(label="Y label"),
            bg_style = fill_style.gray90,
            border_line_style = line_style.default,
            legend = legend.T(loc=(80,10)))

# Below call sets the default attributes for all bar plots.
chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data)

# Attribute cluster=(0,3) tells that you are going to draw three bar
# plots side by side.  The plot labeled "foo" will the leftmost (i.e.,
# 0th out of 3).  Attribute hcol tells the column from which to
# retrive sample values from.  It defaults to one.
ar.add_plot(bar_plot.T(label="foo", cluster=(0,3)))
ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3)))
ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3)))
ar.draw()
---------------------------------------------------------------------

To execute the script and include the generated chart image in your
document add the following lines to the AsciiDoc source:

---------------------------------------------------------------------
// Generate chart image file.
\sys2::[python "{indir}/barchart.py" --format=png --output="{outdir}/barchart.png" --scale=2]

// Display chart image file.
image::barchart.png[]
---------------------------------------------------------------------

[NOTE]
=====================================================================
- The `barchart.py` script is located in the same directory as the
  AsciiDoc source file (`{indir}`).
- The generated chart image file (`barchart.png`) is written to the
  same directory as the output file (`{outdir}`).
=====================================================================

== How can I render indented paragraphs?

To unconditionally indent all paragraphs add the following line to the
`xhtml11.css` stylesheet (or a custom stylesheet).

---------------------------------------------------------------------
div.paragraph p {text-indent: 3em;}
---------------------------------------------------------------------

This will restyle the entire document by indenting all paragraphs
which is normally what you want to do (mixed paragraph styles produce
ugly documents).

To selectively indent paragraphs you could either create an 'indented'
paragraph style from scratch or use the 'role' attribute.

[float]
==== Create an indented paragraph style
Define an 'indented' paragraph style, for example, by putting this in
a configuration file:

---------------------------------------------------------------------
[paradef-default]
indented-style=template="indentedparagraph"

[indentedparagraph]
<div class="paragraph"{id? id="{id}"} style="text-indent:3em;">{title?<div class="title">{title}</div>}<p>
|
</p></div>
---------------------------------------------------------------------

Now apply the 'indented' style to normal paragraphs, for example:

---------------------------------------------------------------------
[indented]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
lacinia. Vivamus at lectus.
---------------------------------------------------------------------

[float]
==== Use the role attribute
Add the following line to the `xhtml11.css` stylesheet (or a custom
stylesheet).

---------------------------------------------------------------------
div.paragraph.indented p {text-indent: 3em;}
---------------------------------------------------------------------

Apply the 'role' attribute to indented paragraphs, for example:

---------------------------------------------------------------------
[role="indented"]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
lacinia. Vivamus at lectus.
---------------------------------------------------------------------

NOTE: This FAQ applies to XHTML output not DocBook. To achieve the
same results with DocBook use the 'role' attribute and customize the
DocBook XSL stylesheets to indent paragraphs with the `simpara`
element `role="indented"` attribute.


== Is there a way to set default image height and width attributes?

You can set the 'height' and 'width' attributes globally in your
document with Attribute Entries or from the command-line using the
`--attribute` option. In the following example images that don't
explicitly set the 'height' and 'width' values will be 350 by 250
pixels.

---------------------------------------------------------------------
:height: 250
:width: 350

image:images/tiger.png[]
---------------------------------------------------------------------

NOTE: Setting the global 'width' attribute will also set the default
table width and you will need to explicitly set table widths.

== How can I place a backslash character in front of an attribute reference without escaping the reference?

Use the predefined `{backslash}` attribute reference instead of an
actual backslash, for example if the `{projectname}` attribute has
the value `foobar` then:

  d:\data{backslash}{projectname}

would be rendered as:

  d:\data\foobar

== How can I escape AsciiDoc markup?

Most AsciiDoc inline elements can be suppressed by preceding them with
a backslash character. These elements include:

- Attribute references.
- Text formatting.
- Quoting,
- Macros.
- Replacements.
- Special words.
- Table cell separators.

But there are exceptions -- see the next question.


== Some elements can't be escaped with a single backslash

There are a number of  exceptions to the usual single backslash rule
-- mostly relating to URL macros that  have two syntaxes or quoting
ambiguity.  Here are some non-standard escape examples:

[cols="l,v",width="40%",frame="topbot",options="header"]
|========================================
|AsciiDoc | Renders

2*|
\srackham@methods.co.nz
<\srackham@methods.co.nz>
\mailto:[\srackham@methods.co.nz]

2*|
\http://www.foo1.co.nz
\\http://www.foobar.com[]
\\http://www.foobar.com[Foobar Limited]

2*|
A C\++ Library for C++
\\``double-quotes''
\*\*F**ile Open\...
|========================================

The source of this problem is ambiguity across substitution types --
the first match unescapes allowing the second to substitute. A
work-around for difficult cases is to side-step the problem using the
+\pass:[]+ passthrough inline macro.

NOTE: Escaping is unnecessary inside 'inline literal passthroughs'
(backtick quoted text).


== How can I escape a list?
Here's how to handle situations where the first line of a paragraph is
mistaken for a list item.

[float]
==== Numbered and bulleted lists
Precede the bullet or index of the first list item with an `{empty}`
attribute, for example:

  {empty}- Qui in magna commodo est labitur dolorum an.  Est ne magna
  primis adolescens.

The predefined `{empty}` attribute is replaced by an empty string and
ensures the first line is not mistaken for a bulleted list item.

[float]
==== Labeled lists
Two colons or semicolons in a paragraph may be confused with a labeled
list entry. Use the predefined `{two-colons}` and `{two-semicolons}`
attributes to suppress this behavior, for example:

  Qui in magna commodo{two-colons} est labitur dolorum an. Est ne
  magna primis adolescens.

Will be rendered as:

Qui in magna commodo{two-colons} est labitur dolorum an. Est ne
magna primis adolescens.


== How can I set default list and tables styles?

You can set the element's 'style' entry in a global or custom
configuration file.

This example this will horizontally style all labeled lists that don't
have an explicit style attribute:

----------------------------------
[listdef-labeled]
style=horizontal

[listdef-labeled2]
style=horizontal
----------------------------------

This example will put a top and bottom border on all tables that don't
already have an explicit style attribute:

----------------------------------
[tabledef-default]
style=topbot
topbot-style=frame="topbot"
----------------------------------

Alternatively you can set the configuration entries from inside your
document, the above examples are equivalent to:

----------------------------------
:listdef-labeled.style: horizontal
:listdef-labeled2.style: horizontal

:tabledef-default.topbot-style: frame="topbot"
:tabledef-default.style: topbot
----------------------------------


== Why do I get a filter non-zero exit code error?

An error was returned when AsciiDoc tried to execute an external
filter command. The most common reason for this is that the filter
command could not be found by the command shell. To figure out what
the problem is run AsciiDoc with the `--verbose` option to determine
the command that is failing and then try to run the command manually
from the command-line.


== Are there any DocBook viewers?

http://live.gnome.org/Yelp[Yelp], the GNOME help viewer, does a
creditable job of displaying DocBook XML files directly.


== Can you create ODF documents using AsciiDoc?

The easiest and highest fidelity method I've seen is to generate
HTML from AsciiDoc then paste it from your browser (we use Firefox)
into OpenOffice Writer.

- I found that that there is better fidelity pasting HTML generated by
  the 'html4' backend instead of the default 'xhtml11' backend.
- Don't paste AsciiDoc tables of contents, OpenOffice Writer (I was
  using version 2.3) hangs when saving. This may be something to do
  with the embedded JavaScript but I haven't looked closely at it, I
  may even be wrong about this.

This tip was contributed by Bernard Amade.


== How can I suppress cell separators in included table data files?

Use the `{include:}` system attribute instead of the `include::[]`
macro (the former is not expanded until after the table data has been
parsed into cells, whereas the latter is included before the table is
processed.


== How can I preserve paragraph line boundaries?

Apply the The 'verse' paragraph style, the rendered text preserves
line boundaries and is useful for lyrics and poems.  For example:

---------------------------------------------------------------------
[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------

Alternatively, if you are generating PDF files, you can use line
breaks. For example:

---------------------------------------------------------------------
Consul *necessitatibus* per id, +
consetetur, eu pro everti postulant +
homero verear ea mea, qui.
---------------------------------------------------------------------


== How can I include non-breaking space characters?

Use the non-breaking space character entity reference `&#160;` (see
the next question). You could also use the predefined `{nbsp}`
attribute reference.


== Can I include HTML and XML character entity references in my document?

Yes, just enter the reference in your document. For example `&#946;`
will print a Greek small beta character &#946;


[[X1]]
== How do I include spaces in URLs?

URL inline macro targets (addresses) cannot contain white space
characters. If you need spaces encode them as `%20`. For example:

  image:large%20image.png[]
  http://www.foo.bar.com/an%20example%20document.html


== How can I get AsciiDoc to assign the correct DocBook language attribute?

Set the AsciiDoc 'lang' attribute to the appropriate language code.
For example:

  $ a2x -a lang=es doc/article.txt

This will ensure that downstream DocBook processing will generate the
correct language specific document headings (things like table of
contents, revision history, figure and table captions, admonition
captions).


== How can I turn off table and image title numbering?
For HTML outputs set the 'caption' attribute to an empty string,
either globally:

-------------------------
:caption:
-------------------------

or on an element by element basis, for example:

-------------------------
.Tiger
[caption=""]
image::images/tiger.png[]
-------------------------


== How can I assign multiple author names?

A quick way to do this is put both authors in a single first name, for
example:

---------------------------------------
My Document
===========
:Author: Bill_and_Ben_the_Flowerpot_Men
:Author Initials: BB & BC
---------------------------------------

asciidoc(1) replaces the underscores with spaces.

If you are generating DocBook then a  more flexible approach is to
create a 'docinfo' file containing a DocBook 'authorgroup' element
(search the 'User Guide' for 'docinfo' for more details).


== How can I selectively disable a quoted text substitution?

Omitting the tag name will disable quoting. For example, if you don't
want superscripts or subscripts then put the following in a custom
configuration file or edit the global `asciidoc.conf` configuration
file:

-------------------
[quotes]
^=
~=
-------------------

Alternatively you can set the configuration entries from within your
document, the above examples are equivalent to:

-------------------
:quotes.^:
:quotes.~:
-------------------


== How can I customize the \{localdate} format?

The default format for the `{localdate}` attribute is the ISO 8601
`yyyy-mm-dd` format. You can change this format by explicitly setting
the `{localdate}` attribute. For example by setting it using the
asciidoc(1) `-a` command-line option:

  $ asciidoc -a localdate=`date +%d-%m-%Y` mydoc.txt

You could also set it by adding an Attribute Entry to your source
document, for example:

  :localdate: {sys: date +%Y-%m-%d}


== Why doesn't AsciiDoc support strike through text?

DocBook does not have provision for strike through text and one of the
AsciiDoc design goals is that AsciiDoc markup should strive to be
applicable to all output formats.

Strike through is normally used to mark deleted text -- a more
comprehensive way to manage document revisions is to use a version
control system such as Subversion. You can also use the AsciiDoc
'CommentLines' and 'CommentBlocks' to retain revised text in the
source document.

If you really need strike through text for (X)HTML outputs then adding
the following to a configuration file will allow you to quote strike
through text with hyphen characters:

---------------------------------------------------------------------
 ifdef::basebackend-html[]

 [quotes]
 -=strikethrough

 [tags]
 strikethrough=<del>|</del>

 endif::basebackend-html[]
---------------------------------------------------------------------


== Where can I find examples of commands used to build output documents?

The User Guide has some. You could also look at `./doc/main.aap` and
`./examples/website/main.aap` in the AsciiDoc distribution, they have
all the commands used to build the AsciiDoc documentation and the
AsciiDoc website (even if you don't use A-A-P you'll still find it
useful).


== Why have you used the DocBook <simpara> element instead of <para>?

`<simpara>` is really the same as `<para>` except it can't contain
block elements -- this matches, more closely, the AsciiDoc paragraph
semantics.


== How can I format text inside a listing block?

By default only 'specialcharacters' and 'callouts' are substituted in
listing blocks; you can add quotes substitutions by explicitly setting
the block 'subs' attribute, for example:

[listing]
..........................................
[subs="quotes"]
------------------------------------------
$ ls *-al*
------------------------------------------
..........................................

The `-al` will rendered bold. Note that:

- You would need to explicitly escape text you didn't want quoted.
- Don't do this in source code listing blocks because it modifies the
  source code which confuses the syntax highlighter.
- This only works if your DocBook processor recognizes DocBook
  `<emphasis>` elements inside `<screen>` elements.

Alternative, if the lines are contiguous, you could use the 'literal'
paragraph style:

------------------------------------------
["literal",subs="quotes"]
$ ls *-al*
------------------------------------------


== Why doesn't the include1::[] macro work?

Internally the `include1` macro is translated to the `include1` system
attribute which means it must be evaluated in a region where attribute
substitution is enabled. `include1` won't work, for example, in a
ListingBlock (unless attribute substitution is enabled).  `include1`
is intended for use in configuration files, use the `include` macro
and set the attribute `depth=1` instead, for example:

[listing]
................................................
------------------------------------------------
\include::blogpost_media_processing.txt[depth=1]
------------------------------------------------
................................................


== How can I make the mailto macro work with multiple email addresses?

For the AsciiDoc 'mailto' macro to work with multiple email addresses
(as per RFC2368) you need to URL encode the '@' characters (replace
them with '%40'), if you don't the individual addresses will be
rendered as separate links. You also need to <<X1,replace spaces with
'%20'>>.

For example, the following call won't work:

  mailto:jb@foobar.com,jd@acme.co.nz?subject=New foofoo release[New foofoo release]

Use this instead:

  mailto:jb%40foobar.com,jd%40acme.co.nz?subject=New%20foofoo%20release[New foofoo release]


== How can a replacement have a trailing backslash?
Quote the entry name -- this nonsensical example replaces `x\` with
`y`:

  "x\\"=y

If quoting were omitted the equals character (separating the
entry name `x` from the value `y`) would be escaped.