git-scribe 0.0.4 → 0.0.5

Sign up to get free protection for your applications and to get access to all the features.
Files changed (151) hide show
  1. data/.gitignore +1 -0
  2. data/Rakefile +31 -0
  3. data/SPEC.asciidoc +126 -0
  4. data/TODO.txt +29 -0
  5. data/bin/git-scribe +2 -1
  6. data/docbook-xsl/.CatalogManager.properties.example +61 -0
  7. data/docbook-xsl/.urilist +1 -0
  8. data/git-scribe.gemspec +32 -0
  9. data/lib/git-scribe.rb +21 -315
  10. data/lib/git-scribe/check.rb +60 -0
  11. data/lib/git-scribe/cli.rb +84 -0
  12. data/lib/git-scribe/generate.rb +222 -0
  13. data/lib/git-scribe/init.rb +16 -0
  14. data/lib/git-scribe/version.rb +3 -0
  15. data/template/.gitignore +1 -0
  16. data/template/.gitscribe +5 -0
  17. data/test/check_test.rb +12 -0
  18. data/test/gen_test.rb +78 -0
  19. data/test/init_test.rb +36 -0
  20. data/test/test_helper.rb +44 -0
  21. metadata +49 -161
  22. data/example/book/big.asc +0 -5604
  23. data/example/book/holmes.asc +0 -12983
  24. data/example/output/META-INF/container.xml +0 -6
  25. data/example/output/OEBPS/ar01s02.html +0 -15
  26. data/example/output/OEBPS/ar01s03.html +0 -3
  27. data/example/output/OEBPS/content.opf +0 -21
  28. data/example/output/OEBPS/index.html +0 -5
  29. data/example/output/OEBPS/toc.ncx +0 -37
  30. data/example/output/a_case_of_identity.html +0 -725
  31. data/example/output/a_example_appendix.html +0 -63
  32. data/example/output/a_migration_notes.html +0 -95
  33. data/example/output/apa.html +0 -20
  34. data/example/output/apb.html +0 -6
  35. data/example/output/apc.html +0 -24
  36. data/example/output/apd.html +0 -30
  37. data/example/output/ape.html +0 -26
  38. data/example/output/apf.html +0 -9
  39. data/example/output/apg.html +0 -42
  40. data/example/output/aph.html +0 -89
  41. data/example/output/ar01s02.html +0 -12
  42. data/example/output/ar01s03.html +0 -34
  43. data/example/output/ar01s04.html +0 -77
  44. data/example/output/ar01s05.html +0 -272
  45. data/example/output/ar01s06.html +0 -35
  46. data/example/output/ar01s07.html +0 -105
  47. data/example/output/ar01s08.html +0 -33
  48. data/example/output/ar01s09.html +0 -12
  49. data/example/output/ar01s10.html +0 -14
  50. data/example/output/ar01s11.html +0 -34
  51. data/example/output/ar01s12.html +0 -63
  52. data/example/output/ar01s13.html +0 -156
  53. data/example/output/ar01s14.html +0 -330
  54. data/example/output/ar01s15.html +0 -22
  55. data/example/output/ar01s16.html +0 -27
  56. data/example/output/ar01s17.html +0 -94
  57. data/example/output/ar01s18.html +0 -359
  58. data/example/output/ar01s19.html +0 -373
  59. data/example/output/ar01s20.html +0 -27
  60. data/example/output/ar01s21.html +0 -33
  61. data/example/output/ar01s22.html +0 -351
  62. data/example/output/ar01s23.html +0 -21
  63. data/example/output/ar01s24.html +0 -69
  64. data/example/output/ar01s25.html +0 -60
  65. data/example/output/ar01s26.html +0 -217
  66. data/example/output/ar01s27.html +0 -88
  67. data/example/output/ar01s28.html +0 -237
  68. data/example/output/ar01s29.html +0 -68
  69. data/example/output/ar01s30.html +0 -154
  70. data/example/output/ar01s31.html +0 -6
  71. data/example/output/ar01s32.html +0 -22
  72. data/example/output/ar01s33.html +0 -209
  73. data/example/output/asciidoc_backends.html +0 -190
  74. data/example/output/asciidoc_document_types.html +0 -131
  75. data/example/output/attribute_entries.html +0 -185
  76. data/example/output/attribute_lists.html +0 -157
  77. data/example/output/attribute_references.html +0 -414
  78. data/example/output/attributelist_element.html +0 -143
  79. data/example/output/b_packager_notes.html +0 -68
  80. data/example/output/bi01.html +0 -18
  81. data/example/output/big.asc +0 -5604
  82. data/example/output/block_element_definitions.html +0 -448
  83. data/example/output/block_titles.html +0 -83
  84. data/example/output/blockid_element.html +0 -80
  85. data/example/output/book.asc +0 -5604
  86. data/example/output/book.epub +0 -0
  87. data/example/output/book.fo +0 -3788
  88. data/example/output/book.html +0 -8793
  89. data/example/output/book.xml +0 -8265
  90. data/example/output/c_asciidoc_safe_mode.html +0 -105
  91. data/example/output/callouts.html +0 -214
  92. data/example/output/catalog +0 -10
  93. data/example/output/colophon.html +0 -397
  94. data/example/output/configuration_files.html +0 -672
  95. data/example/output/converting_docbook_to_other_file_formats.html +0 -324
  96. data/example/output/d_using_asciidoc_with_non-english_languages.html +0 -107
  97. data/example/output/delimited_blocks.html +0 -455
  98. data/example/output/document_attributes.html +0 -95
  99. data/example/output/document_processing.html +0 -116
  100. data/example/output/document_structure.html +0 -493
  101. data/example/output/e_vim_syntax_highlighter.html +0 -111
  102. data/example/output/example_bibliography.html +0 -82
  103. data/example/output/example_colophon.html +0 -58
  104. data/example/output/example_glossary.html +0 -73
  105. data/example/output/example_index.html +0 -108
  106. data/example/output/f_attribute_options.html +0 -129
  107. data/example/output/filters.html +0 -179
  108. data/example/output/footnotes.html +0 -103
  109. data/example/output/g_diagnostics.html +0 -148
  110. data/example/output/generating_plain_text_files.html +0 -68
  111. data/example/output/getting_started.html +0 -87
  112. data/example/output/glossary.html +0 -95
  113. data/example/output/go01.html +0 -24
  114. data/example/output/h_backend_attributes.html +0 -308
  115. data/example/output/help_commands.html +0 -96
  116. data/example/output/holmes.asc +0 -12983
  117. data/example/output/image/octocat_professor.png +0 -0
  118. data/example/output/include/hello.c +0 -10
  119. data/example/output/index.html +0 -656
  120. data/example/output/indexes.html +0 -104
  121. data/example/output/intrinsic_attributes.html +0 -165
  122. data/example/output/ix01.html +0 -3
  123. data/example/output/lists.html +0 -666
  124. data/example/output/macros.html +0 -737
  125. data/example/output/manpage_documents.html +0 -124
  126. data/example/output/master.css +0 -281
  127. data/example/output/mathematical_formulas.html +0 -125
  128. data/example/output/page.html +0 -60
  129. data/example/output/paragraphs.html +0 -192
  130. data/example/output/pr01.html +0 -3
  131. data/example/output/source_code_highlighting.html +0 -59
  132. data/example/output/stylesheets/handbookish-quirks.css +0 -0
  133. data/example/output/stylesheets/handbookish.css +0 -233
  134. data/example/output/tables.html +0 -797
  135. data/example/output/text_formatting.html +0 -273
  136. data/example/output/the_adventure_of_the_beryl_coronet.html +0 -968
  137. data/example/output/the_adventure_of_the_blue_carbuncle.html +0 -825
  138. data/example/output/the_adventure_of_the_copper_beeches.html +0 -998
  139. data/example/output/the_adventure_of_the_engineer_s_thumb.html +0 -851
  140. data/example/output/the_adventure_of_the_noble_bachelor.html +0 -861
  141. data/example/output/the_adventure_of_the_speckled_band.html +0 -1015
  142. data/example/output/the_boscombe_valley_mystery.html +0 -974
  143. data/example/output/the_first_chapter.html +0 -110
  144. data/example/output/the_five_orange_pips.html +0 -776
  145. data/example/output/the_man_with_the_twisted_lip.html +0 -946
  146. data/example/output/the_red-headed_league.html +0 -950
  147. data/example/output/the_second_chapter.html +0 -95
  148. data/example/output/the_third_chapter.html +0 -58
  149. data/example/output/tips_and_tricks.html +0 -452
  150. data/example/output/title.html +0 -120
  151. data/example/output/titles.html +0 -126
data/example/output/ar01s19.html DELETED
@@ -1,373 +0,0 @@
1
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Tables</title><link rel="stylesheet" href="stylesheets/handbookish.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.74.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ar01s18.html" title="Macros" /><link rel="next" href="ar01s20.html" title="Manpage Documents" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Tables</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s18.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s20.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_tables"></a>Tables</h2></div></div></div><p>The AsciiDoc table syntax looks and behaves like other delimited block
4
- types and supports standard <a class="link" href="ar01s28.html" title="Block Element Definitions">block configuration entries</a>.
5
- Formatting is easy to read and, just as importantly, easy to enter.</p><div class="itemizedlist"><ul type="disc"><li>
6
- Cells and columns can be formatted using built-in customizable styles.
7
- </li><li>
8
- Horizontal and vertical cell alignment can be set on columns and
9
- cell.
10
- </li><li>
11
- Horizontal and vertical cell spanning is supported.
12
- </li></ul></div><div class="sidebar"><p class="title"><b>Use tables sparingly</b></p><p>When technical users first start creating documents, tables (complete
13
- with column spanning and table nesting) are often considered very
14
- important. The reality is that tables are seldom used, even in
15
- technical documentation.</p><p>Try this exercise: thumb through your library of technical books,
16
- you’ll be surprised just how seldom tables are actually used, even
17
- less seldom are tables containing block elements (such as paragraphs
18
- or lists) or spanned cells. This is no accident, like figures, tables
19
- are outside the normal document flow — tables are for consulting not
20
- for reading.</p><p>Tables are designed for, and should normally only be used for,
21
- displaying column oriented tabular data.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_example_tables"></a>Example tables</h3></div></div></div><div class="table"><a id="id36121822"></a><p class="title"><b>Table 2. Simple table</b></p><div class="table-contents"><table summary="Simple table" border="1" width="15%"><colgroup><col /><col /><col /></colgroup><tbody><tr><td align="left" valign="top"><p>1</p></td><td align="left" valign="top"><p>2</p></td><td align="left" valign="top"><p>A</p></td></tr><tr><td align="left" valign="top"><p>3</p></td><td align="left" valign="top"><p>4</p></td><td align="left" valign="top"><p>B</p></td></tr><tr><td align="left" valign="top"><p>5</p></td><td align="left" valign="top"><p>6</p></td><td align="left" valign="top"><p>C</p></td></tr></tbody></table></div></div><br class="table-break" /><p><b>AsciiDoc source. </b>
22
- </p><pre class="screen">[width="15%"]
23
- |=======
24
- |1 |2 |A
25
- |3 |4 |B
26
- |5 |6 |C
27
- |=======</pre><p>
28
- </p><div class="table"><a id="id36121959"></a><p class="title"><b>Table 3. Columns formatted with strong, monospaced and emphasis styles</b></p><div class="table-contents"><table summary="Columns formatted with strong, monospaced and emphasis styles" border="1" width="50%"><colgroup><col /><col /><col /></colgroup><thead><tr><th align="right" valign="top"> </th><th colspan="2" align="center" valign="top">Columns 2 and 3</th></tr></thead><tfoot><tr><th align="right" valign="top"><p><span class="strong"><strong>footer 1</strong></span></p></th><th align="center" valign="top"><p><code class="literal">footer 2</code></p></th><th align="left" valign="top"><p><span class="emphasis"><em>footer 3</em></span></p></th></tr></tfoot><tbody><tr><td align="right" valign="top"><p><span class="strong"><strong>1</strong></span></p></td><td align="center" valign="top"><p><code class="literal">Item 1</code></p></td><td align="left" valign="top"><p><span class="emphasis"><em>Item 1</em></span></p></td></tr><tr><td align="right" valign="top"><p><span class="strong"><strong>2</strong></span></p></td><td align="center" valign="top"><p><code class="literal">Item 2</code></p></td><td align="left" valign="top"><p><span class="emphasis"><em>Item 2</em></span></p></td></tr><tr><td align="right" valign="top"><p><span class="strong"><strong>3</strong></span></p></td><td align="center" valign="top"><p><code class="literal">Item 3</code></p></td><td align="left" valign="top"><p><span class="emphasis"><em>Item 3</em></span></p></td></tr><tr><td align="right" valign="top"><p><span class="strong"><strong>4</strong></span></p></td><td align="center" valign="top"><p><code class="literal">Item 4</code></p></td><td align="left" valign="top"><p><span class="emphasis"><em>Item 4</em></span></p></td></tr></tbody></table></div></div><br class="table-break" /><p><b>AsciiDoc source. </b>
29
- </p><pre class="screen">.An example table
30
- [width="50%",cols="&gt;s,^m,e",frame="topbot",options="header,footer"]
31
- |==========================
32
- | 2+|Columns 2 and 3
33
- |1 |Item 1 |Item 1
34
- |2 |Item 2 |Item 2
35
- |3 |Item 3 |Item 3
36
- |4 |Item 4 |Item 4
37
- |footer 1|footer 2|footer 3
38
- |==========================</pre><p>
39
- </p><div class="table"><a id="id36122216"></a><p class="title"><b>Table 4. Horizontal and vertical source data</b></p><div class="table-contents"><table summary="Horizontal and vertical source data" border="1" width="80%"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th align="left" valign="top">Date </th><th align="center" valign="top">Duration </th><th align="center" valign="top">Avg HR </th><th align="left" valign="top">Notes</th></tr></thead><tbody><tr><td align="left" valign="top"><p>22-Aug-08</p></td><td align="center" valign="top"><p>10:24</p></td><td align="center" valign="top"><p>157</p></td><td align="left" valign="top"><p>Worked out MSHR (max sustainable heart rate) by going hard
40
- for this interval.</p></td></tr><tr><td align="left" valign="top"><p>22-Aug-08</p></td><td align="center" valign="top"><p>23:03</p></td><td align="center" valign="top"><p>152</p></td><td align="left" valign="top"><p>Back-to-back with previous interval.</p></td></tr><tr><td align="left" valign="top"><p>24-Aug-08</p></td><td align="center" valign="top"><p>40:00</p></td><td align="center" valign="top"><p>145</p></td><td align="left" valign="top"><p>Moderately hard interspersed with 3x 3min intervals (2min
41
- hard + 1min really hard taking the HR up to 160).</p></td></tr></tbody></table></div></div><br class="table-break" /><p>Short cells can be entered horizontally, longer cells vertically. The
42
- default behavior is to strip leading and trailing blank lines within a
43
- cell. These characteristics aid readability and data entry.</p><p><b>AsciiDoc source. </b>
44
- </p><pre class="screen">.Windtrainer workouts
45
- [width="80%",cols="3,^2,^2,10",options="header"]
46
- |=========================================================
47
- |Date |Duration |Avg HR |Notes
48
-
49
- |22-Aug-08 |10:24 | 157 |
50
- Worked out MSHR (max sustainable heart rate) by going hard
51
- for this interval.
52
-
53
- |22-Aug-08 |23:03 | 152 |
54
- Back-to-back with previous interval.
55
-
56
- |24-Aug-08 |40:00 | 145 |
57
- Moderately hard interspersed with 3x 3min intervals (2min
58
- hard + 1min really hard taking the HR up to 160).
59
-
60
- |=========================================================</pre><p>
61
- </p><div class="table"><a id="id36122426"></a><p class="title"><b>Table 5. A table with externally sourced CSV data</b></p><div class="table-contents"><table summary="A table with externally sourced CSV data" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th align="center" valign="top">ID</th><th align="left" valign="top">Customer Name</th><th align="left" valign="top">Contact Name</th><th align="left" valign="top">Customer Address</th><th align="left" valign="top">Phone</th></tr></thead><tbody></tbody></table></div></div><br class="table-break" /><p><b>AsciiDoc source. </b>
62
- </p><pre class="screen">[format="csv",cols="^1,4*2",options="header"]
63
- |===================================================
64
- ID,Customer Name,Contact Name,Customer Address,Phone
65
- include::customers.csv[]
66
- |===================================================</pre><p>
67
- </p><div class="table"><a id="id36122532"></a><p class="title"><b>Table 6. Cell spans, alignments and styles</b></p><div class="table-contents"><table summary="Cell spans, alignments and styles" border="1" width="25%"><colgroup><col /><col /><col /><col /></colgroup><tbody><tr><td align="left" valign="top"><p><span class="emphasis"><em>1</em></span></p></td><td align="right" valign="top"><p><span class="strong"><strong>2</strong></span></p></td><td align="center" valign="top"><p>3</p></td><td align="right" valign="top"><p><span class="strong"><strong>4</strong></span></p></td></tr><tr><td align="center" valign="top"><p><span class="emphasis"><em>5</em></span></p></td><td rowspan="2" colspan="2" align="center" valign="middle"><p><code class="literal">6</code></p></td><td rowspan="3" align="left" valign="bottom"><p><code class="literal">7</code></p></td></tr><tr><td align="center" valign="top"><p><span class="emphasis"><em>8</em></span></p></td></tr><tr><td align="left" valign="top"><p><span class="emphasis"><em>9</em></span></p></td><td colspan="2" align="right" valign="top"><p><code class="literal">10</code></p></td></tr></tbody></table></div></div><br class="table-break" /><p><b>AsciiDoc source. </b>
68
- </p><pre class="screen">[cols="e,m,^,&gt;s",width="25%"]
69
- |============================
70
- |1 &gt;s|2 |3 |4
71
- ^|5 2.2+^.^|6 .3+&lt;.&gt;m|7
72
- ^|8
73
- |9 2+&gt;|10
74
- |============================</pre><p>
75
- </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X68"></a>Table input data formats</h3></div></div></div><p>AsciiDoc table data can be <span class="emphasis"><em>psv</em></span>, <span class="emphasis"><em>dsv</em></span> or <span class="emphasis"><em>csv</em></span> formatted. The
76
- default table format is <span class="emphasis"><em>psv</em></span>.</p><p>AsciiDoc <span class="emphasis"><em>psv</em></span> (<span class="emphasis"><em>Prefix Separated Values</em></span>) and <span class="emphasis"><em>dsv</em></span> (<span class="emphasis"><em>Delimiter
77
- Separated Values</em></span>) formats are cell oriented — the table is treated
78
- as a sequence of cells — there are no explicit row separators.</p><div class="itemizedlist"><ul type="disc"><li>
79
- <span class="emphasis"><em>psv</em></span> prefixes each cell with a separator whereas <span class="emphasis"><em>dsv</em></span> delimits
80
- cells with a separator.
81
- </li><li>
82
- <span class="emphasis"><em>psv</em></span> and <span class="emphasis"><em>dsv</em></span> separators are Python regular expressions.
83
- </li><li>
84
- The default <span class="emphasis"><em>psv</em></span> separator contains <a class="link" href="ar01s19.html#X84" title="Cell Specifiers">cell specifier</a> related
85
- named regular expression groups.
86
- </li><li>
87
- The default <span class="emphasis"><em>dsv</em></span> separator is <code class="literal">:|\n</code> (a colon or a new line
88
- character).
89
- </li><li>
90
- <span class="emphasis"><em>psv</em></span> and <span class="emphasis"><em>dsv</em></span> cell separators can be escaped by preceding them
91
- with a backslash character.
92
- </li></ul></div><p>Here are four <span class="emphasis"><em>psv</em></span> cells (the second item spans two columns; the
93
- last contains an escaped separator):</p><pre class="literallayout">|One 2+|Two and three |A \| separator character</pre><p><span class="emphasis"><em>csv</em></span> is the quasi-standard row oriented <span class="emphasis"><em>Comma Separated Values
94
- (CSV)</em></span> format commonly used to import and export spreadsheet and
95
- database data.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X69"></a>Table attributes</h3></div></div></div><p>Tables can be customized by the following attributes:</p><div class="variablelist"><dl><dt><span class="term">
96
- format
97
- </span></dt><dd>
98
- <span class="emphasis"><em>psv</em></span> (default), <span class="emphasis"><em>dsv</em></span> or <span class="emphasis"><em>csv</em></span> (See <a class="link" href="ar01s19.html#X68" title="Table input data formats">Table Data Formats</a>).
99
- </dd><dt><span class="term">
100
- separator
101
- </span></dt><dd>
102
- The cell separator. A Python regular expression (<span class="emphasis"><em>psv</em></span> and <span class="emphasis"><em>dsv</em></span>
103
- formats) or a single character (<span class="emphasis"><em>csv</em></span> format).
104
- </dd><dt><span class="term">
105
- frame
106
- </span></dt><dd>
107
- Defines the table border and can take the following values: <span class="emphasis"><em>topbot</em></span>
108
- (top and bottom), <span class="emphasis"><em>all</em></span> (all sides), <span class="emphasis"><em>none</em></span> and <span class="emphasis"><em>sides</em></span> (left and
109
- right sides). The default value is <span class="emphasis"><em>all</em></span>.
110
- </dd><dt><span class="term">
111
- grid
112
- </span></dt><dd>
113
- Defines which ruler lines are drawn between table rows and columns.
114
- The <span class="emphasis"><em>grid</em></span> attribute value can be any of the following values: <span class="emphasis"><em>none</em></span>,
115
- <span class="emphasis"><em>cols</em></span>, <span class="emphasis"><em>rows</em></span> and <span class="emphasis"><em>all</em></span>. The default value is <span class="emphasis"><em>all</em></span>.
116
- </dd><dt><span class="term">
117
- align
118
- </span></dt><dd>
119
- Use the <span class="emphasis"><em>align</em></span> attribute to horizontally align the table on the
120
- page (works with HTML outputs only, has no effect on DocBook outputs).
121
- The following values are valid: <span class="emphasis"><em>left</em></span>, <span class="emphasis"><em>right</em></span>, and <span class="emphasis"><em>center</em></span>.
122
- </dd><dt><span class="term">
123
- float
124
- </span></dt><dd>
125
- Use the <span class="emphasis"><em>float</em></span> attribute to float the table <span class="emphasis"><em>left</em></span> or <span class="emphasis"><em>right</em></span> on the
126
- page (works with HTML outputs only, has no effect on DocBook outputs).
127
- Floating only makes sense in conjunction with a table <span class="emphasis"><em>width</em></span>
128
- attribute value of less than 100% (otherwise the table will take up
129
- all the available space). <span class="emphasis"><em>float</em></span> and <span class="emphasis"><em>align</em></span> attributes are mutually
130
- exclusive. Use the <code class="literal">unfloat::[]</code> block macro to stop floating.
131
- </dd><dt><span class="term">
132
- halign
133
- </span></dt><dd>
134
- Use the <span class="emphasis"><em>halign</em></span> attribute to horizontally align all cells in a table.
135
- The following values are valid: <span class="emphasis"><em>left</em></span>, <span class="emphasis"><em>right</em></span>, and <span class="emphasis"><em>center</em></span>
136
- (defaults to <span class="emphasis"><em>left</em></span>). Overridden by <a class="link" href="ar01s19.html#X70" title="Column Specifiers">Column specifiers</a> and
137
- <a class="link" href="ar01s19.html#X84" title="Cell Specifiers">Cell specifiers</a>.
138
- </dd><dt><span class="term">
139
- valign
140
- </span></dt><dd>
141
- Use the <span class="emphasis"><em>valign</em></span> attribute to vertically align all cells in a table.
142
- The following values are valid: <span class="emphasis"><em>top</em></span>, <span class="emphasis"><em>bottom</em></span>, and <span class="emphasis"><em>middle</em></span>
143
- (defaults to <span class="emphasis"><em>top</em></span>). Overridden by <a class="link" href="ar01s19.html#X70" title="Column Specifiers">Column specifiers</a> and
144
- <a class="link" href="ar01s19.html#X84" title="Cell Specifiers">Cell specifiers</a>.
145
- </dd><dt><span class="term">
146
- options
147
- </span></dt><dd>
148
- The <span class="emphasis"><em>options</em></span> attribute can contain comma separated values, for
149
- example: <span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>footer</em></span>. By default header and footer rows are
150
- omitted. See <a class="link" href="apf.html" title="F. Attribute Options">attribute options</a> for a complete list of
151
- available table options.
152
- </dd><dt><span class="term">
153
- cols
154
- </span></dt><dd><p>
155
- The <span class="emphasis"><em>cols</em></span> attribute is a comma separated list of <a class="link" href="ar01s19.html#X70" title="Column Specifiers">column specifiers</a>. For example <code class="literal">cols="2&lt;p,2*,4p,&gt;"</code>.
156
- </p><div class="itemizedlist"><ul type="disc"><li>
157
- If <span class="emphasis"><em>cols</em></span> is present it must specify all columns.
158
- </li><li>
159
- If the <span class="emphasis"><em>cols</em></span> attribute is not specified the number of columns is
160
- calculated as the number of data items in the <span class="strong"><strong>first line</strong></span> of the
161
- table.
162
- </li><li>
163
- The degenerate form for the <span class="emphasis"><em>cols</em></span> attribute is an integer
164
- specifying the number of columns e.g. <code class="literal">cols=4</code>.
165
- </li></ul></div></dd><dt><span class="term">
166
- width
167
- </span></dt><dd>
168
- The <span class="emphasis"><em>width</em></span> attribute is expressed as a percentage value
169
- (<span class="emphasis"><em>"1%"</em></span>…<span class="emphasis"><em>"99%"</em></span>). The width specifies the table width relative to
170
- the available width. HTML backends use this value to set the table
171
- width attribute. It’s a bit more complicated with DocBook, see the
172
- <a class="link" href="ar01s19.html#X89" title="DocBook table widths">DocBook table widths</a> sidebar.
173
- </dd><dt><span class="term">
174
- filter
175
- </span></dt><dd>
176
- The <span class="emphasis"><em>filter</em></span> attribute defines an external shell command that is
177
- invoked for each cell. The built-in <span class="emphasis"><em>asciidoc</em></span> table style is
178
- implemented using a filter.
179
- </dd></dl></div><div class="sidebar"><a id="X89"></a><p class="title"><b>DocBook table widths</b></p><p>The AsciiDoc docbook backend generates CALS tables. CALS tables do not
180
- support a table width attribute — table width can only be controlled
181
- by specifying absolute column widths.</p><p>Specifying absolute column widths is not media independent because
182
- different presentation media have different physical dimensions. To
183
- get round this limitation both
184
- <a class="ulink" href="http://www.sagehill.net/docbookxsl/Tables.html#TableWidth" target="_top">DocBook XSL
185
- Stylesheets</a> and
186
- <a class="ulink" href="http://dblatex.sourceforge.net/doc/manual/ch03s05.html#sec-table-width" target="_top">dblatex</a>
187
- have implemented table width processing instructions for setting the
188
- table width as a percentage of the available width. AsciiDoc emits
189
- these processing instructions if the <span class="emphasis"><em>width</em></span> attribute is set along
190
- with proportional column widths (the AsciiDoc docbook backend
191
- <span class="emphasis"><em>pageunits</em></span> attribute defaults to <span class="emphasis"><em>*</em></span>).</p><p>To generate DocBook tables with absolute column widths set the
192
- <span class="emphasis"><em>pageunits</em></span> attribute to a CALS absolute unit such as <span class="emphasis"><em>pt</em></span> and set the
193
- <span class="emphasis"><em>pagewidth</em></span> attribute to match the width of the presentation media.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X70"></a>Column Specifiers</h3></div></div></div><p>Column specifiers define how columns are rendered and appear in the
194
- table <a class="link" href="ar01s19.html#X69" title="Table attributes">cols attribute</a>. A column specifier consists of an
195
- optional column multiplier followed by optional alignment, width and
196
- style values and is formatted like:</p><pre class="literallayout">[&lt;multiplier&gt;*][&lt;align&gt;][&lt;width&gt;][&lt;style&gt;]</pre><div class="itemizedlist"><ul type="disc"><li>
197
- All components are optional. The multiplier must be first and the
198
- style last. The order of <code class="literal">&lt;align&gt;</code> or <code class="literal">&lt;width&gt;</code> is not important.
199
- </li><li>
200
- Column <code class="literal">&lt;width&gt;</code> can be either an integer proportional value (1…)
201
- or a percentage (1%…100%). The default value is 1. To ensure
202
- portability across different backends, there is no provision for
203
- absolute column widths (not to be confused with output column width
204
- <a class="link" href="ar01s19.html#X72" title="Markup attributes">markup attributes</a> which are available in both percentage and
205
- absolute units).
206
- </li><li><p>
207
- The <span class="emphasis"><em>&lt;align&gt;</em></span> column alignment specifier is formatted like:
208
- </p><pre class="literallayout">[&lt;horizontal&gt;][.&lt;vertical&gt;]</pre><p>Where <code class="literal">&lt;horizontal&gt;</code> and <code class="literal">&lt;vertical&gt;</code> are one of the following
209
- characters: <code class="literal">&lt;</code>, <code class="literal">^</code> or <code class="literal">&gt;</code> which represent <span class="emphasis"><em>left</em></span>, <span class="emphasis"><em>center</em></span> and
210
- <span class="emphasis"><em>right</em></span> horizontal alignment or <span class="emphasis"><em>top</em></span>, <span class="emphasis"><em>middle</em></span> and <span class="emphasis"><em>bottom</em></span> vertical
211
- alignment respectively.</p></li><li>
212
- A <code class="literal">&lt;multiplier&gt;</code> can be used to specify repeated columns e.g.
213
- <code class="literal">cols="4*&lt;"</code> specifies four left-justified columns. The default
214
- multiplier value is 1.
215
- </li><li>
216
- The <code class="literal">&lt;style&gt;</code> name specifies a <a class="link" href="ar01s19.html#X71" title="Table styles">table style</a> to used to markup
217
- column cells (you can use the full style names if you wish but the
218
- first letter is normally sufficient).
219
- </li><li>
220
- Column specific styles are not applied to header rows.
221
- </li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X84"></a>Cell Specifiers</h3></div></div></div><p>Cell specifiers allow individual cells in <span class="emphasis"><em>psv</em></span> formatted tables to be
222
- spanned, multiplied, aligned and styled. Cell specifiers prefix <span class="emphasis"><em>psv</em></span>
223
- <code class="literal">|</code> delimiters and are formatted like:</p><pre class="literallayout">[&lt;span&gt;*|+][&lt;align&gt;][&lt;style&gt;]</pre><div class="itemizedlist"><ul type="disc"><li><p>
224
- <span class="emphasis"><em>&lt;span&gt;</em></span> specifies horizontal and vertical cell spans (<span class="emphasis"><em>+</em></span> operator) or
225
- the number of times the cell is replicated (<span class="emphasis"><em>*</em></span> operator). <span class="emphasis"><em>&lt;span&gt;</em></span>
226
- is formatted like:
227
- </p><pre class="literallayout">[&lt;colspan&gt;][.&lt;rowspan&gt;]</pre><p>Where <code class="literal">&lt;colspan&gt;</code> and <code class="literal">&lt;rowspan&gt;</code> are integers specifying the number of
228
- columns and rows to span.</p></li><li>
229
- <code class="literal">&lt;align&gt;</code> specifies horizontal and vertical cell alignment an is the
230
- same as in <a class="link" href="ar01s19.html#X70" title="Column Specifiers">column specifiers</a>.
231
- </li><li>
232
- A <code class="literal">&lt;style&gt;</code> value is the first letter of <a class="link" href="ar01s19.html#X71" title="Table styles">table style</a> name.
233
- </li></ul></div><p>For example, the following <span class="emphasis"><em>psv</em></span> formatted cell will span two columns
234
- and the text will be centered and emphasized:</p><pre class="literallayout">`2+^e| Cell text`</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X71"></a>Table styles</h3></div></div></div><p>Table styles can be applied to the entire table (by setting the
235
- <span class="emphasis"><em>style</em></span> attribute in the table’s attribute list) or on a per column
236
- basis (by specifying the style in the table’s <a class="link" href="ar01s19.html#X69" title="Table attributes">cols attribute</a>).
237
- Table data can be formatted using the following predefined styles:</p><div class="variablelist"><dl><dt><span class="term">
238
- default
239
- </span></dt><dd>
240
- The default style: AsciiDoc inline text formatting; blank lines are
241
- treated as paragraph breaks.
242
- </dd><dt><span class="term">
243
- emphasis
244
- </span></dt><dd>
245
- Like default but all text is emphasised.
246
- </dd><dt><span class="term">
247
- monospaced
248
- </span></dt><dd>
249
- Like default but all text is in a monospaced font.
250
- </dd><dt><span class="term">
251
- strong
252
- </span></dt><dd>
253
- Like default but all text is bold.
254
- </dd><dt><span class="term">
255
- header
256
- </span></dt><dd>
257
- Apply the same style as the table header. Normally used to create a
258
- vertical header in the first column.
259
- </dd><dt><span class="term">
260
- asciidoc
261
- </span></dt><dd>
262
- With this style table cells can contain any of the AsciiDoc elements
263
- that are allowed inside document sections. This style runs asciidoc(1)
264
- as a filter to process cell contents. See also <a class="link" href="ar01s19.html#X83" title="DocBook table limitations">Docbook table limitations</a>.
265
- </dd><dt><span class="term">
266
- literal
267
- </span></dt><dd>
268
- No text formatting; monospaced font; all line breaks are retained
269
- (the same as the AsciiDoc <a class="link" href="ar01s13.html#X65" title="Literal Blocks">LiteralBlock</a> element).
270
- </dd><dt><span class="term">
271
- verse
272
- </span></dt><dd>
273
- All line breaks are retained (just like the AsciiDoc <a class="link" href="ar01s12.html#X94" title="quote and verse paragraph styles">verse paragraph style</a>).
274
- </dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X72"></a>Markup attributes</h3></div></div></div><p>AsciiDoc makes a number of attributes available to table markup
275
- templates and tags. Column specific attributes are available when
276
- substituting the <span class="emphasis"><em>colspec</em></span> cell data tags.</p><div class="variablelist"><dl><dt><span class="term">
277
- pageunits
278
- </span></dt><dd>
279
- DocBook backend only. Specifies table column absolute width units.
280
- Defaults to <span class="emphasis"><em>*</em></span>.
281
- </dd><dt><span class="term">
282
- pagewidth
283
- </span></dt><dd>
284
- DocBook backend only. The nominal output page width in <span class="emphasis"><em>pageunit</em></span>
285
- units. Used to calculate CALS tables absolute column and table
286
- widths. Defaults to <span class="emphasis"><em>425</em></span>.
287
- </dd><dt><span class="term">
288
- tableabswidth
289
- </span></dt><dd>
290
- Integer value calculated from <span class="emphasis"><em>width</em></span> and <span class="emphasis"><em>pagewidth</em></span> attributes.
291
- In <span class="emphasis"><em>pageunit</em></span> units.
292
- </dd><dt><span class="term">
293
- tablepcwidth
294
- </span></dt><dd>
295
- Table width expressed as a percentage of the available width. Integer
296
- value (0..100).
297
- </dd><dt><span class="term">
298
- colabswidth
299
- </span></dt><dd>
300
- Integer value calculated from <span class="emphasis"><em>cols</em></span> column width, <span class="emphasis"><em>width</em></span> and
301
- <span class="emphasis"><em>pagewidth</em></span> attributes. In <span class="emphasis"><em>pageunit</em></span> units.
302
- </dd><dt><span class="term">
303
- colpcwidth
304
- </span></dt><dd>
305
- Column width expressed as a percentage of the table width. Integer
306
- value (0..100).
307
- </dd><dt><span class="term">
308
- colcount
309
- </span></dt><dd>
310
- Total number of table columns.
311
- </dd><dt><span class="term">
312
- rowcount
313
- </span></dt><dd>
314
- Total number of table rows.
315
- </dd><dt><span class="term">
316
- halign
317
- </span></dt><dd>
318
- Horizontal cell content alignment: <span class="emphasis"><em>left</em></span>, <span class="emphasis"><em>right</em></span> or <span class="emphasis"><em>center</em></span>.
319
- </dd><dt><span class="term">
320
- valign
321
- </span></dt><dd>
322
- Vertical cell content alignment: <span class="emphasis"><em>top</em></span>, <span class="emphasis"><em>bottom</em></span> or <span class="emphasis"><em>middle</em></span>.
323
- </dd><dt><span class="term">
324
- colnumber, colstart
325
- </span></dt><dd>
326
- The number of the leftmost column occupied by the cell (1…).
327
- </dd><dt><span class="term">
328
- colend
329
- </span></dt><dd>
330
- The number of the rightmost column occupied by the cell (1…).
331
- </dd><dt><span class="term">
332
- colspan
333
- </span></dt><dd>
334
- Number of columns the cell should span.
335
- </dd><dt><span class="term">
336
- rowspan
337
- </span></dt><dd>
338
- Number of rows the cell should span (1…).
339
- </dd><dt><span class="term">
340
- morerows
341
- </span></dt><dd>
342
- Number of additional rows the cell should span (0…).
343
- </dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_nested_tables"></a>Nested tables</h3></div></div></div><p>An alternative <span class="emphasis"><em>psv</em></span> separator character <span class="emphasis"><em>!</em></span> can be used (instead of
344
- <span class="emphasis"><em>|</em></span>) in nested tables. This allows a single level of table nesting.
345
- Columns containing nested tables must use the <span class="emphasis"><em>asciidoc</em></span> style. An
346
- example can be found in <code class="literal">./examples/website/newtables.txt</code>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X83"></a>DocBook table limitations</h3></div></div></div><p>Fully implementing tables is not trivial, some DocBook toolchains do
347
- better than others. AsciiDoc HTML table outputs are rendered
348
- correctly in all the popular browsers — if your DocBook generated
349
- tables don’t look right compare them with the output generated by the
350
- AsciiDoc <span class="emphasis"><em>xhtml11</em></span> backend or try a different DocBook toolchain. Here
351
- is a list of things to be aware of:</p><div class="itemizedlist"><ul type="disc"><li><p>
352
- Although nested tables are not legal in DocBook 4 the FOP and
353
- dblatex toolchains will process them correctly. If you use <code class="literal">a2x(1)</code>
354
- you will need to include the <code class="literal">--no-xmllint</code> option to suppress
355
- DocBook validation errors.
356
- </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Technically you can nest DocBook 4 tables one level using the
357
- <span class="emphasis"><em>entrytbl</em></span> element, but not all toolchains process <span class="emphasis"><em>entrytbl</em></span>.</p></div></li><li>
358
- DocBook only allows a subset of block elements inside table cells so
359
- not all AsciiDoc elements produce valid DocBook inside table cells.
360
- If you get validation errors running <code class="literal">a2x(1)</code> try the <code class="literal">--no-xmllint</code>
361
- option, toolchains will often process nested block elements such as
362
- sidebar blocks and floating titles correctly even though, strictly
363
- speaking, they are not legal.
364
- </li><li>
365
- Text formatting in cells using the <span class="emphasis"><em>monospaced</em></span> table style will
366
- raise validation errors because the DocBook <span class="emphasis"><em>literal</em></span> element was
367
- not designed to support formatted text (using the <span class="emphasis"><em>literal</em></span> element
368
- is a kludge on the part of AsciiDoc as there is no easy way to set
369
- the font style in DocBook.
370
- </li><li>
371
- Cell alignments are ignored for <span class="emphasis"><em>verse</em></span>, <span class="emphasis"><em>literal</em></span> or <span class="emphasis"><em>asciidoc</em></span>
372
- table styles.
373
- </li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s18.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s20.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Manpage Documents</td></tr></table></div></body></html>
data/example/output/ar01s20.html DELETED
@@ -1,27 +0,0 @@
1
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Manpage Documents</title><link rel="stylesheet" href="stylesheets/handbookish.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.74.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ar01s19.html" title="Tables" /><link rel="next" href="ar01s21.html" title="Mathematical Formulas" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Manpage Documents</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s19.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s21.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X1"></a>Manpage Documents</h2></div></div></div><p>Sooner or later, if you program in a UNIX environment, you’re going
4
- to have to write a man page.</p><p>By observing a couple of additional conventions you can compose
5
- AsciiDoc files that will generate DocBook refentry (man page)
6
- documents. The resulting DocBook file can then be translated to the
7
- native roff man page format (or other formats).</p><p>For example, the <code class="literal">asciidoc.1.txt</code> file in the AsciiDoc distribution
8
- <code class="literal">./doc</code> directory was used to generate both the
9
- <code class="literal">asciidoc.1.css-embedded.html</code> HTML file the <code class="literal">asciidoc.1</code> roff
10
- formatted <code class="literal">asciidoc(1)</code> man page.</p><div class="sidebar"><p class="title"><b>Viewing and printing manpage files</b></p><p>Use the <code class="literal">man(1)</code> command to view the manpage file:</p><pre class="literallayout">$ man -l asciidoc.1</pre><p>To print a high quality man page to a postscript printer:</p><pre class="literallayout">$ man -l -Tps asciidoc.1 | lpr</pre><p>You could also create a PDF version of the man page by converting
11
- PostScript to PDF using <code class="literal">ps2pdf(1)</code>:</p><pre class="literallayout">$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf</pre><p>The <code class="literal">ps2pdf(1)</code> command is included in the Ghostscript distribution.</p></div><p>To find out more about man pages view the <code class="literal">man(7)</code> manpage
12
- (<code class="literal">man 7 man</code> and <code class="literal">man man-pages</code> commands).</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_document_header"></a>Document Header</h3></div></div></div><p>A manpage document Header is mandatory. The title line contains the
13
- man page name followed immediately by the manual section number in
14
- brackets, for example <span class="emphasis"><em>ASCIIDOC(1)</em></span>. The title name should not contain
15
- white space and the manual section number is a single digit optionally
16
- followed by a single character.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_the_name_section"></a>The NAME Section</h3></div></div></div><p>The first manpage section is mandatory, must be titled <span class="emphasis"><em>NAME</em></span> and must
17
- contain a single paragraph (usually a single line) consisting of a
18
- list of one or more comma separated command name(s) separated from the
19
- command purpose by a dash character. The dash must have at least one
20
- white space character on either side. For example:</p><pre class="literallayout">printf, fprintf, sprintf - print formatted output</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_the_synopsis_section"></a>The SYNOPSIS Section</h3></div></div></div><p>The second manpage section is mandatory and must be titled <span class="emphasis"><em>SYNOPSIS</em></span>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_refmiscinfo_attributes"></a>refmiscinfo attributes</h3></div></div></div><p>In addition to the automatically created man page <a class="link" href="ar01s27.html" title="Intrinsic Attributes">intrinsic attributes</a> you can assign DocBook
21
- <a class="ulink" href="http://www.docbook.org/tdg5/en/html/refmiscinfo.html" target="_top">refmiscinfo</a>
22
- element <span class="emphasis"><em>source</em></span>, <span class="emphasis"><em>version</em></span> and <span class="emphasis"><em>manual</em></span> values using AsciiDoc
23
- <code class="literal">{mansource}</code>, <code class="literal">{manversion}</code> and <code class="literal">{manmanual}</code> attributes
24
- respectively. This example is from the AsciiDoc header of a man page
25
- source file:</p><pre class="literallayout">:man source: AsciiDoc
26
- :man version: {revnumber}
27
- :man manual: AsciiDoc Manual</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s19.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s21.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Tables </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Mathematical Formulas</td></tr></table></div></body></html>
data/example/output/ar01s21.html DELETED
@@ -1,33 +0,0 @@
1
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Mathematical Formulas</title><link rel="stylesheet" href="stylesheets/handbookish.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.74.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ar01s20.html" title="Manpage Documents" /><link rel="next" href="ar01s22.html" title="Configuration Files" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Mathematical Formulas</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s20.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s22.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X78"></a>Mathematical Formulas</h2></div></div></div><p>The <span class="emphasis"><em>asciimath</em></span> and <span class="emphasis"><em>latexmath</em></span> <a class="link" href="ar01s18.html#X77" title="Passthrough macros">passthrough macros</a> along with
4
- <span class="emphasis"><em>asciimath</em></span> and <span class="emphasis"><em>latexmath</em></span> <a class="link" href="ar01s13.html#X76" title="Passthrough Blocks">passthrough blocks</a> provide a
5
- (backend dependent) mechanism for rendering mathematical formulas. You
6
- can use the following math markups:</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <span class="emphasis"><em>latexmath</em></span> macro used to include <span class="emphasis"><em>LaTeX Math</em></span> in DocBook
7
- outputs is not the same as the <span class="emphasis"><em>latexmath</em></span> macro used to include
8
- <span class="emphasis"><em>LaTeX MathML</em></span> in XHTML outputs. <span class="emphasis"><em>LaTeX Math</em></span> applies to DocBook
9
- outputs that are processed by <a class="link" href="ar01s30.html#X31">dblatex</a> and is normally used to
10
- generate PDF files. <span class="emphasis"><em>LaTeXMathML</em></span> is very much a subset of <span class="emphasis"><em>LaTeX
11
- Math</em></span> and applies to XHTML documents.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_latex_math"></a>LaTeX Math</h3></div></div></div><p><a class="ulink" href="ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf" target="_top">LaTeX
12
- math</a> can be included in documents that are processed by
13
- <a class="link" href="ar01s30.html#X31">dblatex(1)</a>. Example inline formula:</p><pre class="literallayout">latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]</pre><p>For more examples see the <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">AsciiDoc website</a> or the
14
- distributed <code class="literal">doc/latexmath.txt</code> file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_asciimathml"></a>ASCIIMathML</h3></div></div></div><p><a class="ulink" href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html" target="_top">ASCIIMathML</a>
15
- formulas can be included in XHTML documents generated using the
16
- <span class="emphasis"><em>xhtml11</em></span> backend. To enable ASCIIMathML support you must define the
17
- <span class="emphasis"><em>asciimath</em></span> attribute, for example using the <code class="literal">-a asciimath</code>
18
- command-line option. Example inline formula:</p><pre class="literallayout">asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]</pre><p>For more examples see the <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">AsciiDoc website</a> or the
19
- distributed <code class="literal">doc/asciimathml.txt</code> file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_latexmathml"></a>LaTeXMathML</h3></div></div></div><p><span class="emphasis"><em>LaTeXMathML</em></span> allows LaTeX Math style formulas to be included in XHTML
20
- documents generated using the AsciiDoc <span class="emphasis"><em>xhtml11</em></span> backend. AsciiDoc
21
- uses the
22
- <a class="ulink" href="http://www.maths.nottingham.ac.uk/personal/drw/lm.html" target="_top">original
23
- LaTeXMathML</a> by Douglas Woodall. <span class="emphasis"><em>LaTeXMathML</em></span> is derived from
24
- ASCIIMathML and is for users who are more familiar with or prefer
25
- using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
26
- differences are documented on the <span class="emphasis"><em>LaTeXMathML</em></span> web page). To enable
27
- LaTeXMathML support you must define the <span class="emphasis"><em>latexmath</em></span> attribute, for
28
- example using the <code class="literal">-a latexmath</code> command-line option. Example inline
29
- formula:</p><pre class="literallayout">latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]</pre><p>For more examples see the <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">AsciiDoc website</a> or the
30
- distributed <code class="literal">doc/latexmathml.txt</code> file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_mathml"></a>MathML</h3></div></div></div><p><a class="ulink" href="http://www.w3.org/Math/" target="_top">MathML</a> is a low level XML markup for
31
- mathematics. AsciiDoc has no macros for MathML but users familiar with
32
- this markup could use passthrough macros and passthrough blocks to
33
- include MathML in output documents.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s20.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s22.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Manpage Documents </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Configuration Files</td></tr></table></div></body></html>
data/example/output/ar01s22.html DELETED
@@ -1,351 +0,0 @@
1
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Configuration Files</title><link rel="stylesheet" href="stylesheets/handbookish.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.74.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ar01s21.html" title="Mathematical Formulas" /><link rel="next" href="ar01s23.html" title="Document Attributes" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Configuration Files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s21.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s23.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X7"></a>Configuration Files</h2></div></div></div><p>AsciiDoc source file syntax and output file markup is largely
4
- controlled by a set of cascading, text based, configuration files. At
5
- runtime The AsciiDoc default configuration files are combined with
6
- optional user and document specific configuration files.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_configuration_file_format"></a>Configuration File Format</h3></div></div></div><p>Configuration files contain named sections. Each section begins with a
7
- section name in square brackets []. The section body consists of the
8
- lines of text between adjacent section headings.</p><div class="itemizedlist"><ul type="disc"><li>
9
- Section names consist of one or more alphanumeric, underscore or
10
- dash characters and cannot begin or end with a dash.
11
- </li><li>
12
- Lines starting with a hash character "#" are treated as comments and
13
- ignored.
14
- </li><li>
15
- Same named sections and section entries override previously loaded
16
- sections and section entries (this is sometimes referred to as
17
- <span class="emphasis"><em>cascading</em></span>). Consequently, downstream configuration files need
18
- only contain those sections and section entries that need to be
19
- overridden.
20
- </li></ul></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>When creating custom configuration files you only need to include
21
- the sections and entries that differ from the default configuration.</p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>The best way to learn about configuration files is to read the
22
- default configuration files in the AsciiDoc distribution in
23
- conjunction with asciidoc(1) output files. You can view configuration
24
- file load sequence by turning on the asciidoc(1) <code class="literal">-v</code> (<code class="literal">--verbose</code>)
25
- command-line option.</p></div><p>AsciiDoc reserves the following section names for specific purposes:</p><div class="variablelist"><dl><dt><span class="term">
26
- miscellaneous
27
- </span></dt><dd>
28
- Configuration options that don’t belong anywhere else.
29
- </dd><dt><span class="term">
30
- attributes
31
- </span></dt><dd>
32
- Attribute name/value entries.
33
- </dd><dt><span class="term">
34
- specialcharacters
35
- </span></dt><dd>
36
- Special characters reserved by the backend markup.
37
- </dd><dt><span class="term">
38
- tags
39
- </span></dt><dd>
40
- Backend markup tags.
41
- </dd><dt><span class="term">
42
- quotes
43
- </span></dt><dd>
44
- Definitions for quoted inline character formatting.
45
- </dd><dt><span class="term">
46
- specialwords
47
- </span></dt><dd>
48
- Lists of words and phrases singled out for special markup.
49
- </dd><dt><span class="term">
50
- replacements, replacements2
51
- </span></dt><dd>
52
- Find and replace substitution definitions.
53
- </dd><dt><span class="term">
54
- specialsections
55
- </span></dt><dd>
56
- Used to single out special section names for specific markup.
57
- </dd><dt><span class="term">
58
- macros
59
- </span></dt><dd>
60
- Macro syntax definitions.
61
- </dd><dt><span class="term">
62
- titles
63
- </span></dt><dd>
64
- Heading, section and block title definitions.
65
- </dd><dt><span class="term">
66
- paradef-*
67
- </span></dt><dd>
68
- Paragraph element definitions.
69
- </dd><dt><span class="term">
70
- blockdef-*
71
- </span></dt><dd>
72
- DelimitedBlock element definitions.
73
- </dd><dt><span class="term">
74
- listdef-*
75
- </span></dt><dd>
76
- List element definitions.
77
- </dd><dt><span class="term">
78
- listtags-*
79
- </span></dt><dd>
80
- List element tag definitions.
81
- </dd><dt><span class="term">
82
- tabledef-*
83
- </span></dt><dd>
84
- Table element definitions.
85
- </dd><dt><span class="term">
86
- tabletags-*
87
- </span></dt><dd>
88
- Table element tag definitions.
89
- </dd></dl></div><p>Each line of text in these sections is a <span class="emphasis"><em>section entry</em></span>. Section
90
- entries share the following syntax:</p><div class="variablelist"><dl><dt><span class="term">
91
- name=value
92
- </span></dt><dd>
93
- The entry value is set to value.
94
- </dd><dt><span class="term">
95
- name=
96
- </span></dt><dd>
97
- The entry value is set to a zero length string.
98
- </dd><dt><span class="term">
99
- name!
100
- </span></dt><dd>
101
- The entry is undefined (deleted from the configuration). This
102
- syntax only applies to <span class="emphasis"><em>attributes</em></span> and <span class="emphasis"><em>miscellaneous</em></span>
103
- sections.
104
- </dd></dl></div><div class="itemizedlist"><p class="title"><b>Section entry behavior</b></p><ul type="disc"><li>
105
- All equals characters inside the <code class="literal">name</code> must be escaped with a
106
- backslash character.
107
- </li><li>
108
- <code class="literal">name</code> and <code class="literal">value</code> are stripped of leading and trailing white space.
109
- </li><li>
110
- Attribute names, tag entry names and markup template section names
111
- consist of one or more alphanumeric, underscore or dash characters.
112
- Names should not begin or end with a dash.
113
- </li><li>
114
- A blank configuration file section (one without any entries) deletes
115
- any preceding section with the same name (applies to non-markup
116
- template sections).
117
- </li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_miscellaneous_section"></a>Miscellaneous section</h3></div></div></div><p>The optional <code class="literal">[miscellaneous]</code> section specifies the following
118
- <code class="literal">name=value</code> options:</p><div class="variablelist"><dl><dt><span class="term">
119
- newline
120
- </span></dt><dd><p>
121
- Output file line termination characters. Can include any
122
- valid Python string escape sequences. The default value is
123
- <code class="literal">\r\n</code> (carriage return, line feed). Should not be quoted or
124
- contain explicit spaces (use <code class="literal">\x20</code> instead). For example:
125
- </p><pre class="literallayout">$ asciidoc -a 'newline=\n' -b docbook mydoc.txt</pre></dd><dt><span class="term">
126
- outfilesuffix
127
- </span></dt><dd>
128
- The default extension for the output file, for example
129
- <code class="literal">outfilesuffix=.html</code>. Defaults to backend name.
130
- </dd><dt><span class="term">
131
- tabsize
132
- </span></dt><dd>
133
- The number of spaces to expand tab characters, for example
134
- <code class="literal">tabsize=4</code>. Defaults to 8. A <span class="emphasis"><em>tabsize</em></span> of zero suppresses tab
135
- expansion (useful when piping included files through block
136
- filters). Included files can override this option using the
137
- <span class="emphasis"><em>tabsize</em></span> attribute.
138
- </dd><dt><span class="term">
139
- pagewidth, pageunits
140
- </span></dt><dd>
141
- These global table related options are documented in the
142
- <a class="link" href="ar01s28.html#X4">Table Configuration File Definitions</a> sub-section.
143
- </dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><code class="literal">[miscellaneous]</code> configuration file entries can be set using
144
- the asciidoc(1) <code class="literal">-a</code> (<code class="literal">--attribute</code>) command-line option.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_titles_section"></a>Titles section</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
145
- sectiontitle
146
- </span></dt><dd>
147
- Two line section title pattern. The entry value is a Python
148
- regular expression containing the named group <span class="emphasis"><em>title</em></span>.
149
- </dd><dt><span class="term">
150
- underlines
151
- </span></dt><dd><p>
152
- A comma separated list of document and section title underline
153
- character pairs starting with the section level 0 and ending
154
- with section level 4 underline. The default setting is:
155
- </p><pre class="literallayout">underlines="==","--","~~","^^","++"</pre></dd><dt><span class="term">
156
- sect0…sect4
157
- </span></dt><dd>
158
- One line section title patterns. The entry value is a Python
159
- regular expression containing the named group <span class="emphasis"><em>title</em></span>.
160
- </dd><dt><span class="term">
161
- blocktitle
162
- </span></dt><dd>
163
- <a class="link" href="ar01s09.html" title="Block Titles">BlockTitle element</a> pattern. The entry value is a
164
- Python regular expression containing the named group <span class="emphasis"><em>title</em></span>.
165
- </dd><dt><span class="term">
166
- subs
167
- </span></dt><dd>
168
- A comma separated list of substitutions that are performed on
169
- the document header and section titles. Defaults to <span class="emphasis"><em>normal</em></span>
170
- substitution.
171
- </dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_tags_section"></a>Tags section</h3></div></div></div><p>The <code class="literal">[tags]</code> section contains backend tag definitions (one per
172
- line). Tags are used to translate AsciiDoc elements to backend
173
- markup.</p><p>An AsciiDoc tag definition is formatted like
174
- <code class="literal">&lt;tagname&gt;=&lt;starttag&gt;|&lt;endtag&gt;</code>. For example:</p><pre class="literallayout">emphasis=&lt;em&gt;|&lt;/em&gt;</pre><p>In this example asciidoc(1) replaces the | character with the
175
- emphasized text from the AsciiDoc input file and writes the result to
176
- the output file.</p><p>Use the <code class="literal">{brvbar}</code> attribute reference if you need to include a | pipe
177
- character inside tag text.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_attributes_section"></a>Attributes section</h3></div></div></div><p>The optional <code class="literal">[attributes]</code> section contains predefined attributes.</p><p>If the attribute value requires leading or trailing spaces then the
178
- text text should be enclosed in quotation mark (") characters.</p><p>To delete a attribute insert a <code class="literal">name!</code> entry in a downstream
179
- configuration file or use the asciidoc(1) <code class="literal">--attribute name!</code>
180
- command-line option (an attribute name suffixed with a <code class="literal">!</code> character
181
- deletes the attribute)</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_special_characters_section"></a>Special Characters section</h3></div></div></div><p>The <code class="literal">[specialcharacters]</code> section specifies how to escape characters
182
- reserved by the backend markup. Each translation is specified on a
183
- single line formatted like:</p><pre class="literallayout">&lt;special_character&gt;=&lt;translated_characters&gt;</pre><p>Special characters are normally confined to those that resolve
184
- markup ambiguity (in the case of HTML and XML markups the ampersand,
185
- less than and greater than characters). The following example causes
186
- all occurrences of the <code class="literal">&lt;</code> character to be replaced by <code class="literal">&amp;lt;</code>.</p><pre class="literallayout">&lt;=&amp;lt;</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_quoted_text_section"></a>Quoted Text section</h3></div></div></div><p>Quoting is used primarily for text formatting. The <code class="literal">[quotes]</code> section
187
- defines AsciiDoc quoting characters and their corresponding backend
188
- markup tags. Each section entry value is the name of a of a <code class="literal">[tags]</code>
189
- section entry. The entry name is the character (or characters) that
190
- quote the text. The following examples are taken from AsciiDoc
191
- configuration files:</p><pre class="literallayout">[quotes]
192
- _=emphasis</pre><pre class="literallayout">[tags]
193
- emphasis=&lt;em&gt;|&lt;/em&gt;</pre><p>You can specify the left and right quote strings separately by
194
- separating them with a | character, for example:</p><pre class="literallayout">``|''=quoted</pre><p>Omitting the tag will disable quoting, for example, if you don’t want
195
- superscripts or subscripts put the following in a custom configuration
196
- file or edit the global <code class="literal">asciidoc.conf</code> configuration file:</p><pre class="literallayout">[quotes]
197
- ^=
198
- ~=</pre><p><a class="link" href="ar01s07.html#X52" title="Constrained and Unconstrained Quotes">Unconstrained quotes</a> are differentiated from constrained
199
- quotes by prefixing the tag name with a hash character, for example:</p><pre class="literallayout">__=#emphasis</pre><div class="itemizedlist"><p class="title"><b>Quoted text behavior</b></p><ul type="disc"><li>
200
- Quote characters must be non-alphanumeric.
201
- </li><li>
202
- To minimize quoting ambiguity try not to use the same quote
203
- characters in different quote types.
204
- </li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_special_words_section"></a>Special Words section</h3></div></div></div><p>The <code class="literal">[specialwords]</code> section is used to single out words and phrases
205
- that you want to consistently format in some way throughout your
206
- document without having to repeatedly specify the markup. The name of
207
- each entry corresponds to a markup template section and the entry
208
- value consists of a list of words and phrases to be marked up. For
209
- example:</p><pre class="literallayout">[specialwords]
210
- strongwords=NOTE IMPORTANT</pre><pre class="literallayout">[strongwords]
211
- &lt;strong&gt;{words}&lt;/strong&gt;</pre><p>The examples specifies that any occurrence of <code class="literal">NOTE</code> or <code class="literal">IMPORTANT</code>
212
- should appear in a bold font.</p><p>Words and word phrases are treated as Python regular expressions: for
213
- example, the word <code class="literal">^NOTE</code> would only match <code class="literal">NOTE</code> if appeared at
214
- the start of a line.</p><p>AsciiDoc comes with three built-in Special Word types:
215
- <span class="emphasis"><em>emphasizedwords</em></span>, <span class="emphasis"><em>monospacedwords</em></span> and <span class="emphasis"><em>strongwords</em></span>, each has a
216
- corresponding (backend specific) markup template section. Edit the
217
- configuration files to customize existing Special Words and to add new
218
- ones.</p><div class="itemizedlist"><p class="title"><b>Special word behavior</b></p><ul type="disc"><li>
219
- Word list entries must be separated by space characters.
220
- </li><li>
221
- Word list entries with embedded spaces should be enclosed in quotation (")
222
- characters.
223
- </li><li>
224
- A <code class="literal">[specialwords]</code> section entry of the form
225
- <code class="literal">name=word1 [word2…]</code> adds words to existing <code class="literal">name</code> entries.
226
- </li><li>
227
- A <code class="literal">[specialwords]</code> section entry of the form <code class="literal">name</code> undefines
228
- (deletes) all existing <code class="literal">name</code> words.
229
- </li><li>
230
- Since word list entries are processed as Python regular expressions
231
- you need to be careful to escape regular expression special
232
- characters.
233
- </li><li>
234
- By default Special Words are substituted before Inline Macros, this
235
- may lead to undesirable consequences. For example the special word
236
- <code class="literal">foobar</code> would be expanded inside the macro call
237
- <code class="literal">http://www.foobar.com[]</code>. A possible solution is to emphasize
238
- whole words only by defining the word using regular expression
239
- characters, for example <code class="literal">\bfoobar\b</code>.
240
- </li><li>
241
- If the first matched character of a special word is a backslash then
242
- the remaining characters are output without markup i.e. the
243
- backslash can be used to escape special word markup. For example
244
- the special word <code class="literal">\\?\b[Tt]en\b</code> will mark up the words <code class="literal">Ten</code> and
245
- <code class="literal">ten</code> only if they are not preceded by a backslash.
246
- </li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X10"></a>Replacements section</h3></div></div></div><p><code class="literal">[replacements]</code> and <code class="literal">[replacements2]</code> configuration file entries
247
- specify find and replace text and are formatted like:</p><pre class="literallayout">&lt;find_pattern&gt;=&lt;replacement_text&gt;</pre><p>The find text can be a Python regular expression; the replace text can
248
- contain Python regular expression group references.</p><p>Use Replacement shortcuts for often used macro references, for
249
- example (the second replacement allows us to backslash escape the
250
- macro name):</p><pre class="literallayout">NEW!=image:./images/smallnew.png[New!]
251
- \\NEW!=NEW!</pre><div class="itemizedlist"><p class="title"><b>Replacement behavior</b></p><ul type="disc"><li>
252
- The built-in replacements can be escaped with a backslash.
253
- </li><li>
254
- If the find or replace text has leading or trailing spaces then the
255
- text should be enclosed in quotation (") characters.
256
- </li><li>
257
- Since the find text is processed as a regular expression you need to
258
- be careful to escape regular expression special characters.
259
- </li><li>
260
- Replacements are performed in the same order they appear in the
261
- configuration file replacements section.
262
- </li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_markup_template_sections"></a>Markup Template Sections</h3></div></div></div><p>Markup template sections supply backend markup for translating
263
- AsciiDoc elements. Since the text is normally backend dependent
264
- you’ll find these sections in the backend specific configuration
265
- files. Template sections differ from other sections in that they
266
- contain a single block of text instead of per line <span class="emphasis"><em>name=value</em></span>
267
- entries. A markup template section body can contain:</p><div class="itemizedlist"><ul type="disc"><li>
268
- Attribute references
269
- </li><li>
270
- System macro calls.
271
- </li><li>
272
- A document content placeholder
273
- </li></ul></div><p>The document content placeholder is a single | character and is
274
- replaced by text from the source element. Use the <code class="literal">{brvbar}</code>
275
- attribute reference if you need a literal | character in the template.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X27"></a>Configuration File Names and Locations</h3></div></div></div><p>Configuration files have a <code class="literal">.conf</code> file name extension; they are
276
- loaded from the following locations:</p><div class="orderedlist"><ol type="1"><li>
277
- The directory containing the asciidoc executable.
278
- </li><li>
279
- If there is no <code class="literal">asciidoc.conf</code> file in the directory containing the
280
- asciidoc executable then load from the global configuration
281
- directory (normally <code class="literal">/etc/asciidoc</code> or <code class="literal">/usr/local/etc/asciidoc</code>)
282
- i.e. the global configuration files directory is skipped if
283
- AsciiDoc configuration files are installed in the same directory as
284
- the asciidoc executable. This allows both a system wide copy and
285
- multiple local copies of AsciiDoc to coexist on the same host PC.
286
- </li><li>
287
- The user’s <code class="literal">$HOME/.asciidoc</code> directory (if it exists).
288
- </li><li>
289
- The directory containing the AsciiDoc source file.
290
- </li><li>
291
- Explicit configuration files specified with the asciidoc(1)
292
- <code class="literal">--conf-file</code>) command-line option. The <code class="literal">--conf-file</code> option can
293
- be specified multiple times, in which case configuration files will
294
- be processed in the same order they appear on the command-line.
295
- </li></ol></div><p>Configuration files from the above locations are loaded in the
296
- following order:</p><div class="itemizedlist"><ul type="disc"><li><p>
297
- The <code class="literal">[attributes]</code> section only from:
298
- </p><div class="itemizedlist"><ul type="circle"><li>
299
- <code class="literal">asciidoc.conf</code> in location 3
300
- </li><li><p>
301
- Files from location 5.
302
- </p><p>This first pass makes locally set attributes available in the global
303
- <code class="literal">asciidoc.conf</code> file.</p></li></ul></div></li><li>
304
- <code class="literal">asciidoc.conf</code> from locations 1, 2, 3.
305
- </li><li>
306
- <span class="emphasis"><em>attributes</em></span>, <span class="emphasis"><em>titles</em></span> and <span class="emphasis"><em>specialcharacters</em></span> sections from the
307
- <code class="literal">asciidoc.conf</code> in location 4.
308
- </li><li>
309
- The document header is parsed at this point and we can assume the
310
- <span class="emphasis"><em>backend</em></span> and <span class="emphasis"><em>doctype</em></span> have now been defined.
311
- </li><li>
312
- <code class="literal">&lt;backend&gt;.conf</code> and <code class="literal">&lt;backend&gt;-&lt;doctype&gt;.conf</code> from locations 1,
313
- 2,3.
314
- </li><li>
315
- Filter conf files from the <code class="literal">filters</code> directory in locations 1, 2, 3.
316
- </li><li>
317
- <code class="literal">lang-&lt;lang&gt;.conf</code> from locations 1, 2, 3.
318
- </li><li>
319
- <code class="literal">asciidoc.conf</code> from location 4.
320
- </li><li>
321
- <code class="literal">&lt;backend&gt;.conf</code> and <code class="literal">&lt;backend&gt;-&lt;doctype&gt;.conf</code> from location 4.
322
- 2,3.
323
- </li><li>
324
- Filter conf files from location 4.
325
- </li><li>
326
- <code class="literal">&lt;docfile&gt;.conf</code> and <code class="literal">&lt;docfile&gt;-&lt;backend&gt;.conf</code> from location 4.
327
- </li><li>
328
- Configuration files from location 5.
329
- </li></ul></div><p>Where:</p><div class="itemizedlist"><ul type="disc"><li>
330
- <code class="literal">&lt;backend&gt;</code> and <code class="literal">&lt;doctype&gt;</code> are values specified by the asciidoc(1)
331
- <code class="literal">-b</code> (<code class="literal">--backend</code>) and <code class="literal">-d</code> (<code class="literal">--doctype</code>) command-line options.
332
- </li><li>
333
- <code class="literal">&lt;infile&gt;</code> is the path name of the AsciiDoc input file without the
334
- file name extension.
335
- </li><li>
336
- <code class="literal">&lt;lang&gt;</code> is a two letter country code set by the the AsciiDoc <span class="emphasis"><em>lang</em></span>
337
- attribute.
338
- </li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The backend and language global configuration files are loaded <span class="strong"><strong>after</strong></span>
339
- the header has been parsed. This means that you can set most
340
- attributes in the document header. Here’s an example header:</p><pre class="literallayout">Life's Mysteries
341
- ================
342
- :author: Hu Nose
343
- :doctype: book
344
- :toc:
345
- :icons:
346
- :data-uri:
347
- :lang: en
348
- :encoding: iso-8859-1</pre><p>Attributes set in the document header take precedence over
349
- configuration file attributes.</p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Use the asciidoc(1) <code class="literal">-v</code> (<code class="literal">--verbose</code>) command-line option to see
350
- which configuration files are loaded and the order in which they are
351
- loaded.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s21.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s23.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Mathematical Formulas </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Document Attributes</td></tr></table></div></body></html>