FooBarWidget-mizuho 0.9.3 → 0.9.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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>
|