FooBarWidget-mizuho 0.9.3 → 0.9.4
Sign up to get free protection for your applications and to get access to all the features.
- data/asciidoc/BUGS +3 -3
- data/asciidoc/CHANGELOG +112 -63
- data/asciidoc/CHANGELOG.txt +50 -0
- data/asciidoc/INSTALL +6 -6
- data/asciidoc/Makefile.in +21 -5
- data/asciidoc/README +3 -3
- data/asciidoc/asciidoc.conf +9 -12
- data/asciidoc/asciidoc.py +204 -151
- data/asciidoc/common.aap +2 -2
- data/asciidoc/doc/a2x.1 +4 -3
- data/asciidoc/doc/a2x.1.txt +1 -1
- data/asciidoc/doc/article.css-embedded.html +13 -12
- data/asciidoc/doc/article.html +46 -644
- data/asciidoc/doc/article.pdf +0 -0
- data/asciidoc/doc/asciidoc.1 +2 -2
- data/asciidoc/doc/asciidoc.1.css-embedded.html +14 -13
- data/asciidoc/doc/asciidoc.1.css.html +3 -3
- data/asciidoc/doc/asciidoc.1.html +3 -3
- data/asciidoc/doc/asciidoc.css-embedded.html +238 -225
- data/asciidoc/doc/asciidoc.css.html +227 -215
- data/asciidoc/doc/asciidoc.dict +10 -1
- data/asciidoc/doc/asciidoc.html +181 -164
- data/asciidoc/doc/asciidoc.txt +167 -148
- data/asciidoc/doc/asciimathml.txt +5 -4
- data/asciidoc/doc/book.css-embedded.html +13 -12
- data/asciidoc/doc/faq.txt +60 -3
- data/asciidoc/doc/music-filter.html +94 -41
- data/asciidoc/doc/music-filter.pdf +0 -0
- data/asciidoc/doc/source-highlight-filter.html +125 -465
- data/asciidoc/doc/source-highlight-filter.pdf +0 -0
- data/asciidoc/docbook.conf +8 -2
- data/asciidoc/examples/website/CHANGELOG.html +129 -4
- data/asciidoc/examples/website/INSTALL.html +6 -6
- data/asciidoc/examples/website/README-website.html +3 -3
- data/asciidoc/examples/website/README.html +3 -3
- data/asciidoc/examples/website/a2x.1.html +4 -4
- data/asciidoc/examples/website/asciidoc-docbook-xsl.html +3 -3
- data/asciidoc/examples/website/asciidoc-graphviz-sample.txt +1 -0
- data/asciidoc/examples/website/downloads.html +7 -7
- data/asciidoc/examples/website/faq.html +95 -40
- data/asciidoc/examples/website/index.html +34 -13
- data/asciidoc/examples/website/index.txt +25 -9
- data/asciidoc/examples/website/latex-backend.html +4 -4
- data/asciidoc/examples/website/manpage.html +3 -3
- data/asciidoc/examples/website/music-filter.html +3 -3
- data/asciidoc/examples/website/sample1.png +0 -0
- data/asciidoc/examples/website/sample3.png +0 -0
- data/asciidoc/examples/website/sample4.png +0 -0
- data/asciidoc/examples/website/source-highlight-filter.html +5 -5
- data/asciidoc/examples/website/support.html +3 -3
- data/asciidoc/examples/website/userguide.html +227 -215
- data/asciidoc/examples/website/version9.html +3 -3
- data/asciidoc/filters/{code-filter-readme.txt → code/code-filter-readme.txt} +0 -0
- data/asciidoc/filters/{code-filter-test.txt → code/code-filter-test.txt} +0 -0
- data/asciidoc/filters/{code-filter.conf → code/code-filter.conf} +1 -1
- data/asciidoc/filters/{code-filter.py → code/code-filter.py} +0 -0
- data/asciidoc/filters/graphviz/asciidoc-graphviz-sample.txt +130 -0
- data/asciidoc/filters/graphviz/graphviz-filter.conf +39 -0
- data/asciidoc/filters/graphviz/graphviz2png.py +154 -0
- data/asciidoc/filters/{music-filter-test.txt → music/music-filter-test.txt} +0 -0
- data/asciidoc/filters/{music-filter.conf → music/music-filter.conf} +0 -0
- data/asciidoc/filters/{music2png.py → music/music2png.py} +0 -0
- data/asciidoc/filters/{source-highlight-filter-test.txt → source/source-highlight-filter-test.txt} +0 -0
- data/asciidoc/filters/{source-highlight-filter.conf → source/source-highlight-filter.conf} +2 -1
- data/asciidoc/html4.conf +5 -2
- data/asciidoc/stylesheets/xhtml11-quirks.css +0 -8
- data/asciidoc/stylesheets/xhtml11.css +11 -2
- data/asciidoc/vim/syntax/asciidoc.vim +1 -1
- data/asciidoc/xhtml11.conf +5 -2
- data/lib/mizuho/parser.rb +5 -1
- data/mizuho.gemspec +5 -16
- data/test/parser_spec.rb +49 -0
- metadata +22 -10
data/asciidoc/doc/asciidoc.dict
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
personal_ws-1.1 en
|
|
1
|
+
personal_ws-1.1 en 732
|
|
2
2
|
Sturmer
|
|
3
3
|
Kleber
|
|
4
4
|
Kl�ber
|
|
@@ -55,6 +55,7 @@ ListContinuation
|
|
|
55
55
|
listcontinuation
|
|
56
56
|
consectetuer
|
|
57
57
|
Magnocavallo
|
|
58
|
+
Gouichi
|
|
58
59
|
defacto
|
|
59
60
|
ListParagraph
|
|
60
61
|
charset
|
|
@@ -112,6 +113,7 @@ dsv
|
|
|
112
113
|
O'Reilly
|
|
113
114
|
dvi
|
|
114
115
|
CommentBlocks
|
|
116
|
+
lowerroman
|
|
115
117
|
gif
|
|
116
118
|
Builtin
|
|
117
119
|
tabledef
|
|
@@ -132,6 +134,7 @@ itemtag
|
|
|
132
134
|
entrytag
|
|
133
135
|
hhc
|
|
134
136
|
else's
|
|
137
|
+
Graphviz
|
|
135
138
|
executables
|
|
136
139
|
basebackend
|
|
137
140
|
expr
|
|
@@ -156,6 +159,7 @@ fermentum
|
|
|
156
159
|
ListingBlocks
|
|
157
160
|
GPL
|
|
158
161
|
hsides
|
|
162
|
+
upperalpha
|
|
159
163
|
Bolido
|
|
160
164
|
B�lido
|
|
161
165
|
footrow
|
|
@@ -299,6 +303,7 @@ rewriteURI
|
|
|
299
303
|
formatlistpat
|
|
300
304
|
Konqueror
|
|
301
305
|
pageunit
|
|
306
|
+
upperroman
|
|
302
307
|
Blauer
|
|
303
308
|
backmatter
|
|
304
309
|
stdin
|
|
@@ -444,6 +449,7 @@ RTF
|
|
|
444
449
|
DSSSL
|
|
445
450
|
fileext
|
|
446
451
|
WINA
|
|
452
|
+
arabic
|
|
447
453
|
fringilla
|
|
448
454
|
retab
|
|
449
455
|
BackendBlocks
|
|
@@ -465,6 +471,7 @@ endtag
|
|
|
465
471
|
Vasilev
|
|
466
472
|
crlf
|
|
467
473
|
vel
|
|
474
|
+
Iisaka's
|
|
468
475
|
localtime
|
|
469
476
|
blockmacro
|
|
470
477
|
BlockMacro
|
|
@@ -585,6 +592,7 @@ superscripted
|
|
|
585
592
|
glossdiv
|
|
586
593
|
symlinked
|
|
587
594
|
Mihai
|
|
595
|
+
Pychart
|
|
588
596
|
Klum
|
|
589
597
|
fo
|
|
590
598
|
sgmlformat
|
|
@@ -713,6 +721,7 @@ AsciiDoc
|
|
|
713
721
|
manmanual
|
|
714
722
|
TableBody
|
|
715
723
|
realpath
|
|
724
|
+
loweralpha
|
|
716
725
|
labitur
|
|
717
726
|
prepended
|
|
718
727
|
builtins
|
data/asciidoc/doc/asciidoc.html
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
2
|
-
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>AsciiDoc User Guide</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id2425213"></a>AsciiDoc User Guide</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Stuart</span> <span class="surname">Rackham</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:srackham@gmail.com">srackham@gmail.com</a>></code></p></div></div></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 8.3.1</td><td align="left">14 December 2008</td><td align="left">SJR</td></tr></table></div></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#_introduction">1. Introduction</a></span></dt><dt><span class="section"><a href="#X6">2. Getting Started</a></span></dt><dd><dl><dt><span class="section"><a href="#_installing_asciidoc">2.1. Installing AsciiDoc</a></span></dt><dt><span class="section"><a href="#X11">2.2. Example AsciiDoc Documents</a></span></dt></dl></dd><dt><span class="section"><a href="#_asciidoc_document_types">3. AsciiDoc Document Types</a></span></dt><dd><dl><dt><span class="section"><a href="#_article">3.1. article</a></span></dt><dt><span class="section"><a href="#_book">3.2. book</a></span></dt><dt><span class="section"><a href="#_manpage">3.3. manpage</a></span></dt></dl></dd><dt><span class="section"><a href="#X5">4. AsciiDoc Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#_docbook">4.1. docbook</a></span></dt><dt><span class="section"><a href="#X33">4.2. xhtml11</a></span></dt><dt><span class="section"><a href="#_html4">4.3. html4</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_structure">5. Document Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#_block_elements">5.1. Block Elements</a></span></dt><dt><span class="section"><a href="#_header">5.2. Header</a></span></dt><dt><span class="section"><a href="#_preamble">5.3. Preamble</a></span></dt><dt><span class="section"><a href="#_sections">5.4. Sections</a></span></dt><dt><span class="section"><a href="#_inline_elements">5.5. Inline Elements</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_processing">6. Document Processing</a></span></dt><dt><span class="section"><a href="#_text_formatting">7. Text Formatting</a></span></dt><dd><dl><dt><span class="section"><a href="#X51">7.1. Quoted Text</a></span></dt><dt><span class="section"><a href="#_superscripts_and_subscripts">7.2. Superscripts and Subscripts</a></span></dt><dt><span class="section"><a href="#_line_breaks">7.3. Line Breaks</a></span></dt><dt><span class="section"><a href="#_page_breaks">7.4. Page Breaks</a></span></dt><dt><span class="section"><a href="#_rulers">7.5. Rulers</a></span></dt><dt><span class="section"><a href="#_tabs">7.6. Tabs</a></span></dt><dt><span class="section"><a href="#_replacements">7.7. Replacements</a></span></dt><dt><span class="section"><a href="#_special_words">7.8. Special Words</a></span></dt></dl></dd><dt><span class="section"><a href="#X17">8. Titles</a></span></dt><dd><dl><dt><span class="section"><a href="#_two_line_titles">8.1. Two line titles</a></span></dt><dt><span class="section"><a href="#X46">8.2. One line titles</a></span></dt></dl></dd><dt><span class="section"><a href="#X42">9. BlockTitles</a></span></dt><dt><span class="section"><a href="#X41">10. BlockId Element</a></span></dt><dt><span class="section"><a href="#_paragraphs">11. Paragraphs</a></span></dt><dd><dl><dt><span class="section"><a href="#_default_paragraph">11.1. Default Paragraph</a></span></dt><dt><span class="section"><a href="#_literal_paragraph">11.2. Literal Paragraph</a></span></dt><dt><span class="section"><a href="#X28">11.3. Admonition Paragraphs</a></span></dt></dl></dd><dt><span class="section"><a href="#_delimited_blocks">12. Delimited Blocks</a></span></dt><dd><dl><dt><span class="section"><a href="#_predefined_delimited_blocks">12.1. Predefined Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_listing_blocks">12.2. Listing Blocks</a></span></dt><dt><span class="section"><a href="#X65">12.3. Literal Blocks</a></span></dt><dt><span class="section"><a href="#_sidebarblocks">12.4. SidebarBlocks</a></span></dt><dt><span class="section"><a href="#X26">12.5. Comment Blocks</a></span></dt><dt><span class="section"><a href="#X76">12.6. Passthrough Blocks</a></span></dt><dt><span class="section"><a href="#_quote_blocks">12.7. Quote Blocks</a></span></dt><dt><span class="section"><a href="#X48">12.8. Example Blocks</a></span></dt><dt><span class="section"><a href="#X22">12.9. Admonition Blocks</a></span></dt></dl></dd><dt><span class="section"><a href="#X64">13. Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#_bulleted_and_numbered_lists">13.1. Bulleted and Numbered Lists</a></span></dt><dt><span class="section"><a href="#_labeled_lists">13.2. Labeled Lists</a></span></dt><dt><span class="section"><a href="#_question_and_answer_lists">13.3. Question and Answer Lists</a></span></dt><dt><span class="section"><a href="#_glossary_lists">13.4. Glossary Lists</a></span></dt><dt><span class="section"><a href="#_bibliography_lists">13.5. Bibliography Lists</a></span></dt><dt><span class="section"><a href="#X15">13.6. List Item Continuation</a></span></dt><dt><span class="section"><a href="#X29">13.7. List Block</a></span></dt></dl></dd><dt><span class="section"><a href="#_footnotes">14. Footnotes</a></span></dt><dt><span class="section"><a href="#_indexes">15. Indexes</a></span></dt><dt><span class="section"><a href="#_callouts">16. Callouts</a></span></dt><dd><dl><dt><span class="section"><a href="#_implementation_notes">16.1. Implementation Notes</a></span></dt><dt><span class="section"><a href="#_including_callouts_in_included_code">16.2. Including callouts in included code</a></span></dt></dl></dd><dt><span class="section"><a href="#_macros">17. Macros</a></span></dt><dd><dl><dt><span class="section"><a href="#_inline_macros">17.1. Inline Macros</a></span></dt><dt><span class="section"><a href="#_block_macros">17.2. Block Macros</a></span></dt><dt><span class="section"><a href="#_system_macros">17.3. System Macros</a></span></dt><dt><span class="section"><a href="#X77">17.4. Passthrough macros</a></span></dt><dt><span class="section"><a href="#_macro_definitions">17.5. Macro Definitions</a></span></dt></dl></dd><dt><span class="section"><a href="#_tables">18. Tables</a></span></dt><dd><dl><dt><span class="section"><a href="#_example_tables">18.1. Example tables</a></span></dt><dt><span class="section"><a href="#X68">18.2. Table input data formats</a></span></dt><dt><span class="section"><a href="#X69">18.3. Table attributes</a></span></dt><dt><span class="section"><a href="#X70">18.4. Column Specifiers</a></span></dt><dt><span class="section"><a href="#X71">18.5. Table styles</a></span></dt><dt><span class="section"><a href="#X72">18.6. Markup attributes</a></span></dt><dt><span class="section"><a href="#_nested_tables">18.7. Nested tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X1">19. Manpage Documents</a></span></dt><dd><dl><dt><span class="section"><a href="#_document_header">19.1. Document Header</a></span></dt><dt><span class="section"><a href="#_the_name_section">19.2. The NAME Section</a></span></dt><dt><span class="section"><a href="#_the_synopsis_section">19.3. The SYNOPSIS Section</a></span></dt><dt><span class="section"><a href="#_refmiscinfo_attributes">19.4. refmiscinfo attributes</a></span></dt></dl></dd><dt><span class="section"><a href="#X78">20. Mathematical Formulas</a></span></dt><dd><dl><dt><span class="section"><a href="#_latex_math">20.1. LaTeX Math</a></span></dt><dt><span class="section"><a href="#_asciimathml">20.2. ASCIIMathML</a></span></dt><dt><span class="section"><a href="#_latexmathml">20.3. LaTeXMathML</a></span></dt><dt><span class="section"><a href="#_mathml">20.4. MathML</a></span></dt></dl></dd><dt><span class="section"><a href="#X7">21. Configuration Files</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuration_file_format">21.1. Configuration File Format</a></span></dt><dt><span class="section"><a href="#_miscellaneous_section">21.2. Miscellaneous section</a></span></dt><dt><span class="section"><a href="#_titles_section">21.3. Titles section</a></span></dt><dt><span class="section"><a href="#_tags_section">21.4. Tags section</a></span></dt><dt><span class="section"><a href="#_attributes_section">21.5. Attributes section</a></span></dt><dt><span class="section"><a href="#_special_characters_section">21.6. Special Characters section</a></span></dt><dt><span class="section"><a href="#_quoted_text_section">21.7. Quoted Text section</a></span></dt><dt><span class="section"><a href="#_special_words_section">21.8. Special Words section</a></span></dt><dt><span class="section"><a href="#X10">21.9. Replacements section</a></span></dt><dt><span class="section"><a href="#_markup_template_sections">21.10. Markup Template Sections</a></span></dt><dt><span class="section"><a href="#X27">21.11. Configuration File Names and Locations</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_attributes">22. Document Attributes</a></span></dt><dt><span class="section"><a href="#X18">23. Attribute Entries</a></span></dt><dd><dl><dt><span class="section"><a href="#_setting_configuration_entries">23.1. Setting configuration entries</a></span></dt></dl></dd><dt><span class="section"><a href="#X21">24. Attribute Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#X75">24.1. Options attribute</a></span></dt><dt><span class="section"><a href="#_macro_attribute_lists">24.2. Macro Attribute lists</a></span></dt><dt><span class="section"><a href="#_attributelist_element">24.3. AttributeList Element</a></span></dt></dl></dd><dt><span class="section"><a href="#_attribute_references">25. Attribute References</a></span></dt><dd><dl><dt><span class="section"><a href="#_simple_attributes_references">25.1. Simple Attributes References</a></span></dt><dt><span class="section"><a href="#_conditional_attribute_references">25.2. Conditional Attribute References</a></span></dt><dt><span class="section"><a href="#X24">25.3. System Attribute References</a></span></dt></dl></dd><dt><span class="section"><a href="#X60">26. Intrinsic Attributes</a></span></dt><dt><span class="section"><a href="#X73">27. Block Element Definitions</a></span></dt><dd><dl><dt><span class="section"><a href="#X23">27.1. Styles</a></span></dt><dt><span class="section"><a href="#_paragraphs_2">27.2. Paragraphs</a></span></dt><dt><span class="section"><a href="#_delimited_blocks_2">27.3. Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_lists">27.4. Lists</a></span></dt><dt><span class="section"><a href="#_tables_2">27.5. Tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X59">28. Filters</a></span></dt><dd><dl><dt><span class="section"><a href="#_filter_search_paths">28.1. Filter Search Paths</a></span></dt><dt><span class="section"><a href="#_filter_configuration_files">28.2. Filter Configuration Files</a></span></dt><dt><span class="section"><a href="#X56">28.3. Code Filter</a></span></dt><dt><span class="section"><a href="#X57">28.4. Source Code Highlighter Filter</a></span></dt><dt><span class="section"><a href="#X58">28.5. Music Filter</a></span></dt></dl></dd><dt><span class="section"><a href="#X12">29. Converting DocBook to other file formats</a></span></dt><dd><dl><dt><span class="section"><a href="#X43">29.1. a2x Toolchain Wrapper</a></span></dt><dt><span class="section"><a href="#_html_generation">29.2. HTML generation</a></span></dt><dt><span class="section"><a href="#_pdf_generation">29.3. PDF generation</a></span></dt><dt><span class="section"><a href="#_html_help_generation">29.4. HTML Help generation</a></span></dt><dt><span class="section"><a href="#_toolchain_components_summary">29.5. Toolchain components summary</a></span></dt><dt><span class="section"><a href="#_asciidoc_dblatex_configuration_files">29.6. AsciiDoc dblatex configuration files</a></span></dt><dt><span class="section"><a href="#_asciidoc_docbook_xsl_stylesheets_drivers">29.7. AsciiDoc DocBook XSL Stylesheets drivers</a></span></dt></dl></dd><dt><span class="section"><a href="#_generating_plain_text_files">30. Generating Plain Text Files</a></span></dt><dt><span class="section"><a href="#_xml_and_character_sets">31. XML and Character Sets</a></span></dt><dd><dl><dt><span class="section"><a href="#_pdf_fonts">31.1. PDF Fonts</a></span></dt></dl></dd><dt><span class="section"><a href="#X36">32. Help Commands</a></span></dt><dd><dl><dt><span class="section"><a href="#_customizing_help">32.1. Customizing Help</a></span></dt></dl></dd><dt><span class="section"><a href="#_tips_and_tricks">33. Tips and Tricks</a></span></dt><dd><dl><dt><span class="section"><a href="#_know_your_editor">33.1. Know Your Editor</a></span></dt><dt><span class="section"><a href="#X20">33.2. Vim Commands for Formatting AsciiDoc</a></span></dt><dt><span class="section"><a href="#_troubleshooting">33.3. Troubleshooting</a></span></dt><dt><span class="section"><a href="#_gotchas">33.4. Gotchas</a></span></dt><dt><span class="section"><a href="#_combining_separate_documents">33.5. Combining Separate Documents</a></span></dt><dt><span class="section"><a href="#_processing_document_sections_separately">33.6. Processing Document Sections Separately</a></span></dt><dt><span class="section"><a href="#_processing_document_chunks">33.7. Processing Document Chunks</a></span></dt><dt><span class="section"><a href="#_badges_in_html_page_footers">33.8. Badges in HTML Page Footers</a></span></dt><dt><span class="section"><a href="#_pretty_printing_asciidoc_output">33.9. Pretty Printing AsciiDoc Output</a></span></dt><dt><span class="section"><a href="#_supporting_minor_docbook_dtd_variations">33.10. Supporting Minor DocBook DTD Variations</a></span></dt><dt><span class="section"><a href="#_shipping_stand_alone_asciidoc_source">33.11. Shipping Stand-alone AsciiDoc Source</a></span></dt><dt><span class="section"><a href="#_inserting_blank_space">33.12. Inserting Blank Space</a></span></dt><dt><span class="section"><a href="#_closing_open_sections">33.13. Closing Open Sections</a></span></dt><dt><span class="section"><a href="#_validating_output_files">33.14. Validating Output Files</a></span></dt></dl></dd><dt><span class="glossary"><a href="#_glossary">Glossary</a></span></dt><dt><span class="appendix"><a href="#_migration_notes">A. Migration Notes</a></span></dt><dd><dl><dt><span class="section"><a href="#X53">A.1. Version 7 to version 8</a></span></dt></dl></dd><dt><span class="appendix"><a href="#X38">B. Packager Notes</a></span></dt><dt><span class="appendix"><a href="#X39">C. AsciiDoc Safe Mode</a></span></dt><dt><span class="appendix"><a href="#_using_asciidoc_with_non_english_languages">D. Using AsciiDoc with non-English Languages</a></span></dt><dt><span class="appendix"><a href="#_vim_syntax_highlighter">E. Vim Syntax Highlighter</a></span></dt><dd><dl><dt><span class="section"><a href="#_limitations">E.1. Limitations</a></span></dt></dl></dd><dt><span class="appendix"><a href="#X74">F. Attribute Options</a></span></dt></dl></div><p><span class="emphasis"><em>AsciiDoc</em></span> is a text document format for writing short documents,
|
|
2
|
+
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>AsciiDoc User Guide</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id2425213"></a>AsciiDoc User Guide</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Stuart</span> <span class="surname">Rackham</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:srackham@gmail.com">srackham@gmail.com</a>></code></p></div></div></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 8.3.3</td><td align="left">2 January 2009</td><td align="left">SJR</td></tr></table></div></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#_introduction">1. Introduction</a></span></dt><dt><span class="section"><a href="#X6">2. Getting Started</a></span></dt><dd><dl><dt><span class="section"><a href="#_installing_asciidoc">2.1. Installing AsciiDoc</a></span></dt><dt><span class="section"><a href="#X11">2.2. Example AsciiDoc Documents</a></span></dt></dl></dd><dt><span class="section"><a href="#_asciidoc_document_types">3. AsciiDoc Document Types</a></span></dt><dd><dl><dt><span class="section"><a href="#_article">3.1. article</a></span></dt><dt><span class="section"><a href="#_book">3.2. book</a></span></dt><dt><span class="section"><a href="#_manpage">3.3. manpage</a></span></dt></dl></dd><dt><span class="section"><a href="#X5">4. AsciiDoc Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#_docbook">4.1. docbook</a></span></dt><dt><span class="section"><a href="#X33">4.2. xhtml11</a></span></dt><dt><span class="section"><a href="#_html4">4.3. html4</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_structure">5. Document Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#_block_elements">5.1. Block Elements</a></span></dt><dt><span class="section"><a href="#_header">5.2. Header</a></span></dt><dt><span class="section"><a href="#_preamble">5.3. Preamble</a></span></dt><dt><span class="section"><a href="#_sections">5.4. Sections</a></span></dt><dt><span class="section"><a href="#_inline_elements">5.5. Inline Elements</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_processing">6. Document Processing</a></span></dt><dt><span class="section"><a href="#_text_formatting">7. Text Formatting</a></span></dt><dd><dl><dt><span class="section"><a href="#X51">7.1. Quoted Text</a></span></dt><dt><span class="section"><a href="#_superscripts_and_subscripts">7.2. Superscripts and Subscripts</a></span></dt><dt><span class="section"><a href="#_line_breaks">7.3. Line Breaks</a></span></dt><dt><span class="section"><a href="#_page_breaks">7.4. Page Breaks</a></span></dt><dt><span class="section"><a href="#_rulers">7.5. Rulers</a></span></dt><dt><span class="section"><a href="#_tabs">7.6. Tabs</a></span></dt><dt><span class="section"><a href="#_replacements">7.7. Replacements</a></span></dt><dt><span class="section"><a href="#_special_words">7.8. Special Words</a></span></dt></dl></dd><dt><span class="section"><a href="#X17">8. Titles</a></span></dt><dd><dl><dt><span class="section"><a href="#_two_line_titles">8.1. Two line titles</a></span></dt><dt><span class="section"><a href="#X46">8.2. One line titles</a></span></dt></dl></dd><dt><span class="section"><a href="#X42">9. BlockTitles</a></span></dt><dt><span class="section"><a href="#X41">10. BlockId Element</a></span></dt><dt><span class="section"><a href="#_paragraphs">11. Paragraphs</a></span></dt><dd><dl><dt><span class="section"><a href="#_default_paragraph">11.1. Default Paragraph</a></span></dt><dt><span class="section"><a href="#_literal_paragraph">11.2. Literal Paragraph</a></span></dt><dt><span class="section"><a href="#X28">11.3. Admonition Paragraphs</a></span></dt></dl></dd><dt><span class="section"><a href="#_delimited_blocks">12. Delimited Blocks</a></span></dt><dd><dl><dt><span class="section"><a href="#_predefined_delimited_blocks">12.1. Predefined Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_listing_blocks">12.2. Listing Blocks</a></span></dt><dt><span class="section"><a href="#X65">12.3. Literal Blocks</a></span></dt><dt><span class="section"><a href="#_sidebarblocks">12.4. SidebarBlocks</a></span></dt><dt><span class="section"><a href="#X26">12.5. Comment Blocks</a></span></dt><dt><span class="section"><a href="#X76">12.6. Passthrough Blocks</a></span></dt><dt><span class="section"><a href="#_quote_blocks">12.7. Quote Blocks</a></span></dt><dt><span class="section"><a href="#X48">12.8. Example Blocks</a></span></dt><dt><span class="section"><a href="#X22">12.9. Admonition Blocks</a></span></dt></dl></dd><dt><span class="section"><a href="#X64">13. Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#_bulleted_and_numbered_lists">13.1. Bulleted and Numbered Lists</a></span></dt><dt><span class="section"><a href="#_labeled_lists">13.2. Labeled Lists</a></span></dt><dt><span class="section"><a href="#_question_and_answer_lists">13.3. Question and Answer Lists</a></span></dt><dt><span class="section"><a href="#_glossary_lists">13.4. Glossary Lists</a></span></dt><dt><span class="section"><a href="#_bibliography_lists">13.5. Bibliography Lists</a></span></dt><dt><span class="section"><a href="#X15">13.6. List Item Continuation</a></span></dt><dt><span class="section"><a href="#X29">13.7. List Block</a></span></dt></dl></dd><dt><span class="section"><a href="#_footnotes">14. Footnotes</a></span></dt><dt><span class="section"><a href="#_indexes">15. Indexes</a></span></dt><dt><span class="section"><a href="#_callouts">16. Callouts</a></span></dt><dd><dl><dt><span class="section"><a href="#_implementation_notes">16.1. Implementation Notes</a></span></dt><dt><span class="section"><a href="#_including_callouts_in_included_code">16.2. Including callouts in included code</a></span></dt></dl></dd><dt><span class="section"><a href="#_macros">17. Macros</a></span></dt><dd><dl><dt><span class="section"><a href="#_inline_macros">17.1. Inline Macros</a></span></dt><dt><span class="section"><a href="#_block_macros">17.2. Block Macros</a></span></dt><dt><span class="section"><a href="#_system_macros">17.3. System Macros</a></span></dt><dt><span class="section"><a href="#X77">17.4. Passthrough macros</a></span></dt><dt><span class="section"><a href="#_macro_definitions">17.5. Macro Definitions</a></span></dt></dl></dd><dt><span class="section"><a href="#_tables">18. Tables</a></span></dt><dd><dl><dt><span class="section"><a href="#_example_tables">18.1. Example tables</a></span></dt><dt><span class="section"><a href="#X68">18.2. Table input data formats</a></span></dt><dt><span class="section"><a href="#X69">18.3. Table attributes</a></span></dt><dt><span class="section"><a href="#X70">18.4. Column Specifiers</a></span></dt><dt><span class="section"><a href="#X71">18.5. Table styles</a></span></dt><dt><span class="section"><a href="#X72">18.6. Markup attributes</a></span></dt><dt><span class="section"><a href="#_nested_tables">18.7. Nested tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X1">19. Manpage Documents</a></span></dt><dd><dl><dt><span class="section"><a href="#_document_header">19.1. Document Header</a></span></dt><dt><span class="section"><a href="#_the_name_section">19.2. The NAME Section</a></span></dt><dt><span class="section"><a href="#_the_synopsis_section">19.3. The SYNOPSIS Section</a></span></dt><dt><span class="section"><a href="#_refmiscinfo_attributes">19.4. refmiscinfo attributes</a></span></dt></dl></dd><dt><span class="section"><a href="#X78">20. Mathematical Formulas</a></span></dt><dd><dl><dt><span class="section"><a href="#_latex_math">20.1. LaTeX Math</a></span></dt><dt><span class="section"><a href="#_asciimathml">20.2. ASCIIMathML</a></span></dt><dt><span class="section"><a href="#_latexmathml">20.3. LaTeXMathML</a></span></dt><dt><span class="section"><a href="#_mathml">20.4. MathML</a></span></dt></dl></dd><dt><span class="section"><a href="#X7">21. Configuration Files</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuration_file_format">21.1. Configuration File Format</a></span></dt><dt><span class="section"><a href="#_miscellaneous_section">21.2. Miscellaneous section</a></span></dt><dt><span class="section"><a href="#_titles_section">21.3. Titles section</a></span></dt><dt><span class="section"><a href="#_tags_section">21.4. Tags section</a></span></dt><dt><span class="section"><a href="#_attributes_section">21.5. Attributes section</a></span></dt><dt><span class="section"><a href="#_special_characters_section">21.6. Special Characters section</a></span></dt><dt><span class="section"><a href="#_quoted_text_section">21.7. Quoted Text section</a></span></dt><dt><span class="section"><a href="#_special_words_section">21.8. Special Words section</a></span></dt><dt><span class="section"><a href="#X10">21.9. Replacements section</a></span></dt><dt><span class="section"><a href="#_markup_template_sections">21.10. Markup Template Sections</a></span></dt><dt><span class="section"><a href="#X27">21.11. Configuration File Names and Locations</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_attributes">22. Document Attributes</a></span></dt><dt><span class="section"><a href="#X18">23. Attribute Entries</a></span></dt><dd><dl><dt><span class="section"><a href="#_setting_configuration_entries">23.1. Setting configuration entries</a></span></dt></dl></dd><dt><span class="section"><a href="#X21">24. Attribute Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#X75">24.1. Options attribute</a></span></dt><dt><span class="section"><a href="#_macro_attribute_lists">24.2. Macro Attribute lists</a></span></dt><dt><span class="section"><a href="#_attributelist_element">24.3. AttributeList Element</a></span></dt></dl></dd><dt><span class="section"><a href="#_attribute_references">25. Attribute References</a></span></dt><dd><dl><dt><span class="section"><a href="#_simple_attributes_references">25.1. Simple Attributes References</a></span></dt><dt><span class="section"><a href="#_conditional_attribute_references">25.2. Conditional Attribute References</a></span></dt><dt><span class="section"><a href="#X24">25.3. System Attribute References</a></span></dt></dl></dd><dt><span class="section"><a href="#X60">26. Intrinsic Attributes</a></span></dt><dt><span class="section"><a href="#X73">27. Block Element Definitions</a></span></dt><dd><dl><dt><span class="section"><a href="#X23">27.1. Styles</a></span></dt><dt><span class="section"><a href="#_paragraphs_2">27.2. Paragraphs</a></span></dt><dt><span class="section"><a href="#_delimited_blocks_2">27.3. Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_lists">27.4. Lists</a></span></dt><dt><span class="section"><a href="#_tables_2">27.5. Tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X59">28. Filters</a></span></dt><dd><dl><dt><span class="section"><a href="#_filter_search_paths">28.1. Filter Search Paths</a></span></dt><dt><span class="section"><a href="#_filter_configuration_files">28.2. Filter Configuration Files</a></span></dt><dt><span class="section"><a href="#X56">28.3. Code Filter</a></span></dt><dt><span class="section"><a href="#X57">28.4. Source Code Highlighter Filter</a></span></dt><dt><span class="section"><a href="#X58">28.5. Music Filter</a></span></dt></dl></dd><dt><span class="section"><a href="#X12">29. Converting DocBook to other file formats</a></span></dt><dd><dl><dt><span class="section"><a href="#X43">29.1. a2x Toolchain Wrapper</a></span></dt><dt><span class="section"><a href="#_html_generation">29.2. HTML generation</a></span></dt><dt><span class="section"><a href="#_pdf_generation">29.3. PDF generation</a></span></dt><dt><span class="section"><a href="#_html_help_generation">29.4. HTML Help generation</a></span></dt><dt><span class="section"><a href="#_toolchain_components_summary">29.5. Toolchain components summary</a></span></dt><dt><span class="section"><a href="#X67">29.6. AsciiDoc dblatex configuration files</a></span></dt><dt><span class="section"><a href="#_asciidoc_docbook_xsl_stylesheets_drivers">29.7. AsciiDoc DocBook XSL Stylesheets drivers</a></span></dt></dl></dd><dt><span class="section"><a href="#_generating_plain_text_files">30. Generating Plain Text Files</a></span></dt><dt><span class="section"><a href="#_xml_and_character_sets">31. XML and Character Sets</a></span></dt><dd><dl><dt><span class="section"><a href="#_pdf_fonts">31.1. PDF Fonts</a></span></dt></dl></dd><dt><span class="section"><a href="#X36">32. Help Commands</a></span></dt><dd><dl><dt><span class="section"><a href="#_customizing_help">32.1. Customizing Help</a></span></dt></dl></dd><dt><span class="section"><a href="#_tips_and_tricks">33. Tips and Tricks</a></span></dt><dd><dl><dt><span class="section"><a href="#_know_your_editor">33.1. Know Your Editor</a></span></dt><dt><span class="section"><a href="#X20">33.2. Vim Commands for Formatting AsciiDoc</a></span></dt><dt><span class="section"><a href="#_troubleshooting">33.3. Troubleshooting</a></span></dt><dt><span class="section"><a href="#_gotchas">33.4. Gotchas</a></span></dt><dt><span class="section"><a href="#_combining_separate_documents">33.5. Combining separate documents</a></span></dt><dt><span class="section"><a href="#_processing_document_sections_separately">33.6. Processing document sections separately</a></span></dt><dt><span class="section"><a href="#_processing_document_snippets">33.7. Processing document snippets</a></span></dt><dt><span class="section"><a href="#_badges_in_html_page_footers">33.8. Badges in HTML page footers</a></span></dt><dt><span class="section"><a href="#_pretty_printing_asciidoc_output">33.9. Pretty printing AsciiDoc output</a></span></dt><dt><span class="section"><a href="#_supporting_minor_docbook_dtd_variations">33.10. Supporting minor DocBook DTD variations</a></span></dt><dt><span class="section"><a href="#_shipping_stand_alone_asciidoc_source">33.11. Shipping stand-alone AsciiDoc source</a></span></dt><dt><span class="section"><a href="#_inserting_blank_space">33.12. Inserting blank space</a></span></dt><dt><span class="section"><a href="#_closing_open_sections">33.13. Closing open sections</a></span></dt><dt><span class="section"><a href="#_validating_output_files">33.14. Validating output files</a></span></dt></dl></dd><dt><span class="glossary"><a href="#_glossary">Glossary</a></span></dt><dt><span class="appendix"><a href="#_migration_notes">A. Migration Notes</a></span></dt><dd><dl><dt><span class="section"><a href="#X53">A.1. Version 7 to version 8</a></span></dt></dl></dd><dt><span class="appendix"><a href="#X38">B. Packager Notes</a></span></dt><dt><span class="appendix"><a href="#X39">C. AsciiDoc Safe Mode</a></span></dt><dt><span class="appendix"><a href="#_using_asciidoc_with_non_english_languages">D. Using AsciiDoc with non-English Languages</a></span></dt><dt><span class="appendix"><a href="#_vim_syntax_highlighter">E. Vim Syntax Highlighter</a></span></dt><dd><dl><dt><span class="section"><a href="#_limitations">E.1. Limitations</a></span></dt></dl></dd><dt><span class="appendix"><a href="#X74">F. Attribute Options</a></span></dt></dl></div><p><span class="emphasis"><em>AsciiDoc</em></span> is a text document format for writing short documents,
|
|
3
3
|
articles, books and UNIX man pages. <span class="emphasis"><em>AsciiDoc</em></span> files can be translated
|
|
4
4
|
to HTML and DocBook markups using the <code class="literal">asciidoc(1)</code> command. <span class="emphasis"><em>AsciiDoc</em></span>
|
|
5
5
|
is highly configurable: both the <span class="emphasis"><em>AsciiDoc</em></span> source file syntax and the
|
|
@@ -150,13 +150,13 @@ stylesheet
|
|
|
150
150
|
embedding the stylesheet specify the actual file name; if you are
|
|
151
151
|
linking CSS specify the file name relative to the directory
|
|
152
152
|
specified by the <span class="emphasis"><em>stylesdir</em></span> attribute.
|
|
153
|
-
</dd
|
|
153
|
+
</dd><dt><span class="term">
|
|
154
154
|
icons
|
|
155
155
|
</span></dt><dd>
|
|
156
156
|
Link admonition paragraph and admonition block icon images and badge
|
|
157
157
|
images. By default <span class="emphasis"><em>icons</em></span> is undefined and text is used in place of
|
|
158
158
|
icon images.
|
|
159
|
-
</dd
|
|
159
|
+
</dd><dt><span class="term">
|
|
160
160
|
iconsdir
|
|
161
161
|
</span></dt><dd>
|
|
162
162
|
The name of the directory containing linked admonition and
|
|
@@ -175,7 +175,7 @@ badges
|
|
|
175
175
|
</span></dt><dd>
|
|
176
176
|
Link badges (<span class="emphasis"><em>XHTML 1.1</em></span>, <span class="emphasis"><em>CSS</em></span> and <span class="emphasis"><em>Get Firefox!</em></span>) in document
|
|
177
177
|
footers. By default badges are omitted (<span class="emphasis"><em>badges</em></span> is undefined).
|
|
178
|
-
</dd></dl></div><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The path names of images, icons and scripts are relative to the
|
|
178
|
+
</dd></dl></div><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"><a id="X44"></a></th></tr><tr><td align="left" valign="top"><p>The path names of images, icons and scripts are relative to the
|
|
179
179
|
output document not the source document.</p></td></tr></table></div><div class="variablelist"><a id="X54"></a><dl><dt><span class="term">
|
|
180
180
|
encoding
|
|
181
181
|
</span></dt><dd><p>
|
|
@@ -231,7 +231,7 @@ Preamble, followed by zero or more document Sections.</p><p>Almost any combinati
|
|
|
231
231
|
<span class="emphasis"><em>AsciiDoc</em></span> document: documents can range from a single sentence to a
|
|
232
232
|
multi-part book.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_block_elements"></a>5.1. Block Elements</h3></div></div></div><p>Block elements consist of one or more lines of text and may contain
|
|
233
233
|
other block elements.</p><p>The <span class="emphasis"><em>AsciiDoc</em></span> block structure can be informally summarized
|
|
234
|
-
<sup>[<a id="
|
|
234
|
+
<sup>[<a id="id2528525" href="#ftn.id2528525" class="footnote">1</a>]</sup> as follows:</p><pre class="literallayout">Document ::= (Header?,Preamble?,Section*)
|
|
235
235
|
Header ::= (Title,(AuthorLine,RevisionLine?)?)
|
|
236
236
|
AuthorLine ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
|
|
237
237
|
RevisionLine ::= (Revision?,Date)
|
|
@@ -485,7 +485,7 @@ and <code class="literal">#</code> constrained quotes:</p><pre class="literallay
|
|
|
485
485
|
double-escaped (because of their similarity to the single character
|
|
486
486
|
constrained quotes) — here’s how to escape the previous example:</p><pre class="literallayout">\*\*F**ile Open...</pre></td></tr></table></div></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_superscripts_and_subscripts"></a>7.2. Superscripts and Subscripts</h3></div></div></div><p>Put ^carets on either^ side of the text to be superscripted, put
|
|
487
487
|
~tildes on either side~ of text to be subscripted. For example, the
|
|
488
|
-
following line:</p><pre class="literallayout">e
|
|
488
|
+
following line:</p><pre class="literallayout">e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
|
|
489
489
|
and ~some sub text~</pre><p>Is rendered like:</p><p>e<sup>πi</sup>+1 = 0. H<sub>2</sub>O and x<sup>10</sup>. Some <sup>super text</sup>
|
|
490
490
|
and <sub>some sub text</sub></p><p>Superscripts and subscripts are implemented as <a class="link" href="#X52" title="7.1.1. Constrained and Unconstrained Quotes">unconstrained quotes</a> so they can be escaped with a leading backslash and prefixed
|
|
491
491
|
with with an attribute list.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_line_breaks"></a>7.3. Line Breaks</h3></div></div></div><p>A plus character preceded by at least one space character at the end
|
|
@@ -593,15 +593,15 @@ you are going the DocBook route then the <a class="link" href="#X43" title="29.1
|
|
|
593
593
|
and <code class="literal">--icons-dir</code> options can be used to set the appropriate XSL
|
|
594
594
|
Stylesheets parameters.</p></td></tr></table></div><p>By default the <code class="literal">asciidoc(1)</code> <code class="literal">xhtml11</code> and <code class="literal">html4</code> backends generate
|
|
595
595
|
text captions instead of icon image links. To generate links to icon
|
|
596
|
-
images define the <a class="link" href="#
|
|
597
|
-
icons</code> command-line option.</p><p>The <a class="link" href="#X44" title="
|
|
596
|
+
images define the <a class="link" href="#"><code class="literal">icons</code></a> attribute, for example using the <code class="literal">-a
|
|
597
|
+
icons</code> command-line option.</p><p>The <a class="link" href="#X44" title="Note"><code class="literal">iconsdir</code></a> attribute sets the location of linked icon
|
|
598
598
|
images.</p><p>You can override the default icon image using the <code class="literal">icon</code> attribute to
|
|
599
599
|
specify the path of the linked image. For example:</p><pre class="literallayout">[icon="./images/icons/wink.png"]
|
|
600
600
|
NOTE: What lovely war.</pre><p>Use the <code class="literal">caption</code> attribute to customize the admonition captions (not
|
|
601
601
|
applicable to <code class="literal">docbook</code> backend). The following example suppresses the
|
|
602
602
|
icon image and customizes the caption of a NOTE admonition (undefining
|
|
603
603
|
the <code class="literal">icons</code> attribute with <code class="literal">icons=None</code> is only necessary if
|
|
604
|
-
<a class="link" href="#
|
|
604
|
+
<a class="link" href="#">admonition icons</a> have been enabled):</p><pre class="literallayout">[icons=None, caption="My Special Note"]
|
|
605
605
|
NOTE: This is my special note.</pre><p>This subsection also applies to <a class="link" href="#X22" title="12.9. Admonition Blocks">Admonition Blocks</a>.</p></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_delimited_blocks"></a>12. Delimited Blocks</h2></div></div></div><p>Delimited blocks are blocks of text enveloped by leading and trailing
|
|
606
606
|
delimiter lines (normally a series of four or more repeated
|
|
607
607
|
characters). The behavior of Delimited Blocks is specified by entries
|
|
@@ -615,18 +615,18 @@ SidebarBlock: **************************
|
|
|
615
615
|
QuoteBlock: __________________________
|
|
616
616
|
ExampleBlock: ==========================
|
|
617
617
|
Filter blocks: ~~~~~~~~~~~~~~~~~~~~~~~~~~</pre><p>The <a class="link" href="#X56" title="28.3. Code Filter">code</a>, <a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">source</a> and <a class="link" href="#X58" title="28.5. Music Filter">music</a> filter blocks are
|
|
618
|
-
detailed in the <a class="link" href="#X59" title="28. Filters">Filters</a> section.</p><div class="table"><a id="
|
|
618
|
+
detailed in the <a class="link" href="#X59" title="28. Filters">Filters</a> section.</p><div class="table"><a id="id2531046"></a><p class="title"><b>Table 1. Default DelimitedBlock substitutions</b></p><div class="table-contents"><table summary="Default DelimitedBlock substitutions" cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"> </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Passthrough </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Listing </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Literal </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Sidebar </th><th style="border-bottom: 1px solid ; " align="center" valign="top">Quote</th></tr></thead><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Callouts</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Attributes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Inline Macros</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Quotes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Replacements</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Special chars</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>Special words</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="" align="center" valign="top"><p>Yes</p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_listing_blocks"></a>12.2. Listing Blocks</h3></div></div></div><p>ListingBlocks are rendered verbatim in a monospaced font, they retain
|
|
619
619
|
line and whitespace formatting and often distinguished by a background
|
|
620
620
|
or border. There is no text formatting or substitutions within Listing
|
|
621
621
|
blocks apart from Special Characters and Callouts. Listing blocks are
|
|
622
|
-
often used for code and file listings.</p><p>Here’s an example:</p><pre class="screen"
|
|
623
|
-
|
|
622
|
+
often used for code and file listings.</p><p>Here’s an example:</p><pre class="screen">--------------------------------------
|
|
623
|
+
#include <stdio.h>
|
|
624
624
|
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
625
|
+
int main() {
|
|
626
|
+
printf("Hello World!\n");
|
|
627
|
+
exit(0);
|
|
628
|
+
}
|
|
629
|
+
--------------------------------------</pre><p>Which will be rendered like:</p><pre class="screen">#include <stdio.h>
|
|
630
630
|
|
|
631
631
|
int main() {
|
|
632
632
|
printf("Hello World!\n");
|
|
@@ -645,12 +645,15 @@ bordered box to set it apart from the main text.</p><p>The sidebar body is treat
|
|
|
645
645
|
Any AsciiDoc SectionBody element (apart from
|
|
646
646
|
SidebarBlocks) can be placed inside a sidebar.
|
|
647
647
|
************************************************</pre><p>Which will be rendered like:</p><div class="sidebar"><p class="title"><b>An Example Sidebar</b></p><p>Any <span class="emphasis"><em>AsciiDoc</em></span> SectionBody element (apart from
|
|
648
|
-
SidebarBlocks) can be placed inside a sidebar.</p></div
|
|
648
|
+
SidebarBlocks) can be placed inside a sidebar.</p></div><p>Apply the <span class="emphasis"><em>abstract</em></span> style to generate an abstract, for example:</p><pre class="screen">[abstract]
|
|
649
|
+
************************************************
|
|
650
|
+
In this paper we will attempt to...
|
|
651
|
+
************************************************</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X26"></a>12.5. Comment Blocks</h3></div></div></div><p>The contents of CommentBlocks are not processed; they are useful for
|
|
649
652
|
annotations and for excluding new or outdated content that you don’t
|
|
650
653
|
want displayed. Here’s and example:</p><pre class="screen">//////////////////////////////////////////
|
|
651
654
|
CommentBlock contents are not processed by
|
|
652
655
|
asciidoc(1).
|
|
653
|
-
//////////////////////////////////////////</pre><p>See also <a class="link" href="#X25" title="17.2.3. Comment Lines">Comment Lines</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X76"></a>12.6. Passthrough Blocks</h3></div></div></div><p>By default the block contents is subject to attribute and macro
|
|
656
|
+
//////////////////////////////////////////</pre><p>See also <a class="link" href="#X25" title="17.2.3. Comment Lines">Comment Lines</a>.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>System macros are executed inside comment blocks.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X76"></a>12.6. Passthrough Blocks</h3></div></div></div><p>By default the block contents is subject to attribute and macro
|
|
654
657
|
substitution, no other markup is generated. PassthroughBlock content
|
|
655
658
|
will often be backend specific. Here’s an example:</p><pre class="screen">++++++++++++++++++++++++++++++++++++++
|
|
656
659
|
<table border="1"><tr>
|
|
@@ -701,7 +704,7 @@ inside an example block. For example:</p><pre class="screen">.An example
|
|
|
701
704
|
=====================================================================
|
|
702
705
|
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
703
706
|
adolescens.
|
|
704
|
-
=====================================================================</pre><p>Renders:</p><div class="example"><a id="
|
|
707
|
+
=====================================================================</pre><p>Renders:</p><div class="example"><a id="id2531785"></a><p class="title"><b>Example 1. An example</b></p><div class="example-contents"><p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
705
708
|
adolescens.</p></div></div><br class="example-break" /><p>A title prefix that can be inserted with the <code class="literal">caption</code> attribute
|
|
706
709
|
(<code class="literal">xhtml11</code> and <code class="literal">html4</code> backends). For example:</p><pre class="screen">[caption="Example 1: "]
|
|
707
710
|
.An example with a custom caption
|
|
@@ -769,12 +772,29 @@ You need to use <a class="link" href="#X15" title="13.6. List Item Continua
|
|
|
769
772
|
accompanied by an <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a>.
|
|
770
773
|
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_bulleted_and_numbered_lists"></a>13.1. Bulleted and Numbered Lists</h3></div></div></div><p>Bulleted list items start with a dash or an asterisk followed by a
|
|
771
774
|
space or tab character. Bulleted list syntaxes are:</p><pre class="literallayout">- List item.
|
|
772
|
-
* List item.</pre><p>
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
775
|
+
* List item.</pre><p>There are two numbered list item syntaxes:</p><div class="orderedlist"><ol type="1"><li>
|
|
776
|
+
List items beginning with a single period followed by a space. The
|
|
777
|
+
period can be preceded by an optional decimal number. The default
|
|
778
|
+
numbering style is arabic (decimal).
|
|
779
|
+
</li><li><p>
|
|
780
|
+
List items beginning with two periods followed by a space. An alpha
|
|
781
|
+
character or a roman number (upper or lower case) can optionally be
|
|
782
|
+
used in place of the first period:
|
|
783
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
784
|
+
An attempt is made to set the number style based on number style
|
|
785
|
+
of the first list item.
|
|
786
|
+
</li><li>
|
|
787
|
+
The default numbering style is lowercase alpha.
|
|
788
|
+
</li></ul></div></li></ol></div><p>You can use the <span class="emphasis"><em>style</em></span> attribute to specify an alternative numbering
|
|
789
|
+
style. The numbered list style can be set to one of the following
|
|
790
|
+
values: <span class="emphasis"><em>arabic</em></span>, <span class="emphasis"><em>loweralpha</em></span>, <span class="emphasis"><em>upperalpha</em></span>, <span class="emphasis"><em>lowerroman</em></span>,
|
|
791
|
+
<span class="emphasis"><em>upperroman</em></span>.</p><p>Examples of numbered list items:</p><pre class="literallayout">. Arabic (decimal) numbered list item.
|
|
792
|
+
1. Arabic (decimal) numbered list item.
|
|
793
|
+
.. Lower case letter numbered list item.
|
|
794
|
+
a. Lower case letter numbered list item.
|
|
795
|
+
A. Upper case letter numbered list item.
|
|
796
|
+
iii. Lower case roman numbered list item.
|
|
797
|
+
IX. Upper case roman numbered list item.</pre><p>Here are some examples of bulleted and numbered lists:</p><pre class="screen">- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
778
798
|
* Fusce euismod commodo velit.
|
|
779
799
|
* Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
780
800
|
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
@@ -784,6 +804,7 @@ a. Lowercase letter numbered list item with optional numbering.</pre><p>Here are
|
|
|
784
804
|
- Nulla porttitor vulputate libero.
|
|
785
805
|
. Fusce euismod commodo velit.
|
|
786
806
|
. Vivamus fringilla mi eu lacus.
|
|
807
|
+
[upperroman]
|
|
787
808
|
.. Fusce euismod commodo velit.
|
|
788
809
|
.. Vivamus fringilla mi eu lacus.
|
|
789
810
|
. Donec eget arcu bibendum nunc consequat lobortis.
|
|
@@ -793,6 +814,8 @@ a. Lowercase letter numbered list item with optional numbering.</pre><p>Here are
|
|
|
793
814
|
b. Vivamus fringilla mi eu lacus.
|
|
794
815
|
c. Donec eget arcu bibendum nunc consequat lobortis.
|
|
795
816
|
2. Vivamus fringilla mi eu lacus.
|
|
817
|
+
.. Fusce euismod commodo velit.
|
|
818
|
+
.. Vivamus fringilla mi eu lacus.
|
|
796
819
|
3. Donec eget arcu bibendum nunc consequat lobortis.
|
|
797
820
|
4. Nam fermentum mattis ante.</pre><p>Which render as:</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
798
821
|
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
@@ -812,7 +835,7 @@ Nulla porttitor vulputate libero.
|
|
|
812
835
|
Fusce euismod commodo velit.
|
|
813
836
|
</li><li><p>
|
|
814
837
|
Vivamus fringilla mi eu lacus.
|
|
815
|
-
</p><div class="orderedlist"><ol type="
|
|
838
|
+
</p><div class="orderedlist"><ol type="I"><li>
|
|
816
839
|
Fusce euismod commodo velit.
|
|
817
840
|
</li><li>
|
|
818
841
|
Vivamus fringilla mi eu lacus.
|
|
@@ -828,9 +851,13 @@ Fusce euismod commodo velit.
|
|
|
828
851
|
Vivamus fringilla mi eu lacus.
|
|
829
852
|
</li><li>
|
|
830
853
|
Donec eget arcu bibendum nunc consequat lobortis.
|
|
831
|
-
</li></ol></div></li><li>
|
|
854
|
+
</li></ol></div></li><li><p>
|
|
832
855
|
Vivamus fringilla mi eu lacus.
|
|
856
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
857
|
+
Fusce euismod commodo velit.
|
|
833
858
|
</li><li>
|
|
859
|
+
Vivamus fringilla mi eu lacus.
|
|
860
|
+
</li></ol></div></li><li>
|
|
834
861
|
Donec eget arcu bibendum nunc consequat lobortis.
|
|
835
862
|
</li><li>
|
|
836
863
|
Nam fermentum mattis ante.
|
|
@@ -945,7 +972,7 @@ Current PDF toolchains do not make a good job of determining
|
|
|
945
972
|
</li><li>
|
|
946
973
|
If you are generating DocBook markup then horizontal labeled lists
|
|
947
974
|
should not be nested because the <span class="emphasis"><em>DocBook XML V4.2</em></span> DTD does not
|
|
948
|
-
permit nested informal tables (although <a class="link" href="#
|
|
975
|
+
permit nested informal tables (although <a class="link" href="#">DocBook XSL Stylesheets</a> and <a class="link" href="#">dblatex</a> process them correctly).
|
|
949
976
|
</li><li>
|
|
950
977
|
The label width can be set as a percentage of the total width by
|
|
951
978
|
setting the <span class="emphasis"><em>width</em></span> attribute e.g. <code class="literal">width="10%"</code>
|
|
@@ -954,15 +981,15 @@ DocBook question and answer (Q&A) lists. Example:</p><pre class="screen">[qa
|
|
|
954
981
|
Question one::
|
|
955
982
|
Answer one.
|
|
956
983
|
Question two::
|
|
957
|
-
Answer two.</pre><p>Renders:</p><div class="qandaset"><dl><dt>13.3.1. <a href="#
|
|
984
|
+
Answer two.</pre><p>Renders:</p><div class="qandaset"><dl><dt>13.3.1. <a href="#id2532998">
|
|
958
985
|
Question one
|
|
959
|
-
</a></dt><dt>13.3.2. <a href="#
|
|
986
|
+
</a></dt><dt>13.3.2. <a href="#id2533015">
|
|
960
987
|
Question two
|
|
961
|
-
</a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%" /><tbody><tr class="question"><td align="left" valign="top"><a id="
|
|
988
|
+
</a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%" /><tbody><tr class="question"><td align="left" valign="top"><a id="id2532998"></a><a id="id2533000"></a><p><b>13.3.1.</b></p></td><td align="left" valign="top"><p>
|
|
962
989
|
Question one
|
|
963
990
|
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
|
|
964
991
|
Answer one.
|
|
965
|
-
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="
|
|
992
|
+
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="id2533015"></a><a id="id2533017"></a><p><b>13.3.2.</b></p></td><td align="left" valign="top"><p>
|
|
966
993
|
Question two
|
|
967
994
|
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
|
|
968
995
|
Answer two.
|
|
@@ -1077,7 +1104,7 @@ The <code class="literal">footnoteref</code> macro has two forms: if the text is
|
|
|
1077
1104
|
The footnote text can span multiple lines.
|
|
1078
1105
|
</li></ul></div><p>Example footnote:</p><pre class="literallayout">A footnote footnote:[An example footnote.];
|
|
1079
1106
|
a second footnote with a reference ID footnoteref:[note2,Second footnote.];
|
|
1080
|
-
finally a reference to the second footnote footnoteref:[note2].</pre><p>Which renders:</p><p>A footnote <sup>[<a id="
|
|
1107
|
+
finally a reference to the second footnote footnoteref:[note2].</pre><p>Which renders:</p><p>A footnote <sup>[<a id="id2533619" href="#ftn.id2533619" class="footnote">2</a>]</sup>;
|
|
1081
1108
|
a second footnote with a reference ID <sup>[<a id="note2" href="#ftn.note2" class="footnote">3</a>]</sup>;
|
|
1082
1109
|
finally a reference to the second footnote <sup>[<a href="#ftn.note2" class="footnoteref">3</a>]</sup>.</p><p>Footnotes are primarily useful when generating DocBook output — DocBook conversion programs render footnote outside the primary text
|
|
1083
1110
|
flow.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_indexes"></a>15. Indexes</h2></div></div></div><p>The shipped <span class="emphasis"><em>AsciiDoc</em></span> configuration includes the inline macros for
|
|
@@ -1125,7 +1152,7 @@ example:</p><pre class="screen"> .MS-DOS directory listing
|
|
|
1125
1152
|
|
|
1126
1153
|
<1> This directory holds MS-DOS.
|
|
1127
1154
|
<2> System startup code for DOS.
|
|
1128
|
-
<3> Some sort of Windows 3.1 hack.</pre><p>Which renders:</p><div class="example"><a id="
|
|
1155
|
+
<3> Some sort of Windows 3.1 hack.</pre><p>Which renders:</p><div class="example"><a id="id2533843"></a><p class="title"><b>Example 2. MS-DOS directory listing</b></p><div class="example-contents"><pre class="screen">10/17/97 9:04 <DIR> bin
|
|
1129
1156
|
10/16/97 14:11 <DIR> DOS <a id="CO1-1"></a><img src="./images/icons/callouts/1.png" alt="1" border="0" />
|
|
1130
1157
|
10/16/97 14:40 <DIR> Program Files
|
|
1131
1158
|
10/16/97 14:46 <DIR> TEMP
|
|
@@ -1183,12 +1210,12 @@ substitution — it is a space delimited list of callout IDs that refer
|
|
|
1183
1210
|
to the explanatory list item.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_including_callouts_in_included_code"></a>16.2. Including callouts in included code</h3></div></div></div><p>You can annotate working code examples with callouts — just remember
|
|
1184
1211
|
to put the callouts inside source code comments. This example displays
|
|
1185
1212
|
the <code class="literal">test.py</code> source file (containing a single callout) using the
|
|
1186
|
-
<a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>:</p><div class="example"><a id="
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1213
|
+
<a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>:</p><div class="example"><a id="id2534180"></a><p class="title"><b>Example 3. AsciiDoc source</b></p><div class="example-contents"><pre class="screen">[source,python]
|
|
1214
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1215
|
+
include::test.py[]
|
|
1216
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1190
1217
|
|
|
1191
|
-
|
|
1218
|
+
<1> Print statement.</pre></div></div><br class="example-break" /><div class="example"><a id="id2534196"></a><p class="title"><b>Example 4. Included <code class="literal">test.py</code> source</b></p><div class="example-contents"><pre class="screen">print 'Hello World!' # <1></pre></div></div><br class="example-break" /></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_macros"></a>17. Macros</h2></div></div></div><p>Macros are a mechanism for substituting parametrized text into output
|
|
1192
1219
|
documents.</p><p>Macros have a <span class="emphasis"><em>name</em></span>, a single <span class="emphasis"><em>target</em></span> argument and an <span class="emphasis"><em>attribute
|
|
1193
1220
|
list</em></span>. The usual syntax is <code class="literal"><name>:<target>[<attrlist>]</code> (for
|
|
1194
1221
|
inline macros) and <code class="literal"><name>::<target>[<attrlist>]</code> (for block
|
|
@@ -1330,9 +1357,9 @@ but it is supported by Internet Explorer 8 Beta 1.</p></td></tr></table></div></
|
|
|
1330
1357
|
left margin are treated as comments and are stripped from the output.
|
|
1331
1358
|
Comment lines have been implemented as a block macro and are only
|
|
1332
1359
|
valid in a block context — they are not treated as comments inside
|
|
1333
|
-
paragraphs or delimited blocks. Example comment line:</p><pre class="literallayout">// This is a comment.</pre><p>See also <a class="link" href="#X26" title="12.5. Comment Blocks">Comment Blocks</a>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_system_macros"></a>17.3. System Macros</h3></div></div></div><p>System macros are block macros that perform a predefined task
|
|
1360
|
+
paragraphs or delimited blocks. Example comment line:</p><pre class="literallayout">// This is a comment.</pre><p>See also <a class="link" href="#X26" title="12.5. Comment Blocks">Comment Blocks</a>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_system_macros"></a>17.3. System Macros</h3></div></div></div><p>System macros are block macros that perform a predefined task and are
|
|
1334
1361
|
hardwired into the <code class="literal">asciidoc(1)</code> program.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1335
|
-
You can
|
|
1362
|
+
You can escape system macros with a leading backslash character
|
|
1336
1363
|
(as you can with other macros).
|
|
1337
1364
|
</li><li>
|
|
1338
1365
|
The syntax and tasks performed by system macros is built into
|
|
@@ -1346,7 +1373,7 @@ contents of <code class="literal">include1</code> files are not subject to tab e
|
|
|
1346
1373
|
system macro processing nor are attribute or lower priority
|
|
1347
1374
|
substitutions performed. The <code class="literal">include1</code> macro’s main use is to include
|
|
1348
1375
|
verbatim embedded CSS or scripts into configuration file headers.
|
|
1349
|
-
Example:</p><pre class="screen">
|
|
1376
|
+
Example:</p><pre class="screen">include::chapter1.txt[tabsize=4]</pre><div class="itemizedlist"><p class="title"><b>Include macro behavior</b></p><ul type="disc"><li>
|
|
1350
1377
|
If the included file name is specified with a relative path then the
|
|
1351
1378
|
path is relative to the location of the referring document.
|
|
1352
1379
|
</li><li>
|
|
@@ -1475,7 +1502,7 @@ a markup template. If <code class="literal"><name></code> is omitted then
|
|
|
1475
1502
|
regular expression match group named <span class="emphasis"><em>name</em></span>. The optional
|
|
1476
1503
|
<code class="literal">[<subslist]</code> is a comma-separated list of substitution names enclosed
|
|
1477
1504
|
in <code class="literal">[]</code> brackets, it sets the default substitutions for passthrough
|
|
1478
|
-
text.</p><p><b>Pattern named groups. </b>The following named groups can be used in macro <code class="literal"><pattern></code> regular
|
|
1505
|
+
text, if omitted then no passthrough substitutions are performed.</p><p><b>Pattern named groups. </b>The following named groups can be used in macro <code class="literal"><pattern></code> regular
|
|
1479
1506
|
expressions and are available as markup template attributes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1480
1507
|
name
|
|
1481
1508
|
</span></dt><dd>
|
|
@@ -1523,8 +1550,8 @@ All table meta-data is contained specified in the table’s attribute
|
|
|
1523
1550
|
There is no provision for cells to span multiple columns.
|
|
1524
1551
|
</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
|
|
1525
1552
|
with column spanning and table nesting) are often considered very
|
|
1526
|
-
important.
|
|
1527
|
-
|
|
1553
|
+
important. The reality is that tables are seldom used, even in
|
|
1554
|
+
technical documentation.</p><p>Try this exercise: thumb through your library of technical books,
|
|
1528
1555
|
you’ll be surprised just how seldom tables are actually used, even
|
|
1529
1556
|
less seldom are tables containing block elements such as paragraphs or
|
|
1530
1557
|
lists. This is no accident, like figures, tables are outside the
|
|
@@ -1534,7 +1561,7 @@ displaying column oriented tabular data.</p></div><div class="section" lang="en"
|
|
|
1534
1561
|
|1 |2 |A
|
|
1535
1562
|
|3 |4 |B
|
|
1536
1563
|
|5 |6 |C
|
|
1537
|
-
|=======</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_columns_formatted_with_strong_monospaced_and_emphasis_styles"></a>18.1.2. Columns formatted with strong, monospaced and emphasis styles</h4></div></div></div><div class="table"><a id="
|
|
1564
|
+
|=======</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_columns_formatted_with_strong_monospaced_and_emphasis_styles"></a>18.1.2. Columns formatted with strong, monospaced and emphasis styles</h4></div></div></div><div class="table"><a id="id2536713"></a><p class="title"><b>Table 2. An example table</b></p><div class="table-contents"><table summary="An example table" cellpadding="4px" style="border: none;"><colgroup><col align="right" /><col align="center" /><col align="left" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"> </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Column 2</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Column 3</th></tr></thead><tfoot valign="top"><tr><th style="border-right: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>footer 1</strong></span></p></th><th style="border-right: 1px solid ; " align="center" valign="top"><p><code class="literal">footer 2</code></p></th><th style="" align="left" valign="top"><p><span class="emphasis"><em>footer 3</em></span></p></th></tr></tfoot><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>1</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 1</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 1</em></span></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>2</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 2</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 2</em></span></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>3</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 3</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 3</em></span></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>4</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 4</code></p></td><td style="border-bottom: 1px solid ; " 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><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">.An example table
|
|
1538
1565
|
[width="50%",cols=">s,^m,e",frame="none",options="header,footer"]
|
|
1539
1566
|
|==========================
|
|
1540
1567
|
| |Column 2|Column 3
|
|
@@ -1545,7 +1572,7 @@ displaying column oriented tabular data.</p></div><div class="section" lang="en"
|
|
|
1545
1572
|
|footer 1|footer 2|footer 3
|
|
1546
1573
|
|==========================</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_horizontal_and_vertical_source_data"></a>18.1.3. Horizontal and vertical source data</h4></div></div></div><p>Short cells can be entered horizontally, longer cells vertically. The
|
|
1547
1574
|
default behavior is to strip leading and trailing blank lines within a
|
|
1548
|
-
cell. These characteristics aid readability and data entry.</p><div class="table"><a id="
|
|
1575
|
+
cell. These characteristics aid readability and data entry.</p><div class="table"><a id="id2536932"></a><p class="title"><b>Table 3. Windtrainer workouts</b></p><div class="table-contents"><table summary="Windtrainer workouts" cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="left" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Date </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Duration </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Avg HR </th><th style="border-bottom: 1px solid ; " align="left" valign="top">Notes</th></tr></thead><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>22-Aug-08</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>10:24</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>157</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Worked out MSHR (max sustainable heart rate) by going hard
|
|
1549
1576
|
for this interval.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>22-Aug-08</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>23:03</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>152</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Back-to-back with previous interval.</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>24-Aug-08</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>40:00</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>145</p></td><td style="" align="left" valign="top"><p>Moderately hard interspersed with 3x 3min intervals (2min
|
|
1550
1577
|
hard + 1min really hard taking the HR up to 160).</p></td></tr></tbody></table></div></div><br class="table-break" /><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">.Windtrainer workouts
|
|
1551
1578
|
[width="80%",cols="3,^2,^2,10",options="header"]
|
|
@@ -1572,11 +1599,11 @@ Madrid</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"
|
|
|
1572
1599
|
Marseille</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>91.24.45.40</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BOTTM</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Bottom-Dollar Markets</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Elizabeth Lincoln</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>23 Tsawassen Blvd.
|
|
1573
1600
|
Tsawassen</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>(604) 555-4729</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BSBEV</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>B’s Beverages</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Victoria Ashworth</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Fauntleroy Circus
|
|
1574
1601
|
London</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>(171) 555-1212</p></td></tr><tr><td style="border-right: 1px solid ; " align="center" valign="top"><p>CACTU</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>Cactus Comidas para llevar</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>Patricio Simpson</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>Cerrito 333
|
|
1575
|
-
Buenos Aires</p></td><td style="" align="left" valign="top"><p>(1) 135-5555</p></td></tr></tbody></table></div><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
|
-
|
|
1579
|
-
|
|
1602
|
+
Buenos Aires</p></td><td style="" align="left" valign="top"><p>(1) 135-5555</p></td></tr></tbody></table></div><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">[format="csv",cols="^1,4*2",options="header"]
|
|
1603
|
+
|===================================================
|
|
1604
|
+
ID,Customer Name,Contact Name,Customer Address,Phone
|
|
1605
|
+
include::customers.csv[]
|
|
1606
|
+
|===================================================</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X68"></a>18.2. Table input data formats</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> 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
|
|
1580
1607
|
default <span class="emphasis"><em>AsciiDoc</em></span> table format is <span class="emphasis"><em>psv</em></span>.</p><p><span class="emphasis"><em>csv</em></span> is the quasi-standard row oriented <span class="emphasis"><em>Comma Separated Values
|
|
1581
1608
|
(CSV)</em></span> format commonly used to import and export spreadsheet and
|
|
1582
1609
|
database data.</p><p><span class="emphasis"><em>AsciiDoc</em></span> <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
|
|
@@ -1801,11 +1828,11 @@ source file:</p><pre class="literallayout">:man source: AsciiDoc
|
|
|
1801
1828
|
can use the following math markups:</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The <span class="emphasis"><em>latexmath</em></span> macro used to include <span class="emphasis"><em>LaTeX Math</em></span> in DocBook
|
|
1802
1829
|
outputs is not the same as the <span class="emphasis"><em>latexmath</em></span> macro used to include
|
|
1803
1830
|
<span class="emphasis"><em>LaTeX MathML</em></span> in XHTML outputs. <span class="emphasis"><em>LaTeX Math</em></span> applies to DocBook
|
|
1804
|
-
outputs that are processed by <a class="link" href="#
|
|
1831
|
+
outputs that are processed by <a class="link" href="#">dblatex</a> and is normally used to
|
|
1805
1832
|
generate PDF files. <span class="emphasis"><em>LaTeXMathML</em></span> is very much a subset of <span class="emphasis"><em>LaTeX
|
|
1806
1833
|
Math</em></span> and applies to XHTML documents.</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_latex_math"></a>20.1. 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
|
|
1807
1834
|
math</a> can be included in documents that are processed by
|
|
1808
|
-
<a class="link" href="#
|
|
1835
|
+
<a class="link" href="#">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"><span class="emphasis"><em>AsciiDoc</em></span>
|
|
1809
1836
|
website</a> or the 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>20.2. ASCIIMathML</h3></div></div></div><p><a class="ulink" href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html" target="_top">ASCIIMathML</a>
|
|
1810
1837
|
formulas can be included in XHTML documents generated using the
|
|
1811
1838
|
<span class="emphasis"><em>xhtml11</em></span> backend. To enable ASCIIMathML support you must define the
|
|
@@ -2217,7 +2244,7 @@ Here are some more attribute entry examples:
|
|
|
2217
2244
|
{date}, {revision}, {keywords}, {revisionhistory}</pre><p>The preceding example is equivalent to the standard <span class="emphasis"><em>AsciiDoc</em></span> two line
|
|
2218
2245
|
document header. Actually it’s a little bit different with the
|
|
2219
2246
|
addition of the <code class="literal">{keywords}</code> and <code class="literal">{revisionhistory}</code> attributes
|
|
2220
|
-
<sup>[<a id="
|
|
2247
|
+
<sup>[<a id="id2541424" href="#ftn.id2541424" class="footnote">4</a>]</sup>.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_setting_configuration_entries"></a>23.1. Setting configuration entries</h3></div></div></div><p>A variant of the Attribute Entry syntax allows configuration file
|
|
2221
2248
|
entries to be set from within an <span class="emphasis"><em>AsciiDoc</em></span> document:</p><pre class="literallayout">:<section_name>.<entry_name>: <entry_value></pre><p>Where <code class="literal"><section_name></code> is the configuration section name,
|
|
2222
2249
|
<code class="literal"><entry_name></code> is the name of the entry and <code class="literal"><entry_value></code> is the
|
|
2223
2250
|
optional entry value. This example sets the default labeled list style
|
|
@@ -2267,7 +2294,8 @@ List attributes take precedence over existing attributes.
|
|
|
2267
2294
|
List attributes can only be referenced in configuration file markup
|
|
2268
2295
|
templates and tags, they are not available inside the document.
|
|
2269
2296
|
</li><li>
|
|
2270
|
-
Attribute references are allowed inside attribute lists
|
|
2297
|
+
Attribute references are allowed inside attribute lists — this is
|
|
2298
|
+
the only substitution performed on attribute lists.
|
|
2271
2299
|
</li><li>
|
|
2272
2300
|
Setting a named attribute to <code class="literal">None</code> undefines the attribute.
|
|
2273
2301
|
</li><li>
|
|
@@ -2299,7 +2327,8 @@ empty but it cannot be omitted. List entries are used to pass
|
|
|
2299
2327
|
attribute values to macro markup templates.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_attributelist_element"></a>24.3. AttributeList Element</h3></div></div></div><p>An <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a> on a line by itself constitutes an
|
|
2300
2328
|
<span class="emphasis"><em>AttributeList</em></span> block element, its attributes apply to the following
|
|
2301
2329
|
block element. The list attributes are passed to the next block
|
|
2302
|
-
element for markup template substitution
|
|
2330
|
+
element for markup template substitution. Often the first list
|
|
2331
|
+
parameter is used to specify the element’s <a class="link" href="#X23" title="27.1. Styles">style</a>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_attribute_references"></a>25. Attribute References</h2></div></div></div><p>An attribute references is an attribute name (possibly followed by an
|
|
2303
2332
|
additional parameters) enclosed in braces. When an attribute
|
|
2304
2333
|
reference is encountered it is evaluated and replaced by its
|
|
2305
2334
|
corresponding text value. If the attribute is undefined the line
|
|
@@ -2492,7 +2521,7 @@ See also the <a class="link" href="#X33" title="4.2. xhtml11">xhtml11</a> s
|
|
|
2492
2521
|
The entries that translate to blank strings are designed to be used
|
|
2493
2522
|
for conditional text inclusion. You can also use the <code class="literal">ifdef</code>,
|
|
2494
2523
|
<code class="literal">ifndef</code> and <code class="literal">endif</code> System macros for conditional inclusion.
|
|
2495
|
-
<sup>[<a id="
|
|
2524
|
+
<sup>[<a id="id2543097" href="#ftn.id2543097" class="footnote">5</a>]</sup>
|
|
2496
2525
|
</li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X73"></a>27. Block Element Definitions</h2></div></div></div><p>The syntax and behavior of Paragraph, DelimitedBlock, List and Table
|
|
2497
2526
|
block elements is determined by block definitions contained in
|
|
2498
2527
|
<a class="link" href="#X7" title="21. Configuration Files"><span class="emphasis"><em>AsciiDoc</em></span> configuration file</a> sections.</p><p>Each definition consists of a section title followed by one or more
|
|
@@ -2638,7 +2667,7 @@ sectionbody
|
|
|
2638
2667
|
</dd><dt><span class="term">
|
|
2639
2668
|
skip
|
|
2640
2669
|
</span></dt><dd>
|
|
2641
|
-
The block is treated as a comment (see CommentBlocks).
|
|
2670
|
+
The block is treated as a comment (see <a class="link" href="#X26" title="12.5. Comment Blocks">CommentBlocks</a>).
|
|
2642
2671
|
</dd><dt><span class="term">
|
|
2643
2672
|
list
|
|
2644
2673
|
</span></dt><dd>
|
|
@@ -2746,23 +2775,26 @@ Then it looks in the <code class="literal">asciidoc(1)</code> <code class="liter
|
|
|
2746
2775
|
</li><li>
|
|
2747
2776
|
Finally it relies on the executing shell to search the environment
|
|
2748
2777
|
search path (<code class="literal">$PATH</code>).
|
|
2749
|
-
</li></ul></div
|
|
2778
|
+
</li></ul></div><p>Sub-directories are also included in the searches — standard practice
|
|
2779
|
+
is to install each filter in it’s own sub-directory with the same name
|
|
2780
|
+
as the filter’s style definition. For example the music filter’s style
|
|
2781
|
+
name is <span class="emphasis"><em>music</em></span> so it’s configuration and filter files are stored in
|
|
2782
|
+
the <code class="literal">filters/music</code> directory.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_filter_configuration_files"></a>28.2. Filter Configuration Files</h3></div></div></div><p>Filters are normally accompanied by a configuration file containing a
|
|
2750
2783
|
Paragraph or DelimitedBlock definition along with corresponding markup
|
|
2751
|
-
templates.</p><p>
|
|
2752
|
-
|
|
2753
|
-
</
|
|
2754
|
-
|
|
2755
|
-
|
|
2756
|
-
|
|
2757
|
-
|
|
2758
|
-
|
|
2759
|
-
|
|
2760
|
-
|
|
2761
|
-
<code class="literal">./filters/code-filter-readme.txt</code> file.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>This filter primarily to demonstrate how to write a filter — it’s much to simplistic to be passed off as a code syntax highlighter.
|
|
2784
|
+
templates.</p><p>While it is possible to create new Paragraph or DelimitedBlock
|
|
2785
|
+
definitions the preferred way to implement a filter is to add a
|
|
2786
|
+
<a class="link" href="#X23" title="27.1. Styles">style</a> to an existing Paragraph or DelimitedBlock definition
|
|
2787
|
+
(all filters shipped with <span class="emphasis"><em>AsciiDoc</em></span> use this technique). The filter is
|
|
2788
|
+
applied to the paragraph or delimited block by preceding it with an
|
|
2789
|
+
attribute list: the first positional attribute is the style name,
|
|
2790
|
+
remaining attributes are normally filter specific parameters.</p><p><code class="literal">asciidoc(1)</code> auto-loads all <code class="literal">.conf</code> files found in the filter search
|
|
2791
|
+
paths (see previous section).</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X56"></a>28.3. Code Filter</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes with a toy filter for highlighting source code keywords
|
|
2792
|
+
and comments. See also the <code class="literal">./filters/code/code-filter-readme.txt</code>
|
|
2793
|
+
file.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>This filter primarily to demonstrate how to write a filter — it’s much to simplistic to be passed off as a code syntax highlighter.
|
|
2762
2794
|
If you want a full featured multi-language highlighter use the
|
|
2763
2795
|
<a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>.</p></td></tr></table></div><pre class="screen">.Code filter example
|
|
2764
2796
|
[code,python]
|
|
2765
|
-
|
|
2797
|
+
----------------------------------------------
|
|
2766
2798
|
''' A multi-line
|
|
2767
2799
|
comment.'''
|
|
2768
2800
|
def sub_word(mo):
|
|
@@ -2772,7 +2804,7 @@ def sub_word(mo):
|
|
|
2772
2804
|
return quote + word + quote
|
|
2773
2805
|
else:
|
|
2774
2806
|
return word
|
|
2775
|
-
|
|
2807
|
+
----------------------------------------------</pre><p>Outputs:</p><div class="example"><a id="id2544749"></a><p class="title"><b>Example 5. Code filter example</b></p><div class="example-contents"><pre class="screen"><span class="emphasis"><em>''' A multi-line</em></span>
|
|
2776
2808
|
<span class="emphasis"><em> comment.'''</em></span>
|
|
2777
2809
|
<span class="strong"><strong>def</strong></span> sub_word(mo):
|
|
2778
2810
|
<span class="emphasis"><em> ''' Single line comment.'''</em></span>
|
|
@@ -2803,8 +2835,8 @@ associated with generating and sequencing the toolchain commands and
|
|
|
2803
2835
|
managing intermediate and output files. <code class="literal">a2x(1)</code> also optionally
|
|
2804
2836
|
deploys admonition and navigation icons and a CSS stylesheet. See the
|
|
2805
2837
|
<code class="literal"><code class="literal">a2x(1)</code></code> man page for more details. All you need is
|
|
2806
|
-
<a class="link" href="#
|
|
2807
|
-
<a class="link" href="#
|
|
2838
|
+
<a class="link" href="#">xsltproc(1)</a>, <a class="link" href="#">DocBook XSL Stylesheets</a> and optionally:
|
|
2839
|
+
<a class="link" href="#">dblatex</a> or <a class="link" href="#">FOP</a> (if you want PDF); <code class="literal">w3m(1)</code> or
|
|
2808
2840
|
<code class="literal">lynx(1)</code> (if you want text).</p><p>The following examples generate <code class="literal">doc/source-highlight-filter.pdf</code> from
|
|
2809
2841
|
the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">doc/source-highlight-filter.txt</code> source file. The first
|
|
2810
2842
|
example uses <code class="literal">dblatex(1)</code> (the default PDF generator) the second
|
|
@@ -2829,7 +2861,7 @@ If the DocBook <span class="emphasis"><em>lang</em></span> attribute is set then
|
|
|
2829
2861
|
is easily customized and can be used in situations where there is no
|
|
2830
2862
|
suitable DocBook toolchain (see the
|
|
2831
2863
|
<a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span> website</a> for example).</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_pdf_generation"></a>29.3. PDF generation</h3></div></div></div><p>There are two commonly used tools to generate PDFs from DocBook,
|
|
2832
|
-
<a class="link" href="#
|
|
2864
|
+
<a class="link" href="#">dblatex</a> and <a class="link" href="#">FOP</a>.</p><div class="itemizedlist"><p class="title"><b>dblatex or FOP?</b></p><ul type="disc"><li>
|
|
2833
2865
|
<span class="emphasis"><em>dblatex</em></span> is easier to install, there’s zero configuration
|
|
2834
2866
|
required and no Java VM to install — it just works out of the box.
|
|
2835
2867
|
</li><li>
|
|
@@ -2837,56 +2869,56 @@ suitable DocBook toolchain (see the
|
|
|
2837
2869
|
</li><li>
|
|
2838
2870
|
<span class="emphasis"><em>dblatex</em></span> is easier to use as it converts DocBook directly to PDF
|
|
2839
2871
|
whereas before using <span class="emphasis"><em>FOP</em></span> you have to convert DocBook to XML-FO
|
|
2840
|
-
using <a class="link" href="#
|
|
2872
|
+
using <a class="link" href="#">DocBook XSL Stylesheets</a>.
|
|
2841
2873
|
</li><li>
|
|
2842
2874
|
<span class="emphasis"><em>FOP</em></span> is more feature complete (for example, callouts are processed
|
|
2843
2875
|
inside literal layouts) and arguably produces nicer looking output.
|
|
2844
2876
|
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_html_help_generation"></a>29.4. HTML Help generation</h3></div></div></div><div class="orderedlist"><ol type="1"><li>
|
|
2845
2877
|
Convert DocBook XML documents to HTML Help compiler source files
|
|
2846
|
-
using <a class="link" href="#
|
|
2878
|
+
using <a class="link" href="#">DocBook XSL Stylesheets</a> and <a class="link" href="#">xsltproc(1)</a>.
|
|
2847
2879
|
</li><li>
|
|
2848
2880
|
Convert the HTML Help source (<code class="literal">.hhp</code> and <code class="literal">.html</code>) files to HTML Help
|
|
2849
|
-
(<code class="literal">.chm</code>) files using the <a class="link" href="#X67" title="
|
|
2881
|
+
(<code class="literal">.chm</code>) files using the <a class="link" href="#X67" title="29.6. AsciiDoc dblatex configuration files">Microsoft HTML Help Compiler</a>.
|
|
2850
2882
|
</li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_toolchain_components_summary"></a>29.5. Toolchain components summary</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
2851
2883
|
<span class="emphasis"><em>AsciiDoc</em></span>
|
|
2852
2884
|
</span></dt><dd>
|
|
2853
2885
|
Converts <span class="emphasis"><em>AsciiDoc</em></span> (<code class="literal">.txt</code>) files to DocBook XML (<code class="literal">.xml</code>) files.
|
|
2854
|
-
</dd
|
|
2886
|
+
</dd><dt><span class="term">
|
|
2855
2887
|
<a class="ulink" href="http://docbook.sourceforge.net/projects/xsl/" target="_top">DocBook XSL Stylesheets</a>
|
|
2856
2888
|
</span></dt><dd>
|
|
2857
2889
|
These are a set of XSL stylesheets containing rules for converting
|
|
2858
2890
|
DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
|
|
2859
2891
|
The stylesheets are used in conjunction with an XML parser such as
|
|
2860
|
-
<a class="link" href="#
|
|
2861
|
-
</dd
|
|
2892
|
+
<a class="link" href="#">xsltproc(1)</a>.
|
|
2893
|
+
</dd><dt><span class="term">
|
|
2862
2894
|
<a class="ulink" href="http://www.xmlsoft.org" target="_top">xsltproc</a>
|
|
2863
2895
|
</span></dt><dd>
|
|
2864
2896
|
An XML parser for applying XSLT stylesheets (in our case the
|
|
2865
|
-
<a class="link" href="#
|
|
2866
|
-
</dd
|
|
2897
|
+
<a class="link" href="#">DocBook XSL Stylesheets</a>) to XML documents.
|
|
2898
|
+
</dd><dt><span class="term">
|
|
2867
2899
|
<a class="ulink" href="http://dblatex.sourceforge.net/" target="_top">dblatex</a>
|
|
2868
2900
|
</span></dt><dd>
|
|
2869
2901
|
Generates PDF, DVI, PostScript and LaTeX formats directly from
|
|
2870
|
-
DocBook source via the intermediate LaTeX typesetting language — uses <a class="link" href="#
|
|
2902
|
+
DocBook source via the intermediate LaTeX typesetting language — uses <a class="link" href="#">DocBook XSL Stylesheets</a>, <a class="link" href="#">xsltproc(1)</a> and
|
|
2871
2903
|
<code class="literal">latex(1)</code>.
|
|
2872
|
-
</dd
|
|
2904
|
+
</dd><dt><span class="term">
|
|
2873
2905
|
<a class="ulink" href="http://xml.apache.org/fop/" target="_top">FOP</a>
|
|
2874
2906
|
</span></dt><dd>
|
|
2875
2907
|
The Apache Formatting Objects Processor converts XSL-FO (<code class="literal">.fo</code>)
|
|
2876
2908
|
files to PDF files. The XSL-FO files are generated from DocBook
|
|
2877
|
-
source files using <a class="link" href="#
|
|
2878
|
-
<a class="link" href="#
|
|
2879
|
-
</dd
|
|
2909
|
+
source files using <a class="link" href="#">DocBook XSL Stylesheets</a> and
|
|
2910
|
+
<a class="link" href="#">xsltproc(1)</a>.
|
|
2911
|
+
</dd><dt><span class="term">
|
|
2880
2912
|
Microsoft Help Compiler
|
|
2881
2913
|
</span></dt><dd>
|
|
2882
2914
|
The Microsoft HTML Help Compiler (<code class="literal">hhc.exe</code>) is a command-line tool
|
|
2883
2915
|
that converts HTML Help source files to a single HTML Help (<code class="literal">.chm</code>)
|
|
2884
2916
|
file. It runs on MS Windows platforms and can be downloaded from
|
|
2885
2917
|
<a class="ulink" href="http://www.microsoft.com" target="_top">http://www.microsoft.com</a>.
|
|
2886
|
-
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="
|
|
2918
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X67"></a>29.6. AsciiDoc dblatex configuration files</h3></div></div></div><p>The <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">./dblatex</code> directory contains
|
|
2887
2919
|
<code class="literal">asciidoc-dblatex.xsl</code> (customized XSL parameter settings) and
|
|
2888
2920
|
<code class="literal">asciidoc-dblatex.sty</code> (customized LaTeX settings). These are examples
|
|
2889
|
-
of optional <a class="link" href="#
|
|
2921
|
+
of optional <a class="link" href="#">dblatex</a> output customization and are used by
|
|
2890
2922
|
<a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_asciidoc_docbook_xsl_stylesheets_drivers"></a>29.7. AsciiDoc DocBook XSL Stylesheets drivers</h3></div></div></div><p>You will have noticed that the distributed HTML and HTML Help
|
|
2891
2923
|
documentation files (for example <code class="literal">./doc/asciidoc.html</code>) are not the
|
|
2892
2924
|
plain outputs produced using the default <span class="emphasis"><em>DocBook XSL Stylesheets</em></span>
|
|
@@ -3005,17 +3037,16 @@ highlight clear Search
|
|
|
3005
3037
|
" Don't move to matched text while search pattern is being entered.
|
|
3006
3038
|
set noincsearch
|
|
3007
3039
|
|
|
3008
|
-
"
|
|
3009
|
-
nnoremap
|
|
3040
|
+
" Reformat paragraphs and list.
|
|
3041
|
+
nnoremap R gq}
|
|
3010
3042
|
|
|
3011
|
-
"
|
|
3012
|
-
|
|
3013
|
-
nnoremap W :%s/[\r \t]\+$//<CR>:set et<CR>:retab!<CR>
|
|
3043
|
+
" Delete trailing white space and Dos-returns and to expand tabs to spaces.
|
|
3044
|
+
nnoremap S :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR>
|
|
3014
3045
|
|
|
3015
3046
|
autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
|
|
3016
|
-
\ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2
|
|
3047
|
+
\ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc
|
|
3017
3048
|
\ textwidth=70 wrap formatoptions=tcqn
|
|
3018
|
-
\ formatlistpat=^\\s*<
|
|
3049
|
+
\ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
|
|
3019
3050
|
\ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:></pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_troubleshooting"></a>33.3. Troubleshooting</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li>
|
|
3020
3051
|
The <code class="literal">asciidoc(1)</code> <code class="literal">-v</code> (<code class="literal">--verbose</code>) command-line option displays the
|
|
3021
3052
|
order of configuration file loading and warns of potential
|
|
@@ -3073,35 +3104,22 @@ Macro attribute lists
|
|
|
3073
3104
|
</span></dt><dd><p>
|
|
3074
3105
|
If named attribute list entries are present then all string
|
|
3075
3106
|
attribute values must be quoted. For example:
|
|
3076
|
-
</p><pre class="literallayout">["Desktop screenshot",width=32]</pre></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_combining_separate_documents"></a>33.5. Combining
|
|
3107
|
+
</p><pre class="literallayout">["Desktop screenshot",width=32]</pre></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_combining_separate_documents"></a>33.5. Combining separate documents</h3></div></div></div><p>You have a number of stand-alone <span class="emphasis"><em>AsciiDoc</em></span> documents that you want to
|
|
3077
3108
|
process as a single document. Simply processing them with a series of
|
|
3078
|
-
<code class="literal">include</code> macros won’t work
|
|
3079
|
-
|
|
3080
|
-
document
|
|
3081
|
-
|
|
3082
|
-
Push the standard title underlines down one level by defining a new
|
|
3083
|
-
level 0 underline in a custom configuration file. For example
|
|
3084
|
-
<code class="literal">combined.conf</code>:
|
|
3085
|
-
</p><pre class="literallayout">[titles]
|
|
3086
|
-
underlines="__","==","--","~~","^^"</pre></li><li>
|
|
3087
|
-
If you use single line titles you’ll need to make corresponding
|
|
3088
|
-
adjustments to the <code class="literal">[titles]</code> section <code class="literal">sect0</code>…<code class="literal">sect4</code> entries.
|
|
3089
|
-
</li><li><p>
|
|
3090
|
-
Create a top level wrapper document. For example <code class="literal">combined.txt</code>:
|
|
3091
|
-
</p><pre class="screen"> Combined Document Title
|
|
3092
|
-
_______________________
|
|
3109
|
+
<code class="literal">include</code> macros won’t work because the documents contain (level 0)
|
|
3110
|
+
document titles. The solution is to create a top level wrapper
|
|
3111
|
+
document that redefines the document underlines, pushing them down one
|
|
3112
|
+
level. For example <code class="literal">combined.txt</code>:</p><pre class="screen">:titles.underlines: "__","==","--","~~","^^"
|
|
3093
3113
|
|
|
3094
|
-
|
|
3114
|
+
Combined Document Title
|
|
3115
|
+
_______________________
|
|
3095
3116
|
|
|
3096
|
-
|
|
3117
|
+
include::document1.txt[]
|
|
3097
3118
|
|
|
3098
|
-
|
|
3099
|
-
|
|
3100
|
-
|
|
3101
|
-
|
|
3102
|
-
The combined document title uses the newly defined level 0 underline
|
|
3103
|
-
(underscore characters).
|
|
3104
|
-
</li><li>
|
|
3119
|
+
include::document2.txt[]
|
|
3120
|
+
|
|
3121
|
+
include::document3.txt[]</pre><p>The document titles in the included documents will now be processed as
|
|
3122
|
+
level 1 section titles.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3105
3123
|
Put a blank line between the <code class="literal">include</code> macro lines to ensure the
|
|
3106
3124
|
title of the included document is not seen as part of the last
|
|
3107
3125
|
paragraph of the previous document.
|
|
@@ -3109,41 +3127,40 @@ Put a blank line between the <code class="literal">include</code> macro lines to
|
|
|
3109
3127
|
You won’t want document Headers (Author and Revision lines) in the
|
|
3110
3128
|
included files — conditionally exclude them if they are necessary
|
|
3111
3129
|
for stand-alone processing.
|
|
3112
|
-
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_processing_document_sections_separately"></a>33.6. Processing
|
|
3113
|
-
section) which are combined and processed with the following
|
|
3114
|
-
document:</p><pre class="screen">
|
|
3115
|
-
|
|
3116
|
-
|
|
3117
|
-
|
|
3130
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_processing_document_sections_separately"></a>33.6. Processing document sections separately</h3></div></div></div><p>You have divided your <span class="emphasis"><em>AsciiDoc</em></span> document into separate files (one per
|
|
3131
|
+
top level section) which are combined and processed with the following
|
|
3132
|
+
top level document:</p><pre class="screen">Combined Document Title
|
|
3133
|
+
=======================
|
|
3134
|
+
Joe Bloggs
|
|
3135
|
+
v1.0, 12-Aug-03
|
|
3118
3136
|
|
|
3119
|
-
|
|
3137
|
+
include::section1.txt[]
|
|
3120
3138
|
|
|
3121
|
-
|
|
3139
|
+
include::section2.txt[]
|
|
3122
3140
|
|
|
3123
|
-
|
|
3141
|
+
include::section3.txt[]</pre><p>You also want to process the section files as separate documents.
|
|
3124
3142
|
This is easy because <code class="literal">asciidoc(1)</code> will quite happily process
|
|
3125
|
-
<code class="literal">section1.txt</code>, <code class="literal">section2.txt</code> and <code class="literal">section3.txt</code> separately
|
|
3126
|
-
|
|
3127
|
-
|
|
3128
|
-
|
|
3129
|
-
|
|
3130
|
-
documents explained in the previous section.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_processing_document_chunks"></a>33.7. Processing Document Chunks</h3></div></div></div><p><code class="literal">asciidoc(1)</code> can be used as a filter, so you can pipe chunks of text
|
|
3143
|
+
<code class="literal">section1.txt</code>, <code class="literal">section2.txt</code> and <code class="literal">section3.txt</code> separately — the
|
|
3144
|
+
resulting output documents contain the section but have no document
|
|
3145
|
+
title.</p><p>Use the <code class="literal">-s</code> (<code class="literal">--no-header-footer</code>) command-line option to suppress
|
|
3146
|
+
header and footer output, this is useful if the processed output is to
|
|
3147
|
+
be included in another file. For example:</p><pre class="literallayout">$ asciidoc -s -b docbook section1.txt</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_processing_document_snippets"></a>33.7. Processing document snippets</h3></div></div></div><p><code class="literal">asciidoc(1)</code> can be used as a filter, so you can pipe chunks of text
|
|
3131
3148
|
through it. For example:</p><pre class="literallayout">$ echo 'Hello *World!*' | asciidoc -s -
|
|
3132
|
-
<div class="
|
|
3133
|
-
|
|
3134
|
-
included in another file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_badges_in_html_page_footers"></a>33.8. Badges in HTML Page Footers</h3></div></div></div><p>See the <code class="literal">[footer]</code> section in the <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">xhtml11.conf</code>
|
|
3135
|
-
configuration file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_pretty_printing_asciidoc_output"></a>33.9. Pretty Printing AsciiDoc Output</h3></div></div></div><p>If the indentation and layout of the <code class="literal">asciidoc(1)</code> output is not to your
|
|
3149
|
+
<div class="paragraph"><p>Hello <strong>World!</strong></p></div></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_badges_in_html_page_footers"></a>33.8. Badges in HTML page footers</h3></div></div></div><p>See the <code class="literal">[footer]</code> section in the <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">xhtml11.conf</code>
|
|
3150
|
+
configuration file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_pretty_printing_asciidoc_output"></a>33.9. Pretty printing AsciiDoc output</h3></div></div></div><p>If the indentation and layout of the <code class="literal">asciidoc(1)</code> output is not to your
|
|
3136
3151
|
liking you can:</p><div class="orderedlist"><ol type="1"><li>
|
|
3137
3152
|
Change the indentation and layout of configuration file markup
|
|
3138
3153
|
template sections. The <code class="literal">{empty}</code> glossary entry is useful for
|
|
3139
3154
|
outputting trailing blank lines in markup templates.
|
|
3140
3155
|
</li><li><p>
|
|
3141
|
-
|
|
3142
|
-
<code class="literal">asciidoc(1)</code> output. Example:
|
|
3143
|
-
</p><pre class="literallayout">$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml</pre></li
|
|
3156
|
+
Use Dave Raggett’s <a class="ulink" href="http://tidy.sourceforge.net/" target="_top">HTML Tidy</a> program
|
|
3157
|
+
to tidy <code class="literal">asciidoc(1)</code> output. Example:
|
|
3158
|
+
</p><pre class="literallayout">$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml</pre></li><li><p>
|
|
3159
|
+
Use the <code class="literal">xmllint(1)</code> format option. Example:
|
|
3160
|
+
</p><pre class="literallayout">$ xmllint --format mydoc.xml</pre></li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_supporting_minor_docbook_dtd_variations"></a>33.10. Supporting minor DocBook DTD variations</h3></div></div></div><p>The conditional inclusion of DocBook SGML markup at the end of the
|
|
3144
3161
|
distribution <code class="literal">docbook.conf</code> file illustrates how to support minor DTD
|
|
3145
3162
|
variations. The included sections override corresponding entries from
|
|
3146
|
-
preceding sections.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_shipping_stand_alone_asciidoc_source"></a>33.11. Shipping
|
|
3163
|
+
preceding sections.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_shipping_stand_alone_asciidoc_source"></a>33.11. Shipping stand-alone AsciiDoc source</h3></div></div></div><p>Reproducing presentation documents from someone else’s source has one
|
|
3147
3164
|
major problem: unless your configuration files are the same as the
|
|
3148
3165
|
creator’s you won’t get the same output.</p><p>The solution is to create a single backend specific configuration file
|
|
3149
3166
|
using the <code class="literal">asciidoc(1)</code> <code class="literal">-c</code> (<code class="literal">--dump-conf</code>) command-line option. You
|
|
@@ -3155,26 +3172,26 @@ file for <code class="literal">mydoc.txt</code>:</p><pre class="literallayout">$
|
|
|
3155
3172
|
these three files (and a Python interpreter) the recipient can
|
|
3156
3173
|
regenerate the HMTL output:</p><pre class="literallayout">$ ./asciidoc.py -eb xhtml11 mydoc.txt</pre><p>The <code class="literal">-e</code> (<code class="literal">--no-conf</code>) option excludes the use of implicit
|
|
3157
3174
|
configuration files, ensuring that only entries from the
|
|
3158
|
-
<code class="literal">mydoc-html.conf</code> configuration are used.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_inserting_blank_space"></a>33.12. Inserting
|
|
3175
|
+
<code class="literal">mydoc-html.conf</code> configuration are used.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_inserting_blank_space"></a>33.12. Inserting blank space</h3></div></div></div><p>Adjust your style sheets to add the correct separation between block
|
|
3159
3176
|
elements. Inserting blank paragraphs containing a single non-breaking
|
|
3160
3177
|
space character <code class="literal">{nbsp}</code> works but is an ad hoc solution compared
|
|
3161
|
-
to using style sheets.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_closing_open_sections"></a>33.13. Closing
|
|
3178
|
+
to using style sheets.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_closing_open_sections"></a>33.13. Closing open sections</h3></div></div></div><p>You can close off section tags up to level <code class="literal">N</code> by calling the
|
|
3162
3179
|
<code class="literal">eval::[Section.setlevel(N)]</code> system macro. This is useful if you
|
|
3163
3180
|
want to include a section composed of raw markup. The following
|
|
3164
3181
|
example includes a DocBook glossary division at the top section level
|
|
3165
|
-
(level 0):</p><pre class="screen">
|
|
3182
|
+
(level 0):</p><pre class="screen">ifdef::backend-docbook[]
|
|
3166
3183
|
|
|
3167
|
-
|
|
3184
|
+
eval::[Section.setlevel(0)]
|
|
3168
3185
|
|
|
3169
|
-
|
|
3170
|
-
|
|
3171
|
-
|
|
3172
|
-
|
|
3173
|
-
|
|
3174
|
-
|
|
3175
|
-
|
|
3176
|
-
|
|
3177
|
-
|
|
3186
|
+
+++++++++++++++++++++++++++++++
|
|
3187
|
+
<glossary>
|
|
3188
|
+
<title>Glossary</title>
|
|
3189
|
+
<glossdiv>
|
|
3190
|
+
...
|
|
3191
|
+
</glossdiv>
|
|
3192
|
+
</glossary>
|
|
3193
|
+
+++++++++++++++++++++++++++++++
|
|
3194
|
+
endif::backend-docbook[]</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_validating_output_files"></a>33.14. Validating output files</h3></div></div></div><p>Use <code class="literal">xmllint(1)</code> to check the <span class="emphasis"><em>AsciiDoc</em></span> generated markup is both well
|
|
3178
3195
|
formed and valid. Here are some examples:</p><pre class="literallayout">$ xmllint --nonet --noout --valid docbook-file.xml
|
|
3179
3196
|
$ xmllint --nonet --noout --valid xhtml11-file.html
|
|
3180
3197
|
$ xmllint --nonet --noout --valid --html html4-file.html</pre><p>The <code class="literal">--valid</code> option checks the file is valid against the document
|
|
@@ -3229,7 +3246,7 @@ inclusion of arbitrary files.</p><p>The safe mode is enabled by default and can
|
|
|
3229
3246
|
<code class="literal">eval</code>, <code class="literal">sys</code> and <code class="literal">sys2</code> executable attributes and block macros are
|
|
3230
3247
|
not executed.
|
|
3231
3248
|
</li><li>
|
|
3232
|
-
<code class="literal"
|
|
3249
|
+
<code class="literal">include::<filename>[]</code> and <code class="literal">\include1::<filename>[]</code> block macro
|
|
3233
3250
|
files must reside inside the parent file’s directory.
|
|
3234
3251
|
</li><li>
|
|
3235
3252
|
<code class="literal">{include:<filename>}</code> executable attribute files must reside
|
|
@@ -3310,13 +3327,13 @@ idea.</p></td></tr></table></div></div></div><div class="appendix" lang="en" xml
|
|
|
3310
3327
|
boundaries (the default behavior); <span class="emphasis"><em>unbreakable</em></span> attempts to keep the
|
|
3311
3328
|
table together on a single page. If neither option is specified the
|
|
3312
3329
|
default XSL stylesheet behavior prevails.</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>pgwide</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>docbook (XSL/FO)</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>table, block image, horizontal labeled list</p></td><td style="" align="left" valign="top"><p>Specifies that the element should be rendered across the full text
|
|
3313
|
-
width of the page irrespective of the current indentation.</p></td></tr></tbody></table></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.
|
|
3314
|
-
definition</p></div><div class="footnote"><p><sup>[<a id="ftn.
|
|
3330
|
+
width of the page irrespective of the current indentation.</p></td></tr></tbody></table></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id2528525" href="#id2528525" class="simpara">1</a>] </sup>This is a rough structural guide, not a rigorous syntax
|
|
3331
|
+
definition</p></div><div class="footnote"><p><sup>[<a id="ftn.id2533619" href="#id2533619" class="simpara">2</a>] </sup>An example footnote.</p></div><div class="footnote"><p><sup>[<a id="ftn.note2" href="#note2" class="simpara">3</a>] </sup>Second footnote</p></div><div class="footnote"><p><sup>[<a id="ftn.id2541424" href="#id2541424" class="simpara">4</a>] </sup>The existence of a <code class="literal">{revisionhistory}</code> attribute causes a
|
|
3315
3332
|
revision history file (if it exists) to be included in DocBook
|
|
3316
3333
|
outputs. If a file named like <code class="literal">{docname}-revhistory.xml</code> exists in
|
|
3317
3334
|
the document’s directory then it will be added verbatim to the DocBook
|
|
3318
3335
|
header (see the <code class="literal">./doc/asciidoc-revhistory.xml</code> example that comes
|
|
3319
|
-
with the <span class="emphasis"><em>AsciiDoc</em></span> distribution).</p></div><div class="footnote"><p><sup>[<a id="ftn.
|
|
3336
|
+
with the <span class="emphasis"><em>AsciiDoc</em></span> distribution).</p></div><div class="footnote"><p><sup>[<a id="ftn.id2543097" href="#id2543097" class="simpara">5</a>] </sup>Conditional inclusion using <code class="literal">ifdef</code> and <code class="literal">ifndef</code> macros
|
|
3320
3337
|
differs from attribute conditional inclusion in that the former
|
|
3321
3338
|
occurs when the file is read while the latter occurs when the
|
|
3322
3339
|
contents are written.</p></div></div></div></body></html>
|