FooBarWidget-mizuho 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE.txt +20 -0
- data/README.markdown +68 -0
- data/Rakefile +9 -0
- data/asciidoc/BUGS +34 -0
- data/asciidoc/BUGS.txt +28 -0
- data/asciidoc/CHANGELOG +1585 -0
- data/asciidoc/CHANGELOG.txt +1595 -0
- data/asciidoc/COPYING +339 -0
- data/asciidoc/COPYRIGHT +18 -0
- data/asciidoc/INSTALL +82 -0
- data/asciidoc/INSTALL.txt +71 -0
- data/asciidoc/README +46 -0
- data/asciidoc/README.txt +36 -0
- data/asciidoc/a2x +641 -0
- data/asciidoc/asciidoc.conf +404 -0
- data/asciidoc/asciidoc.py +4255 -0
- data/asciidoc/common.aap +9 -0
- data/asciidoc/dblatex/asciidoc-dblatex.sty +18 -0
- data/asciidoc/dblatex/asciidoc-dblatex.xsl +17 -0
- data/asciidoc/dblatex/dblatex-readme.txt +22 -0
- data/asciidoc/doc/a2x.1 +246 -0
- data/asciidoc/doc/a2x.1.txt +195 -0
- data/asciidoc/doc/article.css-embedded.html +579 -0
- data/asciidoc/doc/article.html +62 -0
- data/asciidoc/doc/article.pdf +0 -0
- data/asciidoc/doc/article.txt +124 -0
- data/asciidoc/doc/asciidoc-revhistory.xml +27 -0
- data/asciidoc/doc/asciidoc.1 +161 -0
- data/asciidoc/doc/asciidoc.1.css-embedded.html +562 -0
- data/asciidoc/doc/asciidoc.1.css.html +212 -0
- data/asciidoc/doc/asciidoc.1.html +190 -0
- data/asciidoc/doc/asciidoc.1.txt +118 -0
- data/asciidoc/doc/asciidoc.conf +8 -0
- data/asciidoc/doc/asciidoc.css-embedded.html +7954 -0
- data/asciidoc/doc/asciidoc.css.html +7553 -0
- data/asciidoc/doc/asciidoc.dict +673 -0
- data/asciidoc/doc/asciidoc.html +3502 -0
- data/asciidoc/doc/asciidoc.txt +4757 -0
- data/asciidoc/doc/asciimath.txt +47 -0
- data/asciidoc/doc/book-multi.css-embedded.html +575 -0
- data/asciidoc/doc/book-multi.html +72 -0
- data/asciidoc/doc/book-multi.txt +159 -0
- data/asciidoc/doc/book.css-embedded.html +585 -0
- data/asciidoc/doc/book.html +60 -0
- data/asciidoc/doc/book.txt +133 -0
- data/asciidoc/doc/customers.csv +18 -0
- data/asciidoc/doc/faq.txt +262 -0
- data/asciidoc/doc/latex-backend.html +224 -0
- data/asciidoc/doc/latex-backend.txt +193 -0
- data/asciidoc/doc/latexmath.txt +35 -0
- data/asciidoc/doc/main.aap +293 -0
- data/asciidoc/doc/music-filter.html +513 -0
- data/asciidoc/doc/music-filter.pdf +0 -0
- data/asciidoc/doc/music-filter.txt +158 -0
- data/asciidoc/doc/source-highlight-filter.html +183 -0
- data/asciidoc/doc/source-highlight-filter.pdf +0 -0
- data/asciidoc/doc/source-highlight-filter.txt +174 -0
- data/asciidoc/docbook-xsl/asciidoc-docbook-xsl.txt +71 -0
- data/asciidoc/docbook-xsl/chunked.xsl +19 -0
- data/asciidoc/docbook-xsl/common.xsl +67 -0
- data/asciidoc/docbook-xsl/fo.xsl +117 -0
- data/asciidoc/docbook-xsl/htmlhelp.xsl +17 -0
- data/asciidoc/docbook-xsl/manpage.xsl +28 -0
- data/asciidoc/docbook-xsl/shaded-literallayout.patch +32 -0
- data/asciidoc/docbook-xsl/xhtml.xsl +14 -0
- data/asciidoc/docbook.conf +606 -0
- data/asciidoc/examples/website/CHANGELOG.html +3828 -0
- data/asciidoc/examples/website/INSTALL.html +163 -0
- data/asciidoc/examples/website/README-website.html +129 -0
- data/asciidoc/examples/website/README-website.txt +29 -0
- data/asciidoc/examples/website/README.html +125 -0
- data/asciidoc/examples/website/a2x.1.html +395 -0
- data/asciidoc/examples/website/asciidoc-docbook-xsl.html +165 -0
- data/asciidoc/examples/website/asciimath.html +157 -0
- data/asciidoc/examples/website/build-website.sh +25 -0
- data/asciidoc/examples/website/downloads.html +219 -0
- data/asciidoc/examples/website/downloads.txt +98 -0
- data/asciidoc/examples/website/faq.html +372 -0
- data/asciidoc/examples/website/index.html +398 -0
- data/asciidoc/examples/website/index.txt +222 -0
- data/asciidoc/examples/website/latex-backend.html +640 -0
- data/asciidoc/examples/website/latexmath.html +119 -0
- data/asciidoc/examples/website/layout1.conf +161 -0
- data/asciidoc/examples/website/layout1.css +65 -0
- data/asciidoc/examples/website/layout2.conf +158 -0
- data/asciidoc/examples/website/layout2.css +93 -0
- data/asciidoc/examples/website/manpage.html +266 -0
- data/asciidoc/examples/website/music-filter.html +242 -0
- data/asciidoc/examples/website/music1.abc +12 -0
- data/asciidoc/examples/website/music1.png +0 -0
- data/asciidoc/examples/website/music2.ly +9 -0
- data/asciidoc/examples/website/music2.png +0 -0
- data/asciidoc/examples/website/source-highlight-filter.html +251 -0
- data/asciidoc/examples/website/support.html +78 -0
- data/asciidoc/examples/website/support.txt +5 -0
- data/asciidoc/examples/website/userguide.html +7597 -0
- data/asciidoc/examples/website/version9.html +143 -0
- data/asciidoc/examples/website/version9.txt +48 -0
- data/asciidoc/filters/code-filter-readme.txt +37 -0
- data/asciidoc/filters/code-filter-test-c++.txt +7 -0
- data/asciidoc/filters/code-filter-test.txt +15 -0
- data/asciidoc/filters/code-filter.conf +8 -0
- data/asciidoc/filters/code-filter.py +239 -0
- data/asciidoc/filters/music-filter-test.txt +40 -0
- data/asciidoc/filters/music-filter.conf +40 -0
- data/asciidoc/filters/music2png.py +189 -0
- data/asciidoc/filters/source-highlight-filter-test.txt +19 -0
- data/asciidoc/filters/source-highlight-filter.conf +100 -0
- data/asciidoc/help.conf +213 -0
- data/asciidoc/html4.conf +363 -0
- data/asciidoc/images/highlighter.png +0 -0
- data/asciidoc/images/icons/README +5 -0
- data/asciidoc/images/icons/callouts/1.png +0 -0
- data/asciidoc/images/icons/callouts/10.png +0 -0
- data/asciidoc/images/icons/callouts/11.png +0 -0
- data/asciidoc/images/icons/callouts/12.png +0 -0
- data/asciidoc/images/icons/callouts/13.png +0 -0
- data/asciidoc/images/icons/callouts/14.png +0 -0
- data/asciidoc/images/icons/callouts/15.png +0 -0
- data/asciidoc/images/icons/callouts/2.png +0 -0
- data/asciidoc/images/icons/callouts/3.png +0 -0
- data/asciidoc/images/icons/callouts/4.png +0 -0
- data/asciidoc/images/icons/callouts/5.png +0 -0
- data/asciidoc/images/icons/callouts/6.png +0 -0
- data/asciidoc/images/icons/callouts/7.png +0 -0
- data/asciidoc/images/icons/callouts/8.png +0 -0
- data/asciidoc/images/icons/callouts/9.png +0 -0
- data/asciidoc/images/icons/caution.png +0 -0
- data/asciidoc/images/icons/example.png +0 -0
- data/asciidoc/images/icons/home.png +0 -0
- data/asciidoc/images/icons/important.png +0 -0
- data/asciidoc/images/icons/next.png +0 -0
- data/asciidoc/images/icons/note.png +0 -0
- data/asciidoc/images/icons/prev.png +0 -0
- data/asciidoc/images/icons/tip.png +0 -0
- data/asciidoc/images/icons/up.png +0 -0
- data/asciidoc/images/icons/warning.png +0 -0
- data/asciidoc/images/smallnew.png +0 -0
- data/asciidoc/images/tiger.png +0 -0
- data/asciidoc/install.sh +55 -0
- data/asciidoc/javascripts/ASCIIMathML.js +938 -0
- data/asciidoc/javascripts/LaTeXMathML.js +1223 -0
- data/asciidoc/javascripts/toc.js +69 -0
- data/asciidoc/lang-es.conf +15 -0
- data/asciidoc/latex.conf +663 -0
- data/asciidoc/linuxdoc.conf +285 -0
- data/asciidoc/math.conf +50 -0
- data/asciidoc/stylesheets/docbook-xsl.css +271 -0
- data/asciidoc/stylesheets/xhtml-deprecated-manpage.css +21 -0
- data/asciidoc/stylesheets/xhtml-deprecated.css +247 -0
- data/asciidoc/stylesheets/xhtml11-manpage.css +18 -0
- data/asciidoc/stylesheets/xhtml11-quirks.css +49 -0
- data/asciidoc/stylesheets/xhtml11.css +284 -0
- data/asciidoc/t.conf +20 -0
- data/asciidoc/text.conf +16 -0
- data/asciidoc/vim/ftdetect/asciidoc_filetype.vim +53 -0
- data/asciidoc/vim/syntax/asciidoc.vim +139 -0
- data/asciidoc/xhtml-deprecated-css.conf +235 -0
- data/asciidoc/xhtml-deprecated.conf +351 -0
- data/asciidoc/xhtml11-quirks.conf +57 -0
- data/asciidoc/xhtml11.conf +514 -0
- data/bin/mizuho +40 -0
- data/lib/mizuho/chapter.rb +54 -0
- data/lib/mizuho/generator.rb +106 -0
- data/lib/mizuho/heading.rb +46 -0
- data/lib/mizuho/parser.rb +99 -0
- data/lib/mizuho/template.rb +50 -0
- data/mizuho.gemspec +34 -0
- data/templates/asciidoc.css +358 -0
- data/templates/asciidoc.html.erb +86 -0
- data/templates/manualsonrails.css +165 -0
- data/templates/manualsonrails.html.erb +97 -0
- data/test/parser_spec.rb +190 -0
- data/test/spec_helper.rb +43 -0
- metadata +234 -0
|
@@ -0,0 +1,3502 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
3
|
+
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>AsciiDoc User Guide</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="id2417888"></a>AsciiDoc User Guide</h1></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 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.2.7</td><td align="left">4 July 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><dt><span class="section"><a href="#_linuxdoc">4.4. linuxdoc</a></span></dt><dt><span class="section"><a href="#_latex">4.5. latex</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="#X50">7.2. Inline Passthroughs</a></span></dt><dt><span class="section"><a href="#_superscripts_and_subscripts">7.3. Superscripts and Subscripts</a></span></dt><dt><span class="section"><a href="#_line_breaks_html_xhtml">7.4. Line Breaks (HTML/XHTML)</a></span></dt><dt><span class="section"><a href="#_rulers_html_xhtml">7.5. Rulers (HTML/XHTML)</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="#_passthrough_blocks">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="#_vertical_labeled_lists">13.2. Vertical Labeled Lists</a></span></dt><dt><span class="section"><a href="#_horizontal_labeled_lists">13.3. Horizontal Labeled Lists</a></span></dt><dt><span class="section"><a href="#_question_and_answer_lists">13.4. Question and Answer Lists</a></span></dt><dt><span class="section"><a href="#_glossary_lists">13.5. Glossary Lists</a></span></dt><dt><span class="section"><a href="#_bibliography_lists">13.6. Bibliography Lists</a></span></dt><dt><span class="section"><a href="#X15">13.7. List Item Continuation</a></span></dt><dt><span class="section"><a href="#X29">13.8. 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="#_macro_definitions">17.4. 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="#_asciidoc_table_block_elements">18.2. AsciiDoc Table Block Elements</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="#X7">20. Configuration Files</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuration_file_format">20.1. Configuration File Format</a></span></dt><dt><span class="section"><a href="#_markup_template_sections">20.2. Markup Template Sections</a></span></dt><dt><span class="section"><a href="#_special_sections">20.3. Special Sections</a></span></dt><dt><span class="section"><a href="#X27">20.4. Configuration File Names and Locations</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_attributes">21. Document Attributes</a></span></dt><dt><span class="section"><a href="#X18">22. Attribute Entries</a></span></dt><dt><span class="section"><a href="#X21">23. Attribute Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#_macro_attribute_lists">23.1. Macro Attribute lists</a></span></dt><dt><span class="section"><a href="#_attributelist_element">23.2. AttributeList Element</a></span></dt></dl></dd><dt><span class="section"><a href="#_attribute_references">24. Attribute References</a></span></dt><dd><dl><dt><span class="section"><a href="#_simple_attributes_references">24.1. Simple Attributes References</a></span></dt><dt><span class="section"><a href="#_conditional_attribute_references">24.2. Conditional Attribute References</a></span></dt><dt><span class="section"><a href="#X24">24.3. System Attribute References</a></span></dt></dl></dd><dt><span class="section"><a href="#X60">25. Intrinsic Attributes</a></span></dt><dt><span class="section"><a href="#_block_element_definitions">26. Block Element Definitions</a></span></dt><dd><dl><dt><span class="section"><a href="#X23">26.1. Styles</a></span></dt><dt><span class="section"><a href="#_paragraphs_2">26.2. Paragraphs</a></span></dt><dt><span class="section"><a href="#_delimited_blocks_2">26.3. Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_lists">26.4. Lists</a></span></dt><dt><span class="section"><a href="#_tables_2">26.5. Tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X59">27. Filters</a></span></dt><dd><dl><dt><span class="section"><a href="#_filter_search_paths">27.1. Filter Search Paths</a></span></dt><dt><span class="section"><a href="#_filter_configuration_files">27.2. Filter Configuration Files</a></span></dt><dt><span class="section"><a href="#X56">27.3. Code Filter</a></span></dt><dt><span class="section"><a href="#X57">27.4. Source Code Highlighter Filter</a></span></dt><dt><span class="section"><a href="#X58">27.5. Music Filter</a></span></dt></dl></dd><dt><span class="section"><a href="#X12">28. Converting DocBook to other file formats</a></span></dt><dd><dl><dt><span class="section"><a href="#X43">28.1. a2x Toolchain Wrapper</a></span></dt><dt><span class="section"><a href="#_html_generation">28.2. HTML generation</a></span></dt><dt><span class="section"><a href="#_pdf_generation">28.3. PDF generation</a></span></dt><dt><span class="section"><a href="#_html_help_generation">28.4. HTML Help generation</a></span></dt><dt><span class="section"><a href="#_toolchain_components_summary">28.5. Toolchain components summary</a></span></dt><dt><span class="section"><a href="#_asciidoc_dblatex_configuration_files">28.6. AsciiDoc dblatex configuration files</a></span></dt><dt><span class="section"><a href="#_asciidoc_docbook_xsl_stylesheets_drivers">28.7. AsciiDoc DocBook XSL Stylesheets drivers</a></span></dt></dl></dd><dt><span class="section"><a href="#_generating_plain_text_files">29. Generating Plain Text Files</a></span></dt><dt><span class="section"><a href="#_xml_and_character_sets">30. XML and Character Sets</a></span></dt><dd><dl><dt><span class="section"><a href="#_pdf_fonts">30.1. PDF Fonts</a></span></dt></dl></dd><dt><span class="section"><a href="#X36">31. Help Commands</a></span></dt><dd><dl><dt><span class="section"><a href="#_customizing_help">31.1. Customizing Help</a></span></dt></dl></dd><dt><span class="section"><a href="#_tips_and_tricks">32. Tips and Tricks</a></span></dt><dd><dl><dt><span class="section"><a href="#_know_your_editor">32.1. Know Your Editor</a></span></dt><dt><span class="section"><a href="#X20">32.2. Vim Commands for Formatting AsciiDoc</a></span></dt><dt><span class="section"><a href="#_troubleshooting">32.3. Troubleshooting</a></span></dt><dt><span class="section"><a href="#_gotchas">32.4. Gotchas</a></span></dt><dt><span class="section"><a href="#_combining_separate_documents">32.5. Combining Separate Documents</a></span></dt><dt><span class="section"><a href="#_processing_document_sections_separately">32.6. Processing Document Sections Separately</a></span></dt><dt><span class="section"><a href="#_processing_document_chunks">32.7. Processing Document Chunks</a></span></dt><dt><span class="section"><a href="#_badges_in_html_page_footers">32.8. Badges in HTML Page Footers</a></span></dt><dt><span class="section"><a href="#_pretty_printing_asciidoc_output">32.9. Pretty Printing AsciiDoc Output</a></span></dt><dt><span class="section"><a href="#_supporting_minor_docbook_dtd_variations">32.10. Supporting Minor DocBook DTD Variations</a></span></dt><dt><span class="section"><a href="#_shipping_stand_alone_asciidoc_source">32.11. Shipping Stand-alone AsciiDoc Source</a></span></dt><dt><span class="section"><a href="#_inserting_blank_space">32.12. Inserting Blank Space</a></span></dt><dt><span class="section"><a href="#_closing_open_sections">32.13. Closing Open Sections</a></span></dt><dt><span class="section"><a href="#_validating_output_files">32.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><dt><span class="section"><a href="#X32">A.2. Version 6 to version 7</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="#_asciimathml_support">E. ASCIIMathML Support</a></span></dt><dt><span class="appendix"><a href="#_vim_syntax_highlighter">F. Vim Syntax Highlighter</a></span></dt><dd><dl><dt><span class="section"><a href="#_limitations">F.1. Limitations</a></span></dt></dl></dd></dl></div><p><span class="emphasis"><em>AsciiDoc</em></span> is a text document format for writing short documents,
|
|
4
|
+
articles, books and UNIX man pages. <span class="emphasis"><em>AsciiDoc</em></span> files can be translated
|
|
5
|
+
to HTML and DocBook markups using the <code class="literal">asciidoc(1)</code> command. <span class="emphasis"><em>AsciiDoc</em></span>
|
|
6
|
+
is highly configurable: both the <span class="emphasis"><em>AsciiDoc</em></span> source file syntax and the
|
|
7
|
+
backend output markups (which can be almost any type of SGML/XML
|
|
8
|
+
markup) can be customized and extended by the user.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_introduction"></a>1. Introduction</h2></div></div></div><div class="sidebar"><p class="title"><b></b></p><p>This is an overly large document, it probably needs to be refactored
|
|
9
|
+
into a Tutorial, FAQ, Quick Reference and Formal Reference.</p><p>If you're new to <span class="emphasis"><em>AsciiDoc</em></span> read this section and the <a href="#X6" title="2. Getting Started">Getting Started</a> section and take a look at the example <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">.txt</code>
|
|
10
|
+
source files in the distribution <code class="literal">doc</code> directory.</p></div><p>Plain text is the most universal electronic document format, no matter
|
|
11
|
+
what computing environment you use, you can always read and write
|
|
12
|
+
plain text documentation. But for many applications plain text is not
|
|
13
|
+
a viable presentation format. HTML, PDF and roff (roff is used for
|
|
14
|
+
man pages) are the most widely used UNIX presentation formats.
|
|
15
|
+
DocBook is a popular UNIX documentation markup format which can be
|
|
16
|
+
translated to HTML, PDF and other presentation formats.</p><p><span class="emphasis"><em>AsciiDoc</em></span> is a plain text human readable/writable document format that
|
|
17
|
+
can be translated to DocBook or HTML using the <code class="literal">asciidoc(1)</code> command.
|
|
18
|
+
You can then either use <code class="literal">asciidoc(1)</code> generated HTML directly or run
|
|
19
|
+
<code class="literal">asciidoc(1)</code> DocBook output through your favorite DocBook toolchain or
|
|
20
|
+
use the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">a2x(1)</code> toolchain wrapper to produce PDF, DVI, LaTeX,
|
|
21
|
+
PostScript, man page, HTML and text formats.</p><p>The <span class="emphasis"><em>AsciiDoc</em></span> format is a useful presentation format in its own right:
|
|
22
|
+
<span class="emphasis"><em>AsciiDoc</em></span> files are unencumbered by markup and are easily viewed,
|
|
23
|
+
proofed and edited.</p><p><span class="emphasis"><em>AsciiDoc</em></span> is light weight: it consists of a single Python script and a
|
|
24
|
+
bunch of configuration files. Apart from <code class="literal">asciidoc(1)</code> and a Python
|
|
25
|
+
interpreter, no other programs are required to convert <span class="emphasis"><em>AsciiDoc</em></span> text
|
|
26
|
+
files to DocBook or HTML. See <a href="#X11" title="2.2. Example AsciiDoc Documents">Example <span class="emphasis"><em>AsciiDoc</em></span> Documents</a>
|
|
27
|
+
below.</p><p>You write an <span class="emphasis"><em>AsciiDoc</em></span> document the same way you would write a normal
|
|
28
|
+
text document, there are no markup tags or arcane notations. Built-in
|
|
29
|
+
<span class="emphasis"><em>AsciiDoc</em></span> formatting rules have been kept to a minimum and are
|
|
30
|
+
reasonably obvious.</p><p>Text markup conventions tend to be a matter of (often strong) personal
|
|
31
|
+
preference: if the default syntax is not to your liking you can define
|
|
32
|
+
your own by editing the text based <code class="literal">asciidoc(1)</code> configuration files.
|
|
33
|
+
You can create your own configuration files to translate <span class="emphasis"><em>AsciiDoc</em></span>
|
|
34
|
+
documents to almost any SGML/XML markup.</p><p><code class="literal">asciidoc(1)</code> comes with a set of configuration files to translate
|
|
35
|
+
<span class="emphasis"><em>AsciiDoc</em></span> articles, books or man pages to HTML or DocBook backend
|
|
36
|
+
formats.</p><div class="sidebar"><p class="title"><b>My AsciiDoc Itch</b></p><p>DocBook has emerged as the de facto standard Open Source documentation
|
|
37
|
+
format. But DocBook is a complex language, the marked up text is
|
|
38
|
+
difficult to read and even more difficult to write directly — I found
|
|
39
|
+
I was spending more time typing markup tags, consulting reference
|
|
40
|
+
manuals and fixing syntax errors, than I was writing the
|
|
41
|
+
documentation.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X6"></a>2. Getting Started</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_installing_asciidoc"></a>2.1. Installing AsciiDoc</h3></div></div></div><p>See the <code class="literal">README</code> and <code class="literal">INSTALL</code> files for install prerequisites and
|
|
42
|
+
procedures. Packagers take a look at <a href="#X38" title="B. Packager Notes">Appendix B: Packager Notes</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X11"></a>2.2. Example AsciiDoc Documents</h3></div></div></div><p>The best way to quickly get a feel for <span class="emphasis"><em>AsciiDoc</em></span> is to view the
|
|
43
|
+
<span class="emphasis"><em>AsciiDoc</em></span> web site and/or distributed examples:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
44
|
+
Take a look at the linked examples on the <span class="emphasis"><em>AsciiDoc</em></span> web site home
|
|
45
|
+
page <a href="http://www.methods.co.nz/asciidoc/" target="_top">http://www.methods.co.nz/asciidoc/</a>. Press the <span class="emphasis"><em>Page Source</em></span>
|
|
46
|
+
sidebar menu item to view corresponding <span class="emphasis"><em>AsciiDoc</em></span> source.
|
|
47
|
+
</li><li>
|
|
48
|
+
Read the <code class="literal">.txt</code> source files in the distribution <code class="literal">./doc</code> directory
|
|
49
|
+
in conjunction with the corresponding HTML and DocBook XML files.
|
|
50
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_asciidoc_document_types"></a>3. AsciiDoc Document Types</h2></div></div></div><p>There are three types of <span class="emphasis"><em>AsciiDoc</em></span> documents: article, book and
|
|
51
|
+
manpage. All document types share the same <span class="emphasis"><em>AsciiDoc</em></span> format with some
|
|
52
|
+
minor variations.</p><p>Use the <code class="literal">asciidoc(1)</code> <code class="literal">-d</code> (<code class="literal">—doctype</code>) option to specify the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
53
|
+
document type — the default document type is <span class="emphasis"><em>article</em></span>.</p><p>By convention the <code class="literal">.txt</code> file extension is used for <span class="emphasis"><em>AsciiDoc</em></span> document
|
|
54
|
+
source files.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_article"></a>3.1. article</h3></div></div></div><p>Used for short documents, articles and general documentation. See the
|
|
55
|
+
<span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">./doc/article.txt</code> example.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_book"></a>3.2. book</h3></div></div></div><p>Books share the same format as articles; in addition there is the
|
|
56
|
+
option to add level 0 book part sections.</p><p>Book documents will normally be used to produce DocBook output since
|
|
57
|
+
DocBook processors can automatically generate footnotes, table of
|
|
58
|
+
contents, list of tables, list of figures, list of examples and
|
|
59
|
+
indexes.</p><p><span class="emphasis"><em>AsciiDoc</em></span> markup supports standard DocBook frontmatter and backmatter
|
|
60
|
+
<a href="#X16" title="5.4.1. Special Sections">special sections</a> (dedication, preface, bibliography, glossary,
|
|
61
|
+
index, colophon) plus footnotes and index entries.</p><div class="variablelist"><p class="title"><b>Example book documents</b></p><dl><dt><span class="term">
|
|
62
|
+
Book
|
|
63
|
+
</span></dt><dd>
|
|
64
|
+
The <code class="literal">./doc/book.txt</code> file in the <span class="emphasis"><em>AsciiDoc</em></span> distribution.
|
|
65
|
+
</dd><dt><span class="term">
|
|
66
|
+
Multi-part book
|
|
67
|
+
</span></dt><dd>
|
|
68
|
+
The <code class="literal">./doc/book-multi.txt</code> file in the <span class="emphasis"><em>AsciiDoc</em></span> distribution.
|
|
69
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_manpage"></a>3.3. manpage</h3></div></div></div><p>Used to generate UNIX manual pages. <span class="emphasis"><em>AsciiDoc</em></span> manpage documents
|
|
70
|
+
observe special header title and section naming conventions — see the
|
|
71
|
+
<a href="#X1" title="19. Manpage Documents">Manpage Documents</a> section for details.</p><p>See also the <code class="literal">asciidoc(1)</code> man page source (<code class="literal">./doc/asciidoc.1.txt</code>) from
|
|
72
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> distribution.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X5"></a>4. AsciiDoc Backends</h2></div></div></div><p>The <code class="literal">asciidoc(1)</code> command translates an <span class="emphasis"><em>AsciiDoc</em></span> formatted file to the
|
|
73
|
+
backend format specified by the <code class="literal">-b</code> (<code class="literal">—backend</code>) command-line
|
|
74
|
+
option. <code class="literal">asciidoc(1)</code> itself has little intrinsic knowledge of backend
|
|
75
|
+
formats, all translation rules are contained in customizable cascading
|
|
76
|
+
configuration files.</p><p><span class="emphasis"><em>AsciiDoc</em></span> ships with the following predefined backend output formats:</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_docbook"></a>4.1. docbook</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> generates the following DocBook document types: article, book
|
|
77
|
+
and refentry (corresponding to the <span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>article</em></span>, <span class="emphasis"><em>book</em></span> and
|
|
78
|
+
<span class="emphasis"><em>manpage</em></span> document types).</p><p>DocBook documents are not designed to be viewed directly. Most Linux
|
|
79
|
+
distributions come with conversion tools (collectively called a
|
|
80
|
+
toolchain) for <a href="#X12" title="28. Converting DocBook to other file formats">converting DocBook files</a> to presentation
|
|
81
|
+
formats such as Postscript, HTML, PDF, DVI, PostScript, LaTeX, roff
|
|
82
|
+
(the native man page format), HTMLHelp, JavaHelp and text.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
83
|
+
The <code class="literal">—backend=docbook</code> command-line option produces DocBook XML.
|
|
84
|
+
You can produce the older DocBook SGML format using the
|
|
85
|
+
<code class="literal">—attribute sgml</code> command-line option.
|
|
86
|
+
</li><li>
|
|
87
|
+
Use the optional <a href="#X54" title="???TITLE???"><code class="literal">encoding</code></a> attribute to set the character
|
|
88
|
+
set encoding.
|
|
89
|
+
</li><li>
|
|
90
|
+
Use the optional <code class="literal">imagesdir</code> attribute to prepend to the target file
|
|
91
|
+
name paths in image inline and block macros. Defaults to a blank
|
|
92
|
+
string.
|
|
93
|
+
</li><li>
|
|
94
|
+
The <span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>Preamble</em></span> element generates a DocBook book <span class="emphasis"><em>preface</em></span>
|
|
95
|
+
element although it's more usual to use an explicit <span class="emphasis"><em>Preface</em></span>
|
|
96
|
+
special section (see the <code class="literal">./doc/book.txt</code> example book).
|
|
97
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X33"></a>4.2. xhtml11</h3></div></div></div><p>The default <code class="literal">asciidoc(1)</code> backend is <code class="literal">xhtml11</code> which generates XHTML 1.1
|
|
98
|
+
markup styled with CSS2. Default output file have a <code class="literal">.html</code> extension.
|
|
99
|
+
<span class="emphasis"><em>xhtml11</em></span> document generation is influenced by the following
|
|
100
|
+
optional attributes (the default behavior is to generate XHTML with no
|
|
101
|
+
section numbers, embedded CSS and no linked admonition icon images):</p><div class="variablelist"><dl><dt><span class="term">
|
|
102
|
+
numbered
|
|
103
|
+
</span></dt><dd>
|
|
104
|
+
Adds section numbers to section titles.
|
|
105
|
+
</dd><dt><span class="term">
|
|
106
|
+
toc
|
|
107
|
+
</span></dt><dd><p>
|
|
108
|
+
Adds a table of contents to the start of the document.
|
|
109
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
110
|
+
JavaScript needs to be enabled in your browser for this to work.
|
|
111
|
+
</li><li>
|
|
112
|
+
By default <span class="emphasis"><em>AsciiDoc</em></span> automatically embeds the required <code class="literal">toc.js</code>
|
|
113
|
+
JavaScript in the output document — use the <span class="emphasis"><em>linkcss</em></span> attribute
|
|
114
|
+
to link the script.
|
|
115
|
+
</li><li><p>
|
|
116
|
+
The following example generates a numbered table of contents by
|
|
117
|
+
embedding the <code class="literal">toc.js</code> script in the <code class="literal">mydoc.html</code> output document
|
|
118
|
+
(to link the script to the output document use the <span class="emphasis"><em>linkcss</em></span> and
|
|
119
|
+
<span class="emphasis"><em>scriptsdir</em></span> attributes):
|
|
120
|
+
</p><pre class="literallayout">$ asciidoc -a toc -a numbered mydoc.txt</pre></li></ul></div></dd><dt><span class="term">
|
|
121
|
+
toclevels
|
|
122
|
+
</span></dt><dd><p>
|
|
123
|
+
Sets the number of title levels (1..4) reported in the table of
|
|
124
|
+
contents (see the <span class="emphasis"><em>toc</em></span> attribute above). Defaults to 2 and must be
|
|
125
|
+
used with the <span class="emphasis"><em>toc</em></span> attribute. Example usage:
|
|
126
|
+
</p><pre class="literallayout">$ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt</pre></dd><dt><span class="term">
|
|
127
|
+
toc_title
|
|
128
|
+
</span></dt><dd>
|
|
129
|
+
Sets the table of contents title (defaults to <span class="emphasis"><em>Table of Contents</em></span>).
|
|
130
|
+
</dd><dt><span class="term">
|
|
131
|
+
linkcss
|
|
132
|
+
</span></dt><dd>
|
|
133
|
+
Link CSS stylesheets and JavaScripts (see the <span class="emphasis"><em>stylesdir</em></span> and
|
|
134
|
+
<span class="emphasis"><em>scriptsdir</em></span> attributes below). By default <span class="emphasis"><em>linkcss</em></span> is undefined in
|
|
135
|
+
which case stylesheets and scripts are automatically embedded in the
|
|
136
|
+
output document.
|
|
137
|
+
</dd><dt><span class="term">
|
|
138
|
+
stylesdir
|
|
139
|
+
</span></dt><dd>
|
|
140
|
+
The name of the directory containing linked stylesheets. Defaults to
|
|
141
|
+
<code class="literal">.</code> (the same directory as the linking document).
|
|
142
|
+
</dd><dt><span class="term">
|
|
143
|
+
scriptsdir
|
|
144
|
+
</span></dt><dd>
|
|
145
|
+
The name of the directory containing linked JavaScripts. Defaults to
|
|
146
|
+
<code class="literal">.</code> (the same directory as the linking document).
|
|
147
|
+
</dd></dl></div><div class="variablelist"><a id="X45"></a><dl><dt><span class="term">
|
|
148
|
+
icons
|
|
149
|
+
</span></dt><dd>
|
|
150
|
+
Link admonition paragraph and admonition block icon images and badge
|
|
151
|
+
images. By default <span class="emphasis"><em>icons</em></span> is undefined and text is used in place of
|
|
152
|
+
icon images.
|
|
153
|
+
</dd></dl></div><div class="variablelist"><a id="X44"></a><dl><dt><span class="term">
|
|
154
|
+
iconsdir
|
|
155
|
+
</span></dt><dd>
|
|
156
|
+
The name of the directory containing linked admonition and
|
|
157
|
+
navigation icons. Defaults to <code class="literal">./images/icons</code>.
|
|
158
|
+
</dd><dt><span class="term">
|
|
159
|
+
imagesdir
|
|
160
|
+
</span></dt><dd>
|
|
161
|
+
This attribute is prepended to the target image file name paths in
|
|
162
|
+
image inline and block macros. Defaults to a blank string.
|
|
163
|
+
</dd><dt><span class="term">
|
|
164
|
+
theme
|
|
165
|
+
</span></dt><dd>
|
|
166
|
+
Use alternative stylesheets (see <a href="#X35" title="4.2.1. Stylesheets">Stylesheets</a>).
|
|
167
|
+
</dd><dt><span class="term">
|
|
168
|
+
badges
|
|
169
|
+
</span></dt><dd>
|
|
170
|
+
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
|
|
171
|
+
footers. By default badges are omitted (<span class="emphasis"><em>badges</em></span> is undefined).
|
|
172
|
+
</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
|
|
173
|
+
output document not the source document.</p></td></tr></table></div><div class="variablelist"><a id="X54"></a><dl><dt><span class="term">
|
|
174
|
+
encoding
|
|
175
|
+
</span></dt><dd><p>
|
|
176
|
+
Set the input and output document character set encoding. For
|
|
177
|
+
example the <code class="literal">—attribute encoding=ISO-8859-1</code> command-line option
|
|
178
|
+
will set the character set encoding to <code class="literal">ISO-8859-1</code>.
|
|
179
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
180
|
+
The default encoding is UTF-8.
|
|
181
|
+
</li><li>
|
|
182
|
+
This attribute specifies the character set in the output document.
|
|
183
|
+
</li><li>
|
|
184
|
+
The encoding name must correspond to a Python codec name or alias.
|
|
185
|
+
</li><li><p>
|
|
186
|
+
The <span class="emphasis"><em>encoding</em></span> attribute can be set using an AttributeEntry inside
|
|
187
|
+
the document header but it must come at the start of the document
|
|
188
|
+
before the document title. For example:
|
|
189
|
+
</p><pre class="literallayout">:encoding: ISO-8859-1</pre></li></ul></div></dd><dt><span class="term">
|
|
190
|
+
quirks
|
|
191
|
+
</span></dt><dd>
|
|
192
|
+
Use the <code class="literal">xhtml11-quirks.css</code> stylesheet to work around IE6 browser
|
|
193
|
+
incompatibilities (this is the default behavior).
|
|
194
|
+
</dd><dt><span class="term">
|
|
195
|
+
data-uri
|
|
196
|
+
</span></dt><dd>
|
|
197
|
+
Embed images referenced by <span class="emphasis"><em>image</em></span> macros using the <a href="#X66" title="Embedding images in XHTML documents">data: uri scheme</a>.
|
|
198
|
+
</dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X35"></a>4.2.1. Stylesheets</h4></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> XHTML output is styled using CSS2 stylesheets from the
|
|
199
|
+
distribution <code class="literal">./stylesheets/</code> directory.</p><div class="important" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="./images/icons/important.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>All browsers have CSS quirks, but Microsoft's IE6 has so many
|
|
200
|
+
omissions and errors that the <code class="literal">xhtml11-quirks.css</code> stylesheet and
|
|
201
|
+
<code class="literal">xhtml11-quirks.conf</code> configuration files are included during XHTML
|
|
202
|
+
backend processing to to implement workarounds for IE6. If you don't
|
|
203
|
+
use IE6 then the quirks stylesheet and configuration files can be
|
|
204
|
+
omitted using the <code class="literal">—attribute quirks!</code> command-line option.</p></td></tr></table></div><p>Default <span class="emphasis"><em>xhtml11</em></span> stylesheets:</p><div class="variablelist"><dl><dt><span class="term">
|
|
205
|
+
<code class="literal">./stylesheets/xhtml11.css</code>
|
|
206
|
+
</span></dt><dd>
|
|
207
|
+
The main stylesheet.
|
|
208
|
+
</dd><dt><span class="term">
|
|
209
|
+
<code class="literal">./stylesheets/xhtml11-manpage.css</code>
|
|
210
|
+
</span></dt><dd>
|
|
211
|
+
Tweaks for manpage document type generation.
|
|
212
|
+
</dd><dt><span class="term">
|
|
213
|
+
<code class="literal">./stylesheets/xhtml11-quirks.css</code>
|
|
214
|
+
</span></dt><dd>
|
|
215
|
+
Stylesheet modifications to work around IE6 browser
|
|
216
|
+
incompatibilities.
|
|
217
|
+
</dd></dl></div><p>Use the <span class="emphasis"><em>theme</em></span> attribute to select and alternative set of
|
|
218
|
+
stylesheets. For example, the command-line option <code class="literal">-a theme=foo</code> will
|
|
219
|
+
use stylesheets <code class="literal">foo.css</code>, <code class="literal">foo-manpage.css</code> and <code class="literal">foo-quirks.css</code>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_html4"></a>4.3. html4</h3></div></div></div><p>This backend generates plain (unstyled) HTML 4.01 Transitional markup.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_linuxdoc"></a>4.4. linuxdoc</h3></div></div></div><div class="warning" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="./images/icons/warning.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The <span class="emphasis"><em>AsciiDoc</em></span> linuxdoc backend is still distributed but is no
|
|
220
|
+
longer being actively developed or tested with new <span class="emphasis"><em>AsciiDoc</em></span> releases
|
|
221
|
+
(the last supported release was <span class="emphasis"><em>AsciiDoc</em></span> 6.0.3).</p></td></tr></table></div><div class="itemizedlist"><ul type="disc"><li>
|
|
222
|
+
Tables are not supported.
|
|
223
|
+
</li><li>
|
|
224
|
+
Images are not supported.
|
|
225
|
+
</li><li>
|
|
226
|
+
Callouts are not supported.
|
|
227
|
+
</li><li>
|
|
228
|
+
Horizontal labeled lists are not supported.
|
|
229
|
+
</li><li>
|
|
230
|
+
Only article document types are allowed.
|
|
231
|
+
</li><li>
|
|
232
|
+
The Abstract section can consist only of a single paragraph.
|
|
233
|
+
</li><li>
|
|
234
|
+
An <span class="emphasis"><em>AsciiDoc</em></span> Preamble is not allowed.
|
|
235
|
+
</li><li>
|
|
236
|
+
The LinuxDoc output format does not support multiple labels per
|
|
237
|
+
labeled list item although LinuxDoc conversion programs generally
|
|
238
|
+
output all the labels with a warning.
|
|
239
|
+
</li><li>
|
|
240
|
+
Don't apply character formatting to the <code class="literal">link</code> macro attributes,
|
|
241
|
+
LinuxDoc does not allow displayed link text to be formatted.
|
|
242
|
+
</li></ul></div><p>The default output file name extension is <code class="literal">.sgml</code>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_latex"></a>4.5. latex</h3></div></div></div><p>An experimental LaTeX backend has been written for <span class="emphasis"><em>AsciiDoc</em></span> by
|
|
243
|
+
Benjamin Klum. A tutorial <code class="literal">./doc/latex-backend.html</code> is included in
|
|
244
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> distribution which can also be viewed at
|
|
245
|
+
<a href="http://www.methods.co.nz/asciidoc/latex-backend.html" target="_top">http://www.methods.co.nz/asciidoc/latex-backend.html</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="_document_structure"></a>5. Document Structure</h2></div></div></div><p>An <span class="emphasis"><em>AsciiDoc</em></span> document consists of a series of <a href="#X8">block elements</a>
|
|
246
|
+
starting with an optional document Header, followed by an optional
|
|
247
|
+
Preamble, followed by zero or more document Sections.</p><p>Almost any combination of zero or more elements constitutes a valid
|
|
248
|
+
<span class="emphasis"><em>AsciiDoc</em></span> document: documents can range from a single sentence to a
|
|
249
|
+
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
|
|
250
|
+
other block elements.</p><p>The <span class="emphasis"><em>AsciiDoc</em></span> block structure can be informally summarized
|
|
251
|
+
<sup>[<a id="id2536808" href="#ftn.id2536808">1</a>]</sup> as follows:</p><pre class="literallayout">Document ::= (Header?,Preamble?,Section*)
|
|
252
|
+
Header ::= (Title,(AuthorLine,RevisionLine?)?)
|
|
253
|
+
AuthorLine ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
|
|
254
|
+
RevisionLine ::= (Revision?,Date)
|
|
255
|
+
Preamble ::= (SectionBody)
|
|
256
|
+
Section ::= (Title,SectionBody?,(Section)*)
|
|
257
|
+
SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
|
|
258
|
+
Block ::= (Paragraph|DelimitedBlock|List|Table)
|
|
259
|
+
List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
|
|
260
|
+
BulletedList ::= (ListItem)+
|
|
261
|
+
NumberedList ::= (ListItem)+
|
|
262
|
+
CalloutList ::= (ListItem)+
|
|
263
|
+
LabeledList ::= (ItemLabel+,ListItem)+
|
|
264
|
+
ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
|
|
265
|
+
Table ::= (Ruler,TableHeader?,TableBody,TableFooter?)
|
|
266
|
+
TableHeader ::= (TableRow+,TableUnderline)
|
|
267
|
+
TableFooter ::= (TableRow+,TableUnderline)
|
|
268
|
+
TableBody ::= (TableRow+,TableUnderline)
|
|
269
|
+
TableRow ::= (TableData+)</pre><p>Where:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
270
|
+
<span class="emphasis"><em>?</em></span> implies zero or one occurrence, <span class="emphasis"><em>+</em></span> implies one or more
|
|
271
|
+
occurrences, <span class="emphasis"><em>*</em></span> implies zero or more occurrences.
|
|
272
|
+
</li><li>
|
|
273
|
+
All block elements are separated by line boundaries.
|
|
274
|
+
</li><li>
|
|
275
|
+
<code class="literal">BlockId</code>, <code class="literal">AttributeEntry</code> and <code class="literal">AttributeList</code> block elements (not
|
|
276
|
+
shown) can occur almost anywhere.
|
|
277
|
+
</li><li>
|
|
278
|
+
There are a number of document type and backend specific
|
|
279
|
+
restrictions imposed on the block syntax.
|
|
280
|
+
</li><li>
|
|
281
|
+
The following elements cannot contain blank lines: Header, Title,
|
|
282
|
+
Paragraph, ItemText.
|
|
283
|
+
</li><li>
|
|
284
|
+
A ListParagraph is a Paragraph with its <span class="emphasis"><em>listelement</em></span> option set.
|
|
285
|
+
</li><li>
|
|
286
|
+
A ListContinuation is a <a href="#X15" title="13.7. List Item Continuation">list continuation element</a>.
|
|
287
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_header"></a>5.2. Header</h3></div></div></div><p>The Header is optional but must start on the first line of the
|
|
288
|
+
document and must begin with a document <a href="#X17" title="8. Titles">title</a>. Optional Author
|
|
289
|
+
and Revision lines immediately follow the title. The header can be
|
|
290
|
+
preceded by a CommentBlock or comment lines.</p><p>The author line contains the author's name optionally followed by the
|
|
291
|
+
author's email address. The author's name consists of a first name
|
|
292
|
+
followed by optional middle and last names separated by white space.
|
|
293
|
+
Multi-word first, middle and last names can be entered in the header
|
|
294
|
+
author line using the underscore as a word separator. The email
|
|
295
|
+
address comes last and must be enclosed in angle <> brackets. Author
|
|
296
|
+
names cannot contain angle <> bracket characters.</p><p>The optional document header revision line should immediately follow
|
|
297
|
+
the author line. The revision line can be one of two formats:</p><div class="orderedlist"><ol type="1"><li><p>
|
|
298
|
+
An alphanumeric document revision number followed by a date:
|
|
299
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
300
|
+
The revision number and date must be separated by a comma.
|
|
301
|
+
</li><li>
|
|
302
|
+
The revision number is optional but must contain at least one
|
|
303
|
+
numeric character.
|
|
304
|
+
</li><li>
|
|
305
|
+
Any non-numeric characters preceding the first numeric character
|
|
306
|
+
will be dropped.
|
|
307
|
+
</li></ul></div></li><li>
|
|
308
|
+
An RCS/CSV/SVN $Id$ marker.
|
|
309
|
+
</li></ol></div><p>The document heading is separated from the remainder of the document
|
|
310
|
+
by one or more blank lines.</p><p>Here's an example <span class="emphasis"><em>AsciiDoc</em></span> document header:</p><pre class="literallayout">Writing Documentation using AsciiDoc
|
|
311
|
+
====================================
|
|
312
|
+
Stuart Rackham <srackham@gmail.com>
|
|
313
|
+
v2.0, February 2003</pre><p>You can override or set header parameters by passing <span class="emphasis"><em>revision</em></span>,
|
|
314
|
+
<span class="emphasis"><em>data</em></span>, <span class="emphasis"><em>email</em></span>, <span class="emphasis"><em>author</em></span>, <span class="emphasis"><em>authorinitials</em></span>, <span class="emphasis"><em>firstname</em></span> and
|
|
315
|
+
<span class="emphasis"><em>lastname</em></span> attributes using the <code class="literal">asciidoc(1)</code> <code class="literal">-a</code> (<code class="literal">—attribute</code>)
|
|
316
|
+
command-line option. For example:</p><pre class="literallayout">$ asciidoc -a date=2004/07/27 article.txt</pre><p>Attributes can also be added to the header for substitution in the
|
|
317
|
+
header template with <a href="#X18" title="22. Attribute Entries">Attribute Entry</a> elements.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_preamble"></a>5.3. Preamble</h3></div></div></div><p>The Preamble is an optional untitled section body between the document
|
|
318
|
+
Header and the first Section title.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_sections"></a>5.4. Sections</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> supports five section levels 0 to 4 (although only book
|
|
319
|
+
documents are allowed to contain level 0 sections). Section levels are
|
|
320
|
+
delineated by the section <a href="#X17" title="8. Titles">titles</a>.</p><p>Sections are translated using configuration file markup templates. To
|
|
321
|
+
determine which configuration file template to use <span class="emphasis"><em>AsciiDoc</em></span> first
|
|
322
|
+
searches for special section titles in the <a href="#X16" title="5.4.1. Special Sections"><code class="literal">[specialsections]</code></a>
|
|
323
|
+
configuration entries, if not found it uses the <code class="literal">[sect<level>]</code>
|
|
324
|
+
template.</p><p>The <code class="literal">-n</code> (<code class="literal">—section-numbers</code>) command-line option auto-numbers HTML
|
|
325
|
+
outputs (DocBook line numbering is handled automatically by the
|
|
326
|
+
DocBook toolchain commands).</p><p>Section IDs are auto-generated from section titles if the <code class="literal">sectids</code>
|
|
327
|
+
attribute is defined (the default behavior). The primary purpose of
|
|
328
|
+
this feature is to ensure persistence of table of contents links:
|
|
329
|
+
missing section IDs are generated dynamically by the JavaScript TOC
|
|
330
|
+
generator <span class="strong"><strong>after</strong></span> the page is loaded. This means, for example, that if
|
|
331
|
+
you go to a bookmarked dynamically generated TOC address the page will
|
|
332
|
+
load but the browser will ignore the (as yet ungenerated) section ID.</p><p>The IDs are generated by the following algorithm:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
333
|
+
Replace all non-alphanumeric title characters with an underscore.
|
|
334
|
+
</li><li>
|
|
335
|
+
Strip leading or trailing underscores.
|
|
336
|
+
</li><li>
|
|
337
|
+
Convert to lowercase.
|
|
338
|
+
</li><li>
|
|
339
|
+
Prepend an underscore (so there's no possibility of name clashes
|
|
340
|
+
with existing document IDs).
|
|
341
|
+
</li><li>
|
|
342
|
+
A numbered suffix (<code class="literal">_2</code>, <code class="literal">_3</code> …) is added if a same named
|
|
343
|
+
auto-generated section ID exists.
|
|
344
|
+
</li></ul></div><p>For example the title <span class="emphasis"><em>Jim's House</em></span> would generate the ID
|
|
345
|
+
<code class="literal">_jim_s_house</code>.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X16"></a>5.4.1. Special Sections</h4></div></div></div><p>In addition to normal sections, documents can contain optional
|
|
346
|
+
frontmatter and backmatter sections — for example: preface,
|
|
347
|
+
bibliography, table of contents, index.</p><p>The <span class="emphasis"><em>AsciiDoc</em></span> configuration file <code class="literal">[specialsections]</code> section specifies
|
|
348
|
+
special section titles and the corresponding backend markup templates.</p><p><code class="literal">[specialsections]</code> entries are formatted like:</p><pre class="literallayout"><pattern>=<name></pre><p><code class="literal"><pattern></code> is a Python regular expression and <code class="literal"><name></code> is the name of
|
|
349
|
+
a configuration file markup template section. If the <code class="literal"><pattern></code>
|
|
350
|
+
matches an <span class="emphasis"><em>AsciiDoc</em></span> document section title then the backend output is
|
|
351
|
+
marked up using the <code class="literal"><name></code> markup template (instead of the default
|
|
352
|
+
<code class="literal">sect<level></code> section template). The {title} attribute value is set
|
|
353
|
+
to the value of the matched regular expression group named <span class="emphasis"><em>title</em></span>, if
|
|
354
|
+
there is no <span class="emphasis"><em>title</em></span> group {title} defaults to the whole of the
|
|
355
|
+
<span class="emphasis"><em>AsciiDoc</em></span> section title.</p><p><span class="emphasis"><em>AsciiDoc</em></span> comes preconfigured with the following special section
|
|
356
|
+
titles:</p><pre class="literallayout">Preface (book documents only)
|
|
357
|
+
Abstract (article documents only)
|
|
358
|
+
Dedication (book documents only)
|
|
359
|
+
Glossary
|
|
360
|
+
Bibliography|References
|
|
361
|
+
Colophon (book documents only)
|
|
362
|
+
Index
|
|
363
|
+
Appendix [A-Z][:.] <title></pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_inline_elements"></a>5.5. Inline Elements</h3></div></div></div><p><a href="#X34">Inline document elements</a> are used to markup character
|
|
364
|
+
formatting and various types of text substitution. Inline elements and
|
|
365
|
+
inline element syntax is defined in the <code class="literal">asciidoc(1)</code> configuration
|
|
366
|
+
files.</p><p>Here is a list of <span class="emphasis"><em>AsciiDoc</em></span> inline elements in the (default) order in
|
|
367
|
+
which they are processed:</p><div class="variablelist"><dl><dt><span class="term">
|
|
368
|
+
Special characters
|
|
369
|
+
</span></dt><dd>
|
|
370
|
+
These character sequences escape special characters used by
|
|
371
|
+
the backend markup (typically "<", ">", and "&"). See
|
|
372
|
+
<code class="literal">[specialcharacters]</code> configuration file sections.
|
|
373
|
+
</dd><dt><span class="term">
|
|
374
|
+
Quotes
|
|
375
|
+
</span></dt><dd>
|
|
376
|
+
Characters that markup words and phrases; usually for
|
|
377
|
+
character formatting. See <code class="literal">[quotes]</code> configuration file
|
|
378
|
+
sections.
|
|
379
|
+
</dd><dt><span class="term">
|
|
380
|
+
Special Words
|
|
381
|
+
</span></dt><dd>
|
|
382
|
+
Word or word phrase patterns singled out for markup without
|
|
383
|
+
the need for further annotation. See <code class="literal">[specialwords]</code>
|
|
384
|
+
configuration file sections.
|
|
385
|
+
</dd><dt><span class="term">
|
|
386
|
+
Replacements
|
|
387
|
+
</span></dt><dd>
|
|
388
|
+
Each Replacement defines a word or word phrase pattern to
|
|
389
|
+
search for along with corresponding replacement text. See
|
|
390
|
+
<code class="literal">[replacements]</code> configuration file sections.
|
|
391
|
+
</dd><dt><span class="term">
|
|
392
|
+
Attributes
|
|
393
|
+
</span></dt><dd>
|
|
394
|
+
Document attribute names enclosed in braces (attribute
|
|
395
|
+
references) are replaced by the corresponding attribute value.
|
|
396
|
+
</dd><dt><span class="term">
|
|
397
|
+
Inline Macros
|
|
398
|
+
</span></dt><dd>
|
|
399
|
+
Inline macros are replaced by the contents of parametrized
|
|
400
|
+
configuration file sections.
|
|
401
|
+
</dd></dl></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_document_processing"></a>6. Document Processing</h2></div></div></div><p>The <span class="emphasis"><em>AsciiDoc</em></span> source document is read and processed as follows:</p><div class="orderedlist"><ol type="1"><li>
|
|
402
|
+
The document <span class="emphasis"><em>Header</em></span> is parsed, header parameter values are
|
|
403
|
+
substituted into the configuration file <code class="literal">[header]</code> template section
|
|
404
|
+
which is then written to the output file.
|
|
405
|
+
</li><li>
|
|
406
|
+
Each document <span class="emphasis"><em>Section</em></span> is processed and its constituent elements
|
|
407
|
+
translated to the output file.
|
|
408
|
+
</li><li>
|
|
409
|
+
The configuration file <code class="literal">[footer]</code> template section is substituted
|
|
410
|
+
and written to the output file.
|
|
411
|
+
</li></ol></div><p>When a block element is encountered <code class="literal">asciidoc(1)</code> determines the type of
|
|
412
|
+
block by checking in the following order (first to last): (section)
|
|
413
|
+
Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
|
|
414
|
+
AttributeLists, BlockTitles, Paragraphs.</p><p>The default paragraph definition <code class="literal">[paradef-default]</code> is last element
|
|
415
|
+
to be checked.</p><p>Knowing the parsing order will help you devise unambiguous macro, list
|
|
416
|
+
and block syntax rules.</p><p>Inline substitutions within block elements are performed in the
|
|
417
|
+
following default order:</p><div class="orderedlist"><ol type="1"><li>
|
|
418
|
+
Special characters
|
|
419
|
+
</li><li>
|
|
420
|
+
Quotes
|
|
421
|
+
</li><li>
|
|
422
|
+
Special words
|
|
423
|
+
</li><li>
|
|
424
|
+
Replacements
|
|
425
|
+
</li><li>
|
|
426
|
+
Attributes
|
|
427
|
+
</li><li>
|
|
428
|
+
Inline Macros
|
|
429
|
+
</li><li>
|
|
430
|
+
Passthroughs
|
|
431
|
+
</li><li>
|
|
432
|
+
Replacements2
|
|
433
|
+
</li></ol></div><p>The substitutions and substitution order performed on
|
|
434
|
+
Title, Paragraph and DelimitedBlock elements is determined by
|
|
435
|
+
configuration file parameters.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_text_formatting"></a>7. Text Formatting</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X51"></a>7.1. Quoted Text</h3></div></div></div><p>Words and phrases can be formatted by enclosing inline text with
|
|
436
|
+
quote characters:</p><div class="variablelist"><dl><dt><span class="term">
|
|
437
|
+
<span class="emphasis"><em>Emphasized text</em></span>
|
|
438
|
+
</span></dt><dd>
|
|
439
|
+
Word phrases 'enclosed in single quote characters' (acute
|
|
440
|
+
accents) or _underline characters_ are emphasized.
|
|
441
|
+
</dd><dt><span class="term">
|
|
442
|
+
<span class="strong"><strong>Strong text</strong></span>
|
|
443
|
+
</span></dt><dd>
|
|
444
|
+
Word phrases *enclosed in asterisk characters* are rendered
|
|
445
|
+
in a strong font (usually bold).
|
|
446
|
+
</dd><dt><span class="term">
|
|
447
|
+
<code class="literal">Monospaced text</code>
|
|
448
|
+
</span></dt><dd>
|
|
449
|
+
Word phrases `enclosed in backtick characters` (grave
|
|
450
|
+
accents) or +plus characters+ are rendered in a monospaced font.
|
|
451
|
+
</dd><dt><span class="term">
|
|
452
|
+
“Quoted text”
|
|
453
|
+
</span></dt><dd>
|
|
454
|
+
Phrases ``enclosed with two grave accents to the left and two
|
|
455
|
+
acute accents to the right'' are rendered in quotation marks.
|
|
456
|
+
</dd><dt><span class="term">
|
|
457
|
+
Unquoted text
|
|
458
|
+
</span></dt><dd>
|
|
459
|
+
Placing #hashes around text# does nothing, it is a mechanism
|
|
460
|
+
to allow inline attributes to be applied to otherwise
|
|
461
|
+
unformatted text (see example below).
|
|
462
|
+
</dd></dl></div><p>The alternative underline and plus characters, while marginally less
|
|
463
|
+
readable, are arguably a better choice than the backtick and
|
|
464
|
+
apostrophe characters as they are not normally used for, and so not
|
|
465
|
+
confused with, punctuation.</p><p>Quoted text can be prefixed with an <a href="#X21" title="23. Attribute Lists">attribute list</a>. Currently
|
|
466
|
+
the only use made of this feature is to allow the font color,
|
|
467
|
+
background color and size to be specified (XHTML/HTML only, not
|
|
468
|
+
DocBook) using the first three positional attribute arguments. The
|
|
469
|
+
first argument is the text color; the second the background color; the
|
|
470
|
+
third is the font size. Colors are valid CSS colors and the font size
|
|
471
|
+
is a number which treated as em units. Here are some examples:</p><pre class="screen">[red]#Red text#.
|
|
472
|
+
[,yellow]*bold text on a yellow background*.
|
|
473
|
+
[blue,#b0e0e6]+Monospaced blue text on a light blue background+
|
|
474
|
+
[,,2]#Double sized text#.</pre><p>New quotes can be defined by editing <code class="literal">asciidoc(1)</code> configuration files.
|
|
475
|
+
See the <a href="#X7" title="20. Configuration Files">Configuration Files</a> section for details.</p><div class="itemizedlist"><p class="title"><b>Quoted text properties</b></p><ul type="disc"><li>
|
|
476
|
+
Quoting cannot be overlapped.
|
|
477
|
+
</li><li>
|
|
478
|
+
Different quoting types can be nested.
|
|
479
|
+
</li><li>
|
|
480
|
+
To suppress quoted text formatting place a backslash character
|
|
481
|
+
immediately in front of the leading quote character(s). In the case
|
|
482
|
+
of ambiguity between escaped and non-escaped text you will need to
|
|
483
|
+
escape both leading and trailing quotes, in the case of
|
|
484
|
+
multi-character quotes you may even need to escape individual
|
|
485
|
+
characters.
|
|
486
|
+
</li><li>
|
|
487
|
+
A configuration file <code class="literal">[quotes]</code> entry can be subsequently undefined
|
|
488
|
+
by setting it to a blank value.
|
|
489
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X52"></a>7.1.1. Constrained and Unconstrained Quotes</h4></div></div></div><p>There are actually two types of quotes:</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a id="_constrained_quotes"></a>7.1.1.1. Constrained quotes</h5></div></div></div><p>Quote text that must be bounded by white space, for example a phrase
|
|
490
|
+
or a word. These are the most common type of quote and are the ones
|
|
491
|
+
discussed previously.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a id="_unconstrained_quotes"></a>7.1.1.2. Unconstrained quotes</h5></div></div></div><p>Unconstrained quotes have no boundary constraints and can be placed
|
|
492
|
+
anywhere within inline text. For consistency and to make them easier
|
|
493
|
+
to remember unconstrained quotes are double-ups of the <code class="literal">_</code>, <code class="literal">*</code>, <code class="literal">+</code>
|
|
494
|
+
and <code class="literal">#</code> constrained quotes:</p><pre class="literallayout">__unconstrained emphasized text__
|
|
495
|
+
**unconstrained strong text**
|
|
496
|
+
++unconstrained monospaced text++
|
|
497
|
+
##unconstrained unquoted text##</pre><p>The following example emboldens the letter F:</p><pre class="literallayout">**F**ile Open...</pre><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The <code class="literal">__</code>, <code class="literal">**</code>, <code class="literal">++</code> and <code class="literal">##</code> unconstrained quotes have to be
|
|
498
|
+
double-escaped (because of their similarity to the single character
|
|
499
|
+
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="X50"></a>7.2. Inline Passthroughs</h3></div></div></div><p>This special text quoting mechanism passes inline text to the output
|
|
500
|
+
document without the usual substitutions. There are two flavors:</p><div class="variablelist"><dl><dt><span class="term">
|
|
501
|
+
+++Triple-plus passthrough+++
|
|
502
|
+
</span></dt><dd>
|
|
503
|
+
No change is made to the quoted text, it is passed verbatim to the
|
|
504
|
+
output document.
|
|
505
|
+
</dd><dt><span class="term">
|
|
506
|
+
$$Double-dollar passthrough$$
|
|
507
|
+
</span></dt><dd>
|
|
508
|
+
Special characters are escaped but no other changes are made.
|
|
509
|
+
This passthrough can be prefixed with inline attributes.
|
|
510
|
+
</dd></dl></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.3. Superscripts and Subscripts</h3></div></div></div><p>Put ^carets on either^ side of the text to be superscripted, put
|
|
511
|
+
~tildes on either side~ of text to be subscripted. For example, the
|
|
512
|
+
following line:</p><pre class="literallayout">e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
|
|
513
|
+
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>
|
|
514
|
+
and <sub>some sub text</sub></p><p>Superscripts and subscripts are implemented as <a href="#X52" title="7.1.1. Constrained and Unconstrained Quotes">unconstrained quotes</a> so they can be escaped with a leading backslash and prefixed
|
|
515
|
+
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_html_xhtml"></a>7.4. Line Breaks (HTML/XHTML)</h3></div></div></div><p>A plus character preceded by at least one space character at the end
|
|
516
|
+
of a line forces a line break. It generates an HTML line break
|
|
517
|
+
(<code class="literal"><br /></code>) tag. Line breaks are ignored when outputting to DocBook
|
|
518
|
+
since it has no line break element.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_rulers_html_xhtml"></a>7.5. Rulers (HTML/XHTML)</h3></div></div></div><p>A line of four or more apostrophe characters will generate an HTML
|
|
519
|
+
ruler (<code class="literal"><hr /></code>) tag. Ignored when generating non-HTML output formats.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_tabs"></a>7.6. Tabs</h3></div></div></div><p>By default tab characters input files will translated to 8 spaces. Tab
|
|
520
|
+
expansion is set with the <span class="emphasis"><em>tabsize</em></span> entry in the configuration file
|
|
521
|
+
<code class="literal">[miscellaneous]</code> section and can be overridden in the <span class="emphasis"><em>include</em></span> block macro
|
|
522
|
+
by setting a <span class="emphasis"><em>tabsize</em></span> attribute in the macro's attribute list. For example:</p><pre class="literallayout">include::addendum.txt[tabsize=2]</pre><p>The tab size can also be set using the attribute command-line option,
|
|
523
|
+
for example <code class="literal">--attribute tabsize=4</code></p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_replacements"></a>7.7. Replacements</h3></div></div></div><p>The following replacements are defined in the default <span class="emphasis"><em>AsciiDoc</em></span>
|
|
524
|
+
configuration:</p><pre class="literallayout">(C) copyright, (TM) trademark, (R) registered trademark,
|
|
525
|
+
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
|
|
526
|
+
double arrow, <= left double arrow.</pre><p>Which are rendered as:</p><p>© copyright, ™ trademark, ® registered trademark,
|
|
527
|
+
— em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right
|
|
528
|
+
double arrow, ⇐ left double arrow.</p><p>The <a href="#X7" title="20. Configuration Files">Configuration Files</a> section explains how to configure your
|
|
529
|
+
own replacements.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_special_words"></a>7.8. Special Words</h3></div></div></div><p>Words defined in <code class="literal">[specialwords]</code> configuration file sections are
|
|
530
|
+
automatically marked up without having to be explicitly notated.</p><p>The <a href="#X7" title="20. Configuration Files">Configuration Files</a> section explains how to add and replace
|
|
531
|
+
special words.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X17"></a>8. Titles</h2></div></div></div><p>Document and section titles can be in either of two formats:</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_two_line_titles"></a>8.1. Two line titles</h3></div></div></div><p>A two line title consists of a title line, starting hard against the
|
|
532
|
+
left margin, and an underline. Section underlines consist a repeated
|
|
533
|
+
character pairs spanning the width of the preceding title (give or
|
|
534
|
+
take up to three characters):</p><p>The default title underlines for each of the document levels are:</p><pre class="literallayout">Level 0 (top level): ======================
|
|
535
|
+
Level 1: ----------------------
|
|
536
|
+
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
|
|
537
|
+
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
|
|
538
|
+
Level 4 (bottom level): ++++++++++++++++++++++</pre><p>Examples:</p><pre class="literallayout">Level One Section Title
|
|
539
|
+
-----------------------</pre><pre class="literallayout">Level 2 Subsection Title
|
|
540
|
+
~~~~~~~~~~~~~~~~~~~~~~~~</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X46"></a>8.2. One line titles</h3></div></div></div><p>One line titles consist of a single line delimited on either side by
|
|
541
|
+
one or more equals characters (the number of equals characters
|
|
542
|
+
corresponds to the section level minus one). Here are some examples
|
|
543
|
+
(levels 2 and 3 illustrate the optional trailing equals characters
|
|
544
|
+
syntax):</p><pre class="literallayout">= Document Title (level 0) =
|
|
545
|
+
== Section title (level 1) ==
|
|
546
|
+
=== Section title (level 2) ===
|
|
547
|
+
==== Section title (level 3) ====
|
|
548
|
+
===== Section title (level 4) =====</pre><div class="itemizedlist"><p class="title"><b>Note</b></p><ul type="disc"><li>
|
|
549
|
+
One or more spaces must fall between the title and the delimiters.
|
|
550
|
+
</li><li>
|
|
551
|
+
The trailing title delimiter is optional.
|
|
552
|
+
</li><li>
|
|
553
|
+
The one-line title syntax can be changed by editing the
|
|
554
|
+
configuration file <code class="literal">[titles]</code> section <code class="literal">sect0</code>…<code class="literal">sect4</code> entries.
|
|
555
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X42"></a>9. BlockTitles</h2></div></div></div><p>A BlockTitle element is a single line beginning with a period followed
|
|
556
|
+
by a title. The title is applied to the next Paragraph,
|
|
557
|
+
DelimitedBlock, List, Table or BlockMacro. For example:</p><pre class="literallayout">.Notes
|
|
558
|
+
- Note 1.
|
|
559
|
+
- Note 2.</pre><p>is rendered as:</p><div class="itemizedlist"><p class="title"><b>Notes</b></p><ul type="disc"><li>
|
|
560
|
+
Note 1.
|
|
561
|
+
</li><li>
|
|
562
|
+
Note 2.
|
|
563
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X41"></a>10. BlockId Element</h2></div></div></div><p>A <span class="emphasis"><em>BlockId</em></span> is a single line block element containing a unique
|
|
564
|
+
identifier enclosed in double square brackets. It is used to assign an
|
|
565
|
+
identifier to the ensuing block element for use by referring links. For
|
|
566
|
+
example:</p><pre class="literallayout">[[chapter-titles]]
|
|
567
|
+
Chapter titles can be ...</pre><p>The preceding example identifies the following paragraph so it can be
|
|
568
|
+
linked from other location, for example with
|
|
569
|
+
<code class="literal"><<chapter-titles,chapter titles>></code>.</p><p><span class="emphasis"><em>BlockId</em></span> elements can be applied to Title, Paragraph, List,
|
|
570
|
+
DelimitedBlock, Table and BlockMacro elements. The BlockId element is
|
|
571
|
+
really just an AttributeList with a special syntax which sets the
|
|
572
|
+
<code class="literal">{id}</code> attribute for substitution in the subsequent block's markup
|
|
573
|
+
template.</p><p>The <span class="emphasis"><em>BlockId</em></span> element has the same syntax and serves a similar
|
|
574
|
+
function to the <a href="#X30" title="17.1.2.1. anchor">anchor inline macro</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_paragraphs"></a>11. Paragraphs</h2></div></div></div><p>Paragraphs are terminated by a blank line, the end of file, or the
|
|
575
|
+
start of a DelimitedBlock.</p><p>Paragraph markup is specified by configuration file <code class="literal">[paradef*]</code>
|
|
576
|
+
sections. <span class="emphasis"><em>AsciiDoc</em></span> ships with the following predefined paragraph
|
|
577
|
+
types:</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_default_paragraph"></a>11.1. Default Paragraph</h3></div></div></div><p>A Default paragraph (<code class="literal">[paradef-default]</code>) consists of one or more
|
|
578
|
+
non-blank lines of text. The first line must start hard against the
|
|
579
|
+
left margin (no intervening white space). The processing expectation
|
|
580
|
+
of the default paragraph type is that of a normal paragraph of text.</p><p>The <span class="emphasis"><em>verse</em></span> paragraph <a href="#X23" title="26.1. Styles">style</a> preserves line boundaries and is
|
|
581
|
+
useful for lyrics and poems. For example:</p><pre class="screen">[verse]
|
|
582
|
+
Consul *necessitatibus* per id,
|
|
583
|
+
consetetur, eu pro everti postulant
|
|
584
|
+
homero verear ea mea, qui.</pre><p>Renders:</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p>Consul <span class="strong"><strong>necessitatibus</strong></span> per id,<br />
|
|
585
|
+
consetetur, eu pro everti postulant<br />
|
|
586
|
+
homero verear ea mea, qui.</p></div></blockquote></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_paragraph"></a>11.2. Literal Paragraph</h3></div></div></div><p>A Literal paragraph (<code class="literal">[paradef-literal]</code>) consists of one or more
|
|
587
|
+
lines of text, where the first line is indented by one or more space
|
|
588
|
+
or tab characters. Literal paragraphs are rendered verbatim in a
|
|
589
|
+
monospaced font usually without any distinguishing background or
|
|
590
|
+
border. There is no text formatting or substitutions within Literal
|
|
591
|
+
paragraphs apart from Special Characters and Callouts. For example:</p><pre class="screen"> Consul *necessitatibus* per id,
|
|
592
|
+
consetetur, eu pro everti postulant
|
|
593
|
+
homero verear ea mea, qui.</pre><p>Renders:</p><pre class="literallayout">Consul *necessitatibus* per id,
|
|
594
|
+
consetetur, eu pro everti postulant
|
|
595
|
+
homero verear ea mea, qui.</pre><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>Because <a href="#X64" title="13. Lists">lists</a> can be indented it's possible for your
|
|
596
|
+
Literal paragraph to be misinterpreted as a list — in situations like
|
|
597
|
+
this use a <a href="#X65" title="12.3. Literal Blocks">LiteralBlock</a> in place of a <span class="emphasis"><em>LiteralParagraph</em></span>.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X28"></a>11.3. Admonition Paragraphs</h3></div></div></div><p><span class="emphasis"><em>Tip</em></span>, <span class="emphasis"><em>Note</em></span>, <span class="emphasis"><em>Important</em></span>, <span class="emphasis"><em>Warning</em></span> and <span class="emphasis"><em>Caution</em></span> paragraph
|
|
598
|
+
definitions support the corresponding DocBook admonishment elements —
|
|
599
|
+
just write a normal paragraph but place <code class="literal">NOTE:</code>, <code class="literal">TIP:</code>, <code class="literal">IMPORTANT:</code>,
|
|
600
|
+
<code class="literal">WARNING:</code> or <code class="literal">CAUTION:</code> as the first word of the paragraph. For
|
|
601
|
+
example:</p><pre class="literallayout">NOTE: This is an example note.</pre><p>or the alternative syntax:</p><pre class="literallayout">[NOTE]
|
|
602
|
+
This is an example note.</pre><p>Renders:</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 is an example note.</p></td></tr></table></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>If your admonition is more than a single paragraph use an
|
|
603
|
+
<a href="#X22" title="12.9. Admonition Blocks">admonition block</a> instead.</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X47"></a>11.3.1. Admonition Icons and Captions</h4></div></div></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>Admonition customization with <code class="literal">icons</code>, <code class="literal">iconsdir</code>, <code class="literal">icon</code> and
|
|
604
|
+
<code class="literal">caption</code> attributes does not apply when generating DocBook output. If
|
|
605
|
+
you are going the DocBook route then the <a href="#X43" title="28.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> <code class="literal">—no-icons</code>
|
|
606
|
+
and <code class="literal">—icons-dir</code> options can be used to set the appropriate XSL
|
|
607
|
+
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
|
|
608
|
+
text captions instead of icon image links. To generate links to icon
|
|
609
|
+
images define the <a href="#X45" title="???TITLE???"><code class="literal">icons</code></a> attribute, for example using the <code class="literal">-a
|
|
610
|
+
icons</code> command-line option.</p><p>The <a href="#X44" title="???TITLE???"><code class="literal">iconsdir</code></a> attribute sets the location of linked icon
|
|
611
|
+
images.</p><p>You can override the default icon image using the <code class="literal">icon</code> attribute to
|
|
612
|
+
specify the path of the linked image. For example:</p><pre class="literallayout">[icon="./images/icons/wink.png"]
|
|
613
|
+
NOTE: What lovely war.</pre><p>Use the <code class="literal">caption</code> attribute to customize the admonition captions (not
|
|
614
|
+
applicable to <code class="literal">docbook</code> backend). The following example suppresses the
|
|
615
|
+
icon image and customizes the caption of a NOTE admonition (undefining
|
|
616
|
+
the <code class="literal">icons</code> attribute with <code class="literal">icons=None</code> is only necessary if
|
|
617
|
+
<a href="#X45" title="???TITLE???">admonition icons</a> have been enabled):</p><pre class="literallayout">[icons=None, caption="My Special Note"]
|
|
618
|
+
NOTE: This is my special note.</pre><p>This subsection also applies to <a 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
|
|
619
|
+
delimiter lines (normally a series of four or more repeated
|
|
620
|
+
characters). The behavior of Delimited Blocks is specified by entries
|
|
621
|
+
in configuration file <code class="literal">[blockdef*]</code> sections.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_predefined_delimited_blocks"></a>12.1. Predefined Delimited Blocks</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> ships with a number of predefined DelimitedBlocks (see the
|
|
622
|
+
<code class="literal">asciidoc.conf</code> configuration file in the <code class="literal">asciidoc(1)</code> program
|
|
623
|
+
directory):</p><p>Predefined delimited block underlines:</p><pre class="literallayout">CommentBlock: //////////////////////////
|
|
624
|
+
PassthroughBlock: ++++++++++++++++++++++++++
|
|
625
|
+
ListingBlock: --------------------------
|
|
626
|
+
LiteralBlock: ..........................
|
|
627
|
+
SidebarBlock: **************************
|
|
628
|
+
QuoteBlock: __________________________
|
|
629
|
+
ExampleBlock: ==========================
|
|
630
|
+
Filter blocks: ~~~~~~~~~~~~~~~~~~~~~~~~~~</pre><p>The <a href="#X56" title="27.3. Code Filter">code</a>, <a href="#X57" title="27.4. Source Code Highlighter Filter">source</a> and <a href="#X58" title="27.5. Music Filter">music</a> filter blocks are
|
|
631
|
+
detailed in the <a href="#X59" title="27. Filters">Filters</a> section.</p><div class="table"><a id="id2539468"></a><p class="title"><b>Table 1. Default DelimitedBlock substitutions</b></p><div class="table-contents"><table summary="Default DelimitedBlock substitutions" cellpadding="4px" border="0" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; "><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /></colgroup><thead><tr><th style="" align="left">
|
|
632
|
+
</th><th style="" align="center">
|
|
633
|
+
Passthrough
|
|
634
|
+
</th><th style="" align="center">
|
|
635
|
+
Listing
|
|
636
|
+
</th><th style="" align="center">
|
|
637
|
+
Literal
|
|
638
|
+
</th><th style="" align="center">
|
|
639
|
+
Sidebar
|
|
640
|
+
</th><th style="" align="center">
|
|
641
|
+
Quote
|
|
642
|
+
</th></tr></thead><tbody><tr><td style="" align="left">
|
|
643
|
+
Callouts
|
|
644
|
+
</td><td style="" align="center">
|
|
645
|
+
No
|
|
646
|
+
</td><td style="" align="center">
|
|
647
|
+
Yes
|
|
648
|
+
</td><td style="" align="center">
|
|
649
|
+
Yes
|
|
650
|
+
</td><td style="" align="center">
|
|
651
|
+
No
|
|
652
|
+
</td><td style="" align="center">
|
|
653
|
+
No
|
|
654
|
+
</td></tr><tr><td style="" align="left">
|
|
655
|
+
Attributes
|
|
656
|
+
</td><td style="" align="center">
|
|
657
|
+
Yes
|
|
658
|
+
</td><td style="" align="center">
|
|
659
|
+
No
|
|
660
|
+
</td><td style="" align="center">
|
|
661
|
+
No
|
|
662
|
+
</td><td style="" align="center">
|
|
663
|
+
Yes
|
|
664
|
+
</td><td style="" align="center">
|
|
665
|
+
Yes
|
|
666
|
+
</td></tr><tr><td style="" align="left">
|
|
667
|
+
Inline Macros
|
|
668
|
+
</td><td style="" align="center">
|
|
669
|
+
Yes
|
|
670
|
+
</td><td style="" align="center">
|
|
671
|
+
No
|
|
672
|
+
</td><td style="" align="center">
|
|
673
|
+
No
|
|
674
|
+
</td><td style="" align="center">
|
|
675
|
+
Yes
|
|
676
|
+
</td><td style="" align="center">
|
|
677
|
+
Yes
|
|
678
|
+
</td></tr><tr><td style="" align="left">
|
|
679
|
+
Quotes
|
|
680
|
+
</td><td style="" align="center">
|
|
681
|
+
No
|
|
682
|
+
</td><td style="" align="center">
|
|
683
|
+
No
|
|
684
|
+
</td><td style="" align="center">
|
|
685
|
+
No
|
|
686
|
+
</td><td style="" align="center">
|
|
687
|
+
Yes
|
|
688
|
+
</td><td style="" align="center">
|
|
689
|
+
Yes
|
|
690
|
+
</td></tr><tr><td style="" align="left">
|
|
691
|
+
Replacements
|
|
692
|
+
</td><td style="" align="center">
|
|
693
|
+
No
|
|
694
|
+
</td><td style="" align="center">
|
|
695
|
+
No
|
|
696
|
+
</td><td style="" align="center">
|
|
697
|
+
No
|
|
698
|
+
</td><td style="" align="center">
|
|
699
|
+
Yes
|
|
700
|
+
</td><td style="" align="center">
|
|
701
|
+
Yes
|
|
702
|
+
</td></tr><tr><td style="" align="left">
|
|
703
|
+
Special chars
|
|
704
|
+
</td><td style="" align="center">
|
|
705
|
+
No
|
|
706
|
+
</td><td style="" align="center">
|
|
707
|
+
Yes
|
|
708
|
+
</td><td style="" align="center">
|
|
709
|
+
Yes
|
|
710
|
+
</td><td style="" align="center">
|
|
711
|
+
Yes
|
|
712
|
+
</td><td style="" align="center">
|
|
713
|
+
Yes
|
|
714
|
+
</td></tr><tr><td style="" align="left">
|
|
715
|
+
Special words
|
|
716
|
+
</td><td style="" align="center">
|
|
717
|
+
No
|
|
718
|
+
</td><td style="" align="center">
|
|
719
|
+
No
|
|
720
|
+
</td><td style="" align="center">
|
|
721
|
+
No
|
|
722
|
+
</td><td style="" align="center">
|
|
723
|
+
Yes
|
|
724
|
+
</td><td style="" align="center">
|
|
725
|
+
Yes
|
|
726
|
+
</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
|
|
727
|
+
line and whitespace formatting and often distinguished by a background
|
|
728
|
+
or border. There is no text formatting or substitutions within Listing
|
|
729
|
+
blocks apart from Special Characters and Callouts. Listing blocks are
|
|
730
|
+
often used for code and file listings.</p><p>Here's an example:</p><pre class="literallayout">--------------------------------------
|
|
731
|
+
#include <stdio.h></pre><pre class="literallayout">int main() {
|
|
732
|
+
printf("Hello World!\n");
|
|
733
|
+
exit(0);
|
|
734
|
+
}
|
|
735
|
+
--------------------------------------</pre><p>Which will be rendered like:</p><pre class="screen">#include <stdio.h>
|
|
736
|
+
|
|
737
|
+
int main() {
|
|
738
|
+
printf("Hello World!\n");
|
|
739
|
+
exit(0);
|
|
740
|
+
}</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X65"></a>12.3. Literal Blocks</h3></div></div></div><p>LiteralBlocks behave just like LiteralParagraphs except you don't have
|
|
741
|
+
to indent the contents.</p><p>LiteralBlocks can be used to resolve list ambiguity. If the following
|
|
742
|
+
list was just indented it would be processed as an ordered list (not
|
|
743
|
+
an indented paragraph):</p><pre class="screen">....................
|
|
744
|
+
1. Item 1
|
|
745
|
+
2. Item 2
|
|
746
|
+
....................</pre><p>Renders:</p><pre class="literallayout">1. Item 1
|
|
747
|
+
2. Item 2</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_sidebarblocks"></a>12.4. SidebarBlocks</h3></div></div></div><p>A sidebar is a short piece of text presented outside the narrative
|
|
748
|
+
flow of the main text. The sidebar is normally presented inside a
|
|
749
|
+
bordered box to set it apart from the main text.</p><p>The sidebar body is treated like a normal section body.</p><p>Here's an example:</p><pre class="screen">.An Example Sidebar
|
|
750
|
+
************************************************
|
|
751
|
+
Any AsciiDoc SectionBody element (apart from
|
|
752
|
+
SidebarBlocks) can be placed inside a sidebar.
|
|
753
|
+
************************************************</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
|
|
754
|
+
SidebarBlocks) can be placed inside a sidebar.</p></div></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
|
|
755
|
+
annotations and for excluding new or outdated content that you don't
|
|
756
|
+
want displayed. Here's and example:</p><pre class="screen">//////////////////////////////////////////
|
|
757
|
+
CommentBlock contents are not processed by
|
|
758
|
+
asciidoc(1).
|
|
759
|
+
//////////////////////////////////////////</pre><p>See also <a 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="_passthrough_blocks"></a>12.6. Passthrough Blocks</h3></div></div></div><p>PassthroughBlocks are for backend specific markup, text is only
|
|
760
|
+
subject to attribute and macro substitution. PassthroughBlock content
|
|
761
|
+
will generally be backend specific. Here's an example:</p><pre class="screen">++++++++++++++++++++++++++++++++++++++
|
|
762
|
+
<table border="1"><tr>
|
|
763
|
+
<td>Cell 1</td>
|
|
764
|
+
<td>Cell 2</td>
|
|
765
|
+
</tr></table>
|
|
766
|
+
++++++++++++++++++++++++++++++++++++++</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_quote_blocks"></a>12.7. Quote Blocks</h3></div></div></div><p>QuoteBlocks are used for quoted passages of text. There are two
|
|
767
|
+
styles: <span class="emphasis"><em>quote</em></span> and <span class="emphasis"><em>verse</em></span> (the first positional attribute). The
|
|
768
|
+
<span class="emphasis"><em>attribution</em></span> and <span class="emphasis"><em>citetitle</em></span> attributes (positional attributes 2 and
|
|
769
|
+
3) specify the content author and source. If no attributes are
|
|
770
|
+
specified the <span class="emphasis"><em>quote</em></span> style is used.</p><p>The <span class="emphasis"><em>quote</em></span> style treats the content like a SectionBody, for example:</p><pre class="screen">[quote, Bertrand Russell, The World of Mathematics (1956)]
|
|
771
|
+
____________________________________________________________________
|
|
772
|
+
A good notation has subtlety and suggestiveness which at times makes
|
|
773
|
+
it almost seem like a live teacher.
|
|
774
|
+
____________________________________________________________________</pre><p>Which is rendered as:</p><div class="blockquote"><table border="0" width="100%" cellspacing="0" cellpadding="0" class="blockquote" summary="Block quote"><tr><td width="10%" valign="top"> </td><td width="80%" valign="top"><p>A good notation has subtlety and suggestiveness which at times makes
|
|
775
|
+
it almost seem like a live teacher.</p></td><td width="10%" valign="top"> </td></tr><tr><td width="10%" valign="top"> </td><td colspan="2" align="right" valign="top">--<span class="attribution">
|
|
776
|
+
Bertrand Russell
|
|
777
|
+
<em class="citetitle">The World of Mathematics (1956)</em>
|
|
778
|
+
</span></td></tr></table></div><p>The <span class="emphasis"><em>verse</em></span> style
|
|
779
|
+
retains the content's line breaks, for example:</p><pre class="screen">[verse, William Blake, from Auguries of Innocence]
|
|
780
|
+
__________________________________________________
|
|
781
|
+
To see a world in a grain of sand,
|
|
782
|
+
And a heaven in a wild flower,
|
|
783
|
+
Hold infinity in the palm of your hand,
|
|
784
|
+
And eternity in an hour.
|
|
785
|
+
__________________________________________________</pre><p>Which is rendered as:</p><div class="blockquote"><table border="0" width="100%" cellspacing="0" cellpadding="0" class="blockquote" summary="Block quote"><tr><td width="10%" valign="top"> </td><td width="80%" valign="top"><div class="literallayout"><p>To see a world in a grain of sand,<br />
|
|
786
|
+
And a heaven in a wild flower,<br />
|
|
787
|
+
Hold infinity in the palm of your hand,<br />
|
|
788
|
+
And eternity in an hour.</p></div></td><td width="10%" valign="top"> </td></tr><tr><td width="10%" valign="top"> </td><td colspan="2" align="right" valign="top">--<span class="attribution">
|
|
789
|
+
William Blake
|
|
790
|
+
<em class="citetitle">from Auguries of Innocence</em>
|
|
791
|
+
</span></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X48"></a>12.8. Example Blocks</h3></div></div></div><p>ExampleBlocks encapsulate the DocBook Example element and are used
|
|
792
|
+
for, well, examples. Example blocks can be titled by preceding them
|
|
793
|
+
with a <span class="emphasis"><em>BlockTitle</em></span>. DocBook toolchains normally number examples and
|
|
794
|
+
generate a <span class="emphasis"><em>List of Examples</em></span> backmatter section.</p><p>Example blocks are delimited by lines of equals characters and you can
|
|
795
|
+
put any block elements apart from Titles, BlockTitles and Sidebars)
|
|
796
|
+
inside an example block. For example:</p><pre class="screen">.An example
|
|
797
|
+
=====================================================================
|
|
798
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
799
|
+
adolescens.
|
|
800
|
+
=====================================================================</pre><p>Renders:</p><div class="example"><a id="id2540162"></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
|
|
801
|
+
adolescens.</p></div></div><br class="example-break" /><p>The title prefix that is automatically inserted by <code class="literal">asciidoc(1)</code> can be
|
|
802
|
+
customized with the <code class="literal">caption</code> attribute (<code class="literal">xhtml11</code> and <code class="literal">html4</code>
|
|
803
|
+
backends). For example</p><pre class="screen">[caption="Example 1: "]
|
|
804
|
+
.An example with a custom caption
|
|
805
|
+
=====================================================================
|
|
806
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
807
|
+
adolescens.
|
|
808
|
+
=====================================================================</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X22"></a>12.9. Admonition Blocks</h3></div></div></div><p>The ExampleBlock definition includes a set of admonition
|
|
809
|
+
<a href="#X23" title="26.1. Styles">styles</a> (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating
|
|
810
|
+
admonition blocks (admonitions containing more than just a
|
|
811
|
+
<a href="#X28" title="11.3. Admonition Paragraphs">simple paragraph</a>). Just precede the ExampleBlock with an
|
|
812
|
+
attribute list containing the admonition style name. For example:</p><pre class="screen">[NOTE]
|
|
813
|
+
.A NOTE block
|
|
814
|
+
=====================================================================
|
|
815
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
816
|
+
adolescens.
|
|
817
|
+
|
|
818
|
+
. Fusce euismod commodo velit.
|
|
819
|
+
. Vivamus fringilla mi eu lacus.
|
|
820
|
+
.. Fusce euismod commodo velit.
|
|
821
|
+
.. Vivamus fringilla mi eu lacus.
|
|
822
|
+
. Donec eget arcu bibendum
|
|
823
|
+
nunc consequat lobortis.
|
|
824
|
+
=====================================================================</pre><p>Renders:</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note: A NOTE block"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left">A NOTE block</th></tr><tr><td align="left" valign="top"><p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
825
|
+
adolescens.</p><div class="orderedlist"><ol type="1"><li>
|
|
826
|
+
Fusce euismod commodo velit.
|
|
827
|
+
</li><li><p>
|
|
828
|
+
Vivamus fringilla mi eu lacus.
|
|
829
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
830
|
+
Fusce euismod commodo velit.
|
|
831
|
+
</li><li>
|
|
832
|
+
Vivamus fringilla mi eu lacus.
|
|
833
|
+
</li></ol></div></li><li>
|
|
834
|
+
Donec eget arcu bibendum
|
|
835
|
+
nunc consequat lobortis.
|
|
836
|
+
</li></ol></div></td></tr></table></div><p>See also <a href="#X47" title="11.3.1. Admonition Icons and Captions">Admonition Icons and Captions</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="X64"></a>13. Lists</h2></div></div></div><div class="itemizedlist"><p class="title"><b>List types</b></p><ul type="disc"><li>
|
|
837
|
+
Bulleted lists. Also known as itemized or unordered lists.
|
|
838
|
+
</li><li>
|
|
839
|
+
Numbered lists. Also called ordered lists.
|
|
840
|
+
</li><li>
|
|
841
|
+
Labeled lists. Sometimes called variable or definition lists.
|
|
842
|
+
</li><li>
|
|
843
|
+
Callout lists (a list of callout annotations).
|
|
844
|
+
</li></ul></div><div class="itemizedlist"><p class="title"><b>List behavior</b></p><ul type="disc"><li>
|
|
845
|
+
Indentation is optional and does not determine nesting, indentation
|
|
846
|
+
does however make the source more readable.
|
|
847
|
+
</li><li>
|
|
848
|
+
A nested list must use a different syntax from its parent so that
|
|
849
|
+
<code class="literal">asciidoc(1)</code> can distinguish the start of a nested list.
|
|
850
|
+
</li><li>
|
|
851
|
+
By default lists of the same type can only be nested two deep; this
|
|
852
|
+
could be increased by defining new list definitions.
|
|
853
|
+
</li><li>
|
|
854
|
+
In addition to nested lists a list item will include immediately
|
|
855
|
+
following Literal paragraphs.
|
|
856
|
+
</li><li>
|
|
857
|
+
Use <a href="#X15" title="13.7. List Item Continuation">List Item Continuation</a> to include other block elements
|
|
858
|
+
in a list item.
|
|
859
|
+
</li><li>
|
|
860
|
+
The <code class="literal">listindex</code> <a href="#X60" title="25. Intrinsic Attributes">intrinsic attribute</a> is the current list item
|
|
861
|
+
index (1..). If this attribute is not inside a list then it's value
|
|
862
|
+
is the number of items in the most recently closed list. Useful for
|
|
863
|
+
displaying the number of items in a list.
|
|
864
|
+
</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
|
|
865
|
+
space or tab character. Bulleted list syntaxes are:</p><pre class="literallayout">- List item.
|
|
866
|
+
* List item.</pre><p>Numbered list items start with an optional number or letter followed
|
|
867
|
+
by a period followed by a space or tab character. List numbering is
|
|
868
|
+
optional. Numbered list syntaxes are:</p><pre class="literallayout">. Integer numbered list item.
|
|
869
|
+
1. Integer numbered list item with optional numbering.
|
|
870
|
+
.. Lowercase letter numbered list item.
|
|
871
|
+
a. Lowercase letter numbered list item with optional numbering.</pre><p>Here are some examples:</p><pre class="screen">- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
872
|
+
* Fusce euismod commodo velit.
|
|
873
|
+
* Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
874
|
+
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
875
|
+
vel.
|
|
876
|
+
* Vivamus fringilla mi eu lacus.
|
|
877
|
+
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
878
|
+
- Nulla porttitor vulputate libero.
|
|
879
|
+
. Fusce euismod commodo velit.
|
|
880
|
+
. Vivamus fringilla mi eu lacus.
|
|
881
|
+
.. Fusce euismod commodo velit.
|
|
882
|
+
.. Vivamus fringilla mi eu lacus.
|
|
883
|
+
. Donec eget arcu bibendum nunc consequat lobortis.
|
|
884
|
+
- Praesent eget purus quis magna eleifend eleifend.
|
|
885
|
+
1. Fusce euismod commodo velit.
|
|
886
|
+
a. Fusce euismod commodo velit.
|
|
887
|
+
b. Vivamus fringilla mi eu lacus.
|
|
888
|
+
c. Donec eget arcu bibendum nunc consequat lobortis.
|
|
889
|
+
2. Vivamus fringilla mi eu lacus.
|
|
890
|
+
3. Donec eget arcu bibendum nunc consequat lobortis.
|
|
891
|
+
4. Nam fermentum mattis ante.</pre><p>Which render as:</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
892
|
+
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
893
|
+
</p><div class="itemizedlist"><ul type="circle"><li>
|
|
894
|
+
Fusce euismod commodo velit.
|
|
895
|
+
</li><li>
|
|
896
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
897
|
+
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
898
|
+
vel.
|
|
899
|
+
</li><li>
|
|
900
|
+
Vivamus fringilla mi eu lacus.
|
|
901
|
+
</li><li>
|
|
902
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
903
|
+
</li></ul></div></li><li><p>
|
|
904
|
+
Nulla porttitor vulputate libero.
|
|
905
|
+
</p><div class="orderedlist"><ol type="1"><li>
|
|
906
|
+
Fusce euismod commodo velit.
|
|
907
|
+
</li><li><p>
|
|
908
|
+
Vivamus fringilla mi eu lacus.
|
|
909
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
910
|
+
Fusce euismod commodo velit.
|
|
911
|
+
</li><li>
|
|
912
|
+
Vivamus fringilla mi eu lacus.
|
|
913
|
+
</li></ol></div></li><li>
|
|
914
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
915
|
+
</li></ol></div></li><li><p>
|
|
916
|
+
Praesent eget purus quis magna eleifend eleifend.
|
|
917
|
+
</p><div class="orderedlist"><ol type="1"><li><p>
|
|
918
|
+
Fusce euismod commodo velit.
|
|
919
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
920
|
+
Fusce euismod commodo velit.
|
|
921
|
+
</li><li>
|
|
922
|
+
Vivamus fringilla mi eu lacus.
|
|
923
|
+
</li><li>
|
|
924
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
925
|
+
</li></ol></div></li><li>
|
|
926
|
+
Vivamus fringilla mi eu lacus.
|
|
927
|
+
</li><li>
|
|
928
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
929
|
+
</li><li>
|
|
930
|
+
Nam fermentum mattis ante.
|
|
931
|
+
</li></ol></div></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_vertical_labeled_lists"></a>13.2. Vertical Labeled Lists</h3></div></div></div><p>Labeled list items consist of one or more text labels followed the
|
|
932
|
+
text of the list item.</p><p>An item label begins a line with an alphanumeric character hard
|
|
933
|
+
against the left margin and ends with a double colon <code class="literal">::</code> or
|
|
934
|
+
semi-colon <code class="literal">;;</code>.</p><p>The list item text consists of one or more lines of text starting on
|
|
935
|
+
the line immediately following the label and can be followed by nested
|
|
936
|
+
List or ListParagraph elements. Item text can be optionally indented.</p><p>Here are some examples:</p><pre class="screen">Lorem::
|
|
937
|
+
Fusce euismod commodo velit.
|
|
938
|
+
|
|
939
|
+
Fusce euismod commodo velit.
|
|
940
|
+
|
|
941
|
+
Ipsum::
|
|
942
|
+
Vivamus fringilla mi eu lacus.
|
|
943
|
+
* Vivamus fringilla mi eu lacus.
|
|
944
|
+
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
945
|
+
Dolor::
|
|
946
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
947
|
+
Suspendisse;;
|
|
948
|
+
A massa id sem aliquam auctor.
|
|
949
|
+
Morbi;;
|
|
950
|
+
Pretium nulla vel lorem.
|
|
951
|
+
In;;
|
|
952
|
+
Dictum mauris in urna.</pre><p>Which render as:</p><div class="variablelist"><dl><dt><span class="term">
|
|
953
|
+
Lorem
|
|
954
|
+
</span></dt><dd><p>
|
|
955
|
+
Fusce euismod commodo velit.
|
|
956
|
+
</p><pre class="literallayout">Fusce euismod commodo velit.</pre></dd><dt><span class="term">
|
|
957
|
+
Ipsum
|
|
958
|
+
</span></dt><dd><p>
|
|
959
|
+
Vivamus fringilla mi eu lacus.
|
|
960
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
961
|
+
Vivamus fringilla mi eu lacus.
|
|
962
|
+
</li><li>
|
|
963
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
964
|
+
</li></ul></div></dd><dt><span class="term">
|
|
965
|
+
Dolor
|
|
966
|
+
</span></dt><dd><p>
|
|
967
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
968
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
969
|
+
Suspendisse
|
|
970
|
+
</span></dt><dd>
|
|
971
|
+
A massa id sem aliquam auctor.
|
|
972
|
+
</dd><dt><span class="term">
|
|
973
|
+
Morbi
|
|
974
|
+
</span></dt><dd>
|
|
975
|
+
Pretium nulla vel lorem.
|
|
976
|
+
</dd><dt><span class="term">
|
|
977
|
+
In
|
|
978
|
+
</span></dt><dd>
|
|
979
|
+
Dictum mauris in urna.
|
|
980
|
+
</dd></dl></div></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_horizontal_labeled_lists"></a>13.3. Horizontal Labeled Lists</h3></div></div></div><p>Horizontal labeled lists differ from vertical labeled lists in that
|
|
981
|
+
the label and the list item sit side-by-side as opposed to the item
|
|
982
|
+
under the label. Item text must begin on the same line as the label
|
|
983
|
+
although you can begin item text on the next line if you follow the
|
|
984
|
+
label with a backslash.</p><p>The following horizontal list example also illustrates the omission
|
|
985
|
+
of optional indentation:</p><pre class="screen">*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
|
|
986
|
+
labitur dolorum an. Est ne magna primis adolescens.
|
|
987
|
+
|
|
988
|
+
Fusce euismod commodo velit.
|
|
989
|
+
|
|
990
|
+
*Ipsum*:: Vivamus fringilla mi eu lacus.
|
|
991
|
+
- Vivamus fringilla mi eu lacus.
|
|
992
|
+
- Donec eget arcu bibendum nunc consequat lobortis.
|
|
993
|
+
|
|
994
|
+
*Dolor*:: \
|
|
995
|
+
- Vivamus fringilla mi eu lacus.
|
|
996
|
+
- Donec eget arcu bibendum nunc consequat lobortis.</pre><p>Which render as:</p><div class="hlabeledlist"><table cellpadding="4px" border="0" style="border-collapse: collapse;"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td style="" valign="top"><p>
|
|
997
|
+
<span class="strong"><strong>Lorem</strong></span>
|
|
998
|
+
</p></td><td style="" valign="top">
|
|
999
|
+
<p>
|
|
1000
|
+
Fusce euismod commodo velit. Qui in magna commodo, est
|
|
1001
|
+
labitur dolorum an. Est ne magna primis adolescens.
|
|
1002
|
+
</p>
|
|
1003
|
+
<pre class="literallayout">Fusce euismod commodo velit.</pre>
|
|
1004
|
+
</td></tr><tr><td style="" valign="top"><p>
|
|
1005
|
+
<span class="strong"><strong>Ipsum</strong></span>
|
|
1006
|
+
</p></td><td style="" valign="top">
|
|
1007
|
+
<p>
|
|
1008
|
+
Vivamus fringilla mi eu lacus.
|
|
1009
|
+
</p>
|
|
1010
|
+
<div class="itemizedlist"><ul type="disc"><li>
|
|
1011
|
+
Vivamus fringilla mi eu lacus.
|
|
1012
|
+
</li><li>
|
|
1013
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
1014
|
+
</li></ul></div>
|
|
1015
|
+
</td></tr><tr><td style="" valign="top"><p>
|
|
1016
|
+
<span class="strong"><strong>Dolor</strong></span>
|
|
1017
|
+
</p></td><td style="" valign="top">
|
|
1018
|
+
<div class="itemizedlist"><ul type="disc"><li>
|
|
1019
|
+
Vivamus fringilla mi eu lacus.
|
|
1020
|
+
</li><li>
|
|
1021
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
1022
|
+
</li></ul></div>
|
|
1023
|
+
</td></tr></tbody></table></div><div class="warning" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="./images/icons/warning.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><div class="itemizedlist"><ul type="disc"><li>
|
|
1024
|
+
Use vertical labeled lists in preference to horizontal labeled lists
|
|
1025
|
+
— current PDF toolchains do not make a good job of determining
|
|
1026
|
+
the relative column widths.
|
|
1027
|
+
</li><li>
|
|
1028
|
+
If you are generating DocBook markup the horizontal labeled lists
|
|
1029
|
+
should not be nested because the <span class="emphasis"><em>DocBook XML V4.2</em></span> DTD does not
|
|
1030
|
+
permit nested informal tables (although <a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a> process them correctly).
|
|
1031
|
+
</li></ul></div></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_question_and_answer_lists"></a>13.4. Question and Answer Lists</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes pre-configured with a labeled list for generating
|
|
1032
|
+
DocBook question and answer (Q&A) lists (<code class="literal">??</code> label delimiter).
|
|
1033
|
+
Example:</p><pre class="screen">Question one??
|
|
1034
|
+
Answer one.
|
|
1035
|
+
Question two??
|
|
1036
|
+
Answer two.</pre><p>Renders:</p><div class="qandaset"><dl><dt>13.4.1. <a href="#id2541250">
|
|
1037
|
+
Question one
|
|
1038
|
+
</a></dt><dt>13.4.2. <a href="#id2541265">
|
|
1039
|
+
Question two
|
|
1040
|
+
</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="id2541250"></a><a id="id2541252"></a><p><b>13.4.1.</b></p></td><td align="left" valign="top"><p>
|
|
1041
|
+
Question one
|
|
1042
|
+
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
|
|
1043
|
+
Answer one.
|
|
1044
|
+
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="id2541265"></a><a id="id2541267"></a><p><b>13.4.2.</b></p></td><td align="left" valign="top"><p>
|
|
1045
|
+
Question two
|
|
1046
|
+
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
|
|
1047
|
+
Answer two.
|
|
1048
|
+
</p></td></tr></tbody></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_glossary_lists"></a>13.5. Glossary Lists</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes pre-configured with a labeled list (<code class="literal">:-</code> label
|
|
1049
|
+
delimiter) for generating DocBook glossary lists. Example:</p><pre class="screen">A glossary term:-
|
|
1050
|
+
The corresponding definition.
|
|
1051
|
+
A second glossary term:-
|
|
1052
|
+
The corresponding definition.</pre><p>For working examples see the <code class="literal">article.txt</code> and <code class="literal">book.txt</code> documents in
|
|
1053
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">./doc</code> distribution directory.</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>To generate valid DocBook output glossary lists must be located
|
|
1054
|
+
in a glossary section.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_bibliography_lists"></a>13.6. Bibliography Lists</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes with a predefined itemized list (<code class="literal">+</code> item bullet) for
|
|
1055
|
+
generating bibliography entries. Example:</p><pre class="screen">+ [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
|
|
1056
|
+
Programming'. Addison-Wesley. ISBN 0-13-142901-9.
|
|
1057
|
+
+ [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
|
|
1058
|
+
'DocBook - The Definitive Guide'. O'Reilly & Associates.
|
|
1059
|
+
1999. ISBN 1-56592-580-7.</pre><p>The <code class="literal">[[[<reference>]]]</code> syntax is a bibliography entry anchor, it
|
|
1060
|
+
generates an anchor named <code class="literal"><reference></code> and additionally displays
|
|
1061
|
+
<code class="literal">[<reference>]</code> at the anchor position. For example <code class="literal">[[[taoup]]]</code>
|
|
1062
|
+
generates an anchor named <code class="literal">taoup</code> that displays <code class="literal">[taoup]</code> at the
|
|
1063
|
+
anchor position. Cite the reference from elsewhere your document using
|
|
1064
|
+
<code class="literal"><<taoup>></code>, this displays a hyperlink (<code class="literal">[taoup]</code>) to the
|
|
1065
|
+
corresponding bibliography entry anchor.</p><p>For working examples see the <code class="literal">article.txt</code> and <code class="literal">book.txt</code> documents in
|
|
1066
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">./doc</code> distribution directory.</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>To generate valid DocBook output bibliography lists must be
|
|
1067
|
+
located in a bibliography section.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X15"></a>13.7. List Item Continuation</h3></div></div></div><p>To include subsequent block elements in list items (in addition to
|
|
1068
|
+
implicitly included nested lists and Literal paragraphs) place a
|
|
1069
|
+
separator line containing a single plus character between the list
|
|
1070
|
+
item and the ensuing list continuation element. Multiple block
|
|
1071
|
+
elements (excluding section Titles and BlockTitles) may be included in
|
|
1072
|
+
a list item using this technique. For example:</p><p>Here's an example of list item continuation:</p><pre class="screen">1. List item one.
|
|
1073
|
+
+
|
|
1074
|
+
List item one continued with a second paragraph followed by an
|
|
1075
|
+
Indented block.
|
|
1076
|
+
+
|
|
1077
|
+
.................
|
|
1078
|
+
$ ls *.sh
|
|
1079
|
+
$ mv *.sh ~/tmp
|
|
1080
|
+
.................
|
|
1081
|
+
+
|
|
1082
|
+
List item one continued with a third paragraph.
|
|
1083
|
+
|
|
1084
|
+
2. List item two.
|
|
1085
|
+
|
|
1086
|
+
List item two literal paragraph (no continuation required).
|
|
1087
|
+
|
|
1088
|
+
- Nested list (item one).
|
|
1089
|
+
|
|
1090
|
+
Nested list literal paragraph (no continuation required).
|
|
1091
|
+
+
|
|
1092
|
+
Nested list appended list item one paragraph
|
|
1093
|
+
|
|
1094
|
+
- Nested list item two.</pre><p>Renders:</p><div class="orderedlist"><ol type="1"><li><p>
|
|
1095
|
+
List item one.
|
|
1096
|
+
</p><p>List item one continued with a second paragraph followed by a Listing
|
|
1097
|
+
block.</p><pre class="literallayout">$ ls *.sh
|
|
1098
|
+
$ mv *.sh ~/tmp</pre><p>List item one continued with a third paragraph.</p></li><li><p>
|
|
1099
|
+
List item two.
|
|
1100
|
+
</p><pre class="literallayout">List item two literal paragraph (no continuation required).</pre><div class="itemizedlist"><ul type="disc"><li><p>
|
|
1101
|
+
Nested list (item one).
|
|
1102
|
+
</p><pre class="literallayout">Nested list literal paragraph (no continuation required).</pre><p>Nested list appended list item one paragraph</p></li><li>
|
|
1103
|
+
Nested list item two.
|
|
1104
|
+
</li></ul></div></li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X29"></a>13.8. List Block</h3></div></div></div><p>A List block is a special delimited block containing a list element.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1105
|
+
All elements between in the List Block are part of the preceding
|
|
1106
|
+
list item. In this respect the List block behaves like <a href="#X15" title="13.7. List Item Continuation">List Item Continuation</a> except that list items contained within the
|
|
1107
|
+
block do not require explicit <code class="literal">+</code> list item continuation lines:
|
|
1108
|
+
</li><li>
|
|
1109
|
+
The block delimiter is a single line containing two dashes.
|
|
1110
|
+
</li><li>
|
|
1111
|
+
Any block title or attributes are passed to the first element inside
|
|
1112
|
+
the block.
|
|
1113
|
+
</li></ul></div><p>The List Block is useful for:</p><div class="orderedlist"><ol type="1"><li>
|
|
1114
|
+
Lists with long multi-element list items.
|
|
1115
|
+
</li><li>
|
|
1116
|
+
Nesting a list within a parent list item (by default nested lists
|
|
1117
|
+
follow the preceding list item).
|
|
1118
|
+
</li></ol></div><p>Here's an example of a nested list block:</p><pre class="screen">.Nested List Block
|
|
1119
|
+
1. List item one.
|
|
1120
|
+
+
|
|
1121
|
+
This paragraph is part of the preceding list item
|
|
1122
|
+
+
|
|
1123
|
+
--
|
|
1124
|
+
a. This list is nested and does not require explicit item continuation.
|
|
1125
|
+
|
|
1126
|
+
This paragraph is part of the preceding list item
|
|
1127
|
+
|
|
1128
|
+
b. List item b.
|
|
1129
|
+
|
|
1130
|
+
This paragraph belongs to list item b.
|
|
1131
|
+
--
|
|
1132
|
+
+
|
|
1133
|
+
This paragraph belongs to item 1.
|
|
1134
|
+
|
|
1135
|
+
2. Item 2 of the outer list.</pre><p>Renders:</p><div class="orderedlist"><p class="title"><b>Nested List Block</b></p><ol type="1"><li><p>
|
|
1136
|
+
List item one.
|
|
1137
|
+
</p><p>This paragraph is part of the preceding list item</p><div class="orderedlist"><ol type="a"><li><p>
|
|
1138
|
+
This list is nested and does not require explicit item continuation.
|
|
1139
|
+
</p><p>This paragraph is part of the preceding list item</p></li><li><p>
|
|
1140
|
+
List item b.
|
|
1141
|
+
</p><p>This paragraph belongs to list item b.</p></li></ol></div><p>This paragraph belongs to item 1.</p></li><li>
|
|
1142
|
+
Item 2 of the outer list.
|
|
1143
|
+
</li></ol></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_footnotes"></a>14. Footnotes</h2></div></div></div><p>The shipped <span class="emphasis"><em>AsciiDoc</em></span> configuration includes the <code class="literal">footnote:[<text>]</code>
|
|
1144
|
+
inline macro for generating footnotes. The footnote text can span
|
|
1145
|
+
multiple lines. Example footnote:</p><pre class="literallayout">A footnote footnote:[An example footnote.]</pre><p>Which renders:</p><p>A footnote <sup>[<a id="id2541843" href="#ftn.id2541843">2</a>]</sup></p><p>Footnotes are primarily useful when generating DocBook output —
|
|
1146
|
+
DocBook conversion programs render footnote outside the primary text
|
|
1147
|
+
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
|
|
1148
|
+
generating document index entries.</p><div class="variablelist"><dl><dt><span class="term">
|
|
1149
|
+
<code class="literal">indexterm:[<primary>,<secondary>,<tertiary>]</code>
|
|
1150
|
+
, </span><span class="term">
|
|
1151
|
+
<code class="literal">(((<primary>,<secondary>,<tertiary>)))</code>
|
|
1152
|
+
</span></dt><dd>
|
|
1153
|
+
This inline macro generates an index term (the <secondary> and
|
|
1154
|
+
<tertiary> attributes are optional). For example
|
|
1155
|
+
<code class="literal">indexterm:[Tigers,Big cats]</code> (or, using the alternative syntax
|
|
1156
|
+
<code class="literal">(((Tigers,Big cats)))</code>. Index terms that have secondary and
|
|
1157
|
+
tertiary entries also generate separate index terms for the
|
|
1158
|
+
secondary and tertiary entries. The index terms appear in the
|
|
1159
|
+
index, not the primary text flow.
|
|
1160
|
+
</dd><dt><span class="term">
|
|
1161
|
+
<code class="literal">indexterm2:[<primary>]</code>
|
|
1162
|
+
, </span><span class="term">
|
|
1163
|
+
<code class="literal">((<primary>))</code>
|
|
1164
|
+
</span></dt><dd>
|
|
1165
|
+
This inline macro generates an index term that appears in both the
|
|
1166
|
+
index and the primary text flow. The <code class="literal"><primary></code> should not be
|
|
1167
|
+
padded to the left or right with white space characters.
|
|
1168
|
+
</dd></dl></div><p>For working examples see the <code class="literal">article.txt</code> and <code class="literal">book.txt</code> documents in
|
|
1169
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">./doc</code> distribution directory.</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>Index entries only really make sense if you are generating
|
|
1170
|
+
DocBook markup — DocBook conversion programs automatically generate
|
|
1171
|
+
an index at the point an <span class="emphasis"><em>Index</em></span> section appears in source document.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_callouts"></a>16. Callouts</h2></div></div></div><p>Callouts are a mechanism for annotating verbatim text (source code,
|
|
1172
|
+
computer output and user input for example). Callout markers are
|
|
1173
|
+
placed inside the annotated text while the actual annotations are
|
|
1174
|
+
presented in a callout list after the annotated text. Here's an
|
|
1175
|
+
example:</p><pre class="screen">.MS-DOS directory listing
|
|
1176
|
+
.....................................................
|
|
1177
|
+
10/17/97 9:04 <DIR> bin
|
|
1178
|
+
10/16/97 14:11 <DIR> DOS <1>
|
|
1179
|
+
10/16/97 14:40 <DIR> Program Files
|
|
1180
|
+
10/16/97 14:46 <DIR> TEMP
|
|
1181
|
+
10/17/97 9:04 <DIR> tmp
|
|
1182
|
+
10/16/97 14:37 <DIR> WINNT
|
|
1183
|
+
10/16/97 14:25 119 AUTOEXEC.BAT <2>
|
|
1184
|
+
2/13/94 6:21 54,619 COMMAND.COM <2>
|
|
1185
|
+
10/16/97 14:25 115 CONFIG.SYS <2>
|
|
1186
|
+
11/16/97 17:17 61,865,984 pagefile.sys
|
|
1187
|
+
2/13/94 6:21 9,349 WINA20.386 <3>
|
|
1188
|
+
.....................................................
|
|
1189
|
+
|
|
1190
|
+
<1> This directory holds MS-DOS.
|
|
1191
|
+
<2> System startup code for DOS.
|
|
1192
|
+
<3> Some sort of Windows 3.1 hack.</pre><p>Which renders:</p><div class="example"><a id="id2542065"></a><p class="title"><b>Example 2. MS-DOS directory listing</b></p><div class="example-contents"><pre class="literallayout">10/17/97 9:04 <DIR> bin
|
|
1193
|
+
10/16/97 14:11 <DIR> DOS <a id="CO1-1"></a><img src="./images/icons/callouts/1.png" alt="1" border="0" />
|
|
1194
|
+
10/16/97 14:40 <DIR> Program Files
|
|
1195
|
+
10/16/97 14:46 <DIR> TEMP
|
|
1196
|
+
10/17/97 9:04 <DIR> tmp
|
|
1197
|
+
10/16/97 14:37 <DIR> WINNT
|
|
1198
|
+
10/16/97 14:25 119 AUTOEXEC.BAT <a id="CO1-2"></a><img src="./images/icons/callouts/2.png" alt="2" border="0" />
|
|
1199
|
+
2/13/94 6:21 54,619 COMMAND.COM <a id="CO1-3"></a><img src="./images/icons/callouts/3.png" alt="3" border="0" />
|
|
1200
|
+
10/16/97 14:25 115 CONFIG.SYS <a id="CO1-4"></a><img src="./images/icons/callouts/4.png" alt="4" border="0" />
|
|
1201
|
+
11/16/97 17:17 61,865,984 pagefile.sys
|
|
1202
|
+
2/13/94 6:21 9,349 WINA20.386 <a id="CO1-5"></a><img src="./images/icons/callouts/5.png" alt="5" border="0" /></pre></div></div><br class="example-break" /><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-1"><img src="./images/icons/callouts/1.png" alt="1" border="0" /></a> </p></td><td valign="top" align="left">
|
|
1203
|
+
This directory holds MS-DOS.
|
|
1204
|
+
</td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-2"><img src="./images/icons/callouts/2.png" alt="2" border="0" /></a> <a href="#CO1-3"><img src="./images/icons/callouts/3.png" alt="3" border="0" /></a> <a href="#CO1-4"><img src="./images/icons/callouts/4.png" alt="4" border="0" /></a> </p></td><td valign="top" align="left">
|
|
1205
|
+
System startup code for DOS.
|
|
1206
|
+
</td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-5"><img src="./images/icons/callouts/5.png" alt="5" border="0" /></a> </p></td><td valign="top" align="left">
|
|
1207
|
+
Some sort of Windows 3.1 hack.
|
|
1208
|
+
</td></tr></table></div><div class="itemizedlist"><p class="title"><b>Explanation</b></p><ul type="disc"><li>
|
|
1209
|
+
The callout marks are whole numbers enclosed in angle brackets that
|
|
1210
|
+
refer to an item index in the following callout list.
|
|
1211
|
+
</li><li>
|
|
1212
|
+
By default callout marks are confined to LiteralParagraphs,
|
|
1213
|
+
LiteralBlocks and ListingBlocks (although this is a configuration
|
|
1214
|
+
file option and can be changed).
|
|
1215
|
+
</li><li>
|
|
1216
|
+
Callout list item numbering is fairly relaxed — list items can
|
|
1217
|
+
start with <code class="literal"><n></code>, <code class="literal">n></code> or <code class="literal">></code> where <code class="literal">n</code> is the optional list item
|
|
1218
|
+
number (in the latter case list items starting with a single <code class="literal">></code>
|
|
1219
|
+
character are implicitly numbered starting at one).
|
|
1220
|
+
</li><li>
|
|
1221
|
+
Callout lists should not be nested — start list items hard against
|
|
1222
|
+
the left margin.
|
|
1223
|
+
</li><li>
|
|
1224
|
+
If you want to present a number inside angle brackets you'll need to
|
|
1225
|
+
escape it with a backslash to prevent it being interpreted as a
|
|
1226
|
+
callout mark.
|
|
1227
|
+
</li></ul></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>To include callout icons in PDF files generated by
|
|
1228
|
+
<a href="#X43" title="28.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> you need to use the <code class="literal">—icons</code> command-line option.</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_implementation_notes"></a>16.1. Implementation Notes</h3></div></div></div><p>Callout marks are generated by the <span class="emphasis"><em>callout</em></span> inline macro while
|
|
1229
|
+
callout lists are generated using the <span class="emphasis"><em>callout</em></span> list definition. The
|
|
1230
|
+
<span class="emphasis"><em>callout</em></span> macro and <span class="emphasis"><em>callout</em></span> list are special in that they work
|
|
1231
|
+
together. The <span class="emphasis"><em>callout</em></span> inline macro is not enabled by the normal
|
|
1232
|
+
<span class="emphasis"><em>macros</em></span> substitutions option, instead it has its own <span class="emphasis"><em>callouts</em></span>
|
|
1233
|
+
substitution option.</p><p>The following attributes are available during inline callout macro
|
|
1234
|
+
substitution:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1235
|
+
<code class="literal">{index}</code>
|
|
1236
|
+
</span></dt><dd>
|
|
1237
|
+
The callout list item index inside the angle brackets.
|
|
1238
|
+
</dd><dt><span class="term">
|
|
1239
|
+
<code class="literal">{coid}</code>
|
|
1240
|
+
</span></dt><dd>
|
|
1241
|
+
An identifier formatted like <code class="literal">CO<listnumber>-<index></code> that
|
|
1242
|
+
uniquely identifies the callout mark. For example <code class="literal">CO2-4</code>
|
|
1243
|
+
identifies the fourth callout mark in the second set of callout
|
|
1244
|
+
marks.
|
|
1245
|
+
</dd></dl></div><p>The <code class="literal">{coids}</code> attribute can be used during callout list item
|
|
1246
|
+
substitution — it is a space delimited list of callout IDs that refer
|
|
1247
|
+
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
|
|
1248
|
+
to put the callouts inside source code comments. This example displays
|
|
1249
|
+
the <code class="literal">test.py</code> source file (containing a single callout) using the
|
|
1250
|
+
<a href="#X57" title="27.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>:</p><div class="example"><a id="id2542432"></a><p class="title"><b>Example 3. AsciiDoc source</b></p><div class="example-contents"><pre class="screen"> [source,python]
|
|
1251
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1252
|
+
include::test.py[]
|
|
1253
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1254
|
+
|
|
1255
|
+
<1> Print statement.</pre></div></div><br class="example-break" /><div class="example"><a id="id2542450"></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
|
|
1256
|
+
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
|
|
1257
|
+
list</em></span>. The default syntax is <code class="literal"><name>:<target>[<attributelist>]</code> (for
|
|
1258
|
+
inline macros) and <code class="literal"><name>::<target>[<attributelist>]</code> (for block
|
|
1259
|
+
macros). Here are some examples:</p><pre class="literallayout">http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
|
|
1260
|
+
include::chapt1.txt[tabsize=2]
|
|
1261
|
+
mailto:srackham@gmail.com[]</pre><div class="itemizedlist"><p class="title"><b>Macro behavior</b></p><ul type="disc"><li>
|
|
1262
|
+
<code class="literal"><name></code> is the macro name. It can only contain letters, digits or
|
|
1263
|
+
dash characters and cannot start with a dash.
|
|
1264
|
+
</li><li>
|
|
1265
|
+
The optional <code class="literal"><target></code> cannot contain white space characters.
|
|
1266
|
+
</li><li>
|
|
1267
|
+
<code class="literal"><attributelist></code> is a <a href="#X21" title="23. Attribute Lists">list of attributes</a> enclosed in square
|
|
1268
|
+
brackets.
|
|
1269
|
+
</li><li>
|
|
1270
|
+
The attribute list is mandatory except for URLs and email addresses.
|
|
1271
|
+
</li><li>
|
|
1272
|
+
Expansion of non-system macro references can be escaped by
|
|
1273
|
+
prefixing a backslash character.
|
|
1274
|
+
</li><li>
|
|
1275
|
+
Block macro attribute reference substitution is performed prior to
|
|
1276
|
+
macro expansion.
|
|
1277
|
+
</li><li>
|
|
1278
|
+
The substitutions performed prior to Inline macro macro expansion
|
|
1279
|
+
are determined by the inline context.
|
|
1280
|
+
</li><li>
|
|
1281
|
+
Macros are processed in the order they appear in the configuration
|
|
1282
|
+
file(s).
|
|
1283
|
+
</li><li>
|
|
1284
|
+
Calls to inline macros can be nested inside different inline macros
|
|
1285
|
+
(an inline macro call cannot contain a nested call to itself).
|
|
1286
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_inline_macros"></a>17.1. Inline Macros</h3></div></div></div><p>Inline Macros occur in an inline element context. Predefined Inline
|
|
1287
|
+
macros include <span class="emphasis"><em>URLs</em></span>, <span class="emphasis"><em>image</em></span> and <span class="emphasis"><em>link</em></span> macros.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_urls"></a>17.1.1. URLs</h4></div></div></div><p><span class="emphasis"><em>http</em></span>, <span class="emphasis"><em>https</em></span>, <span class="emphasis"><em>ftp</em></span>, <span class="emphasis"><em>file</em></span>, <span class="emphasis"><em>mailto</em></span> and <span class="emphasis"><em>callto</em></span> URLs are
|
|
1288
|
+
rendered using predefined inline macros.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1289
|
+
If you don't need a customized the link caption you can enter the
|
|
1290
|
+
<span class="emphasis"><em>http</em></span>, <span class="emphasis"><em>https</em></span>, <span class="emphasis"><em>ftp</em></span>, <span class="emphasis"><em>file</em></span> URLs and email addresses without any
|
|
1291
|
+
special macro syntax.
|
|
1292
|
+
</li><li>
|
|
1293
|
+
If no caption text is specified the URL is displayed.
|
|
1294
|
+
</li></ul></div><p>Here are some examples:</p><pre class="literallayout">http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
|
|
1295
|
+
http://www.methods.co.nz/asciidoc/
|
|
1296
|
+
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
|
|
1297
|
+
joe.bloggs@foobar.com
|
|
1298
|
+
callto:joe.bloggs[]</pre><p>Which are rendered:</p><p><a href="http://www.methods.co.nz/asciidoc/" target="_top">The <span class="emphasis"><em>AsciiDoc</em></span> home page</a></p><p><a href="http://www.methods.co.nz/asciidoc/" target="_top">http://www.methods.co.nz/asciidoc/</a></p><p><a href="mailto:joe.bloggs@foobar.com" target="_top">email Joe Bloggs</a></p><p><a href="mailto:joe.bloggs@foobar.com" target="_top">joe.bloggs@foobar.com</a></p><p><a href="callto:joe.bloggs" target="_top">joe.bloggs</a></p><div class="itemizedlist"><ul type="disc"><li>
|
|
1299
|
+
If the <code class="literal"><target></code> necessitates space characters they should be
|
|
1300
|
+
replaced by <code class="literal">%20</code>. For example <code class="literal">large%20image.png</code>.
|
|
1301
|
+
</li><li>
|
|
1302
|
+
Define an attribute entry if you refer to the same URL more than
|
|
1303
|
+
once, this will make your document <a href="#X62" title="Attribute entries promote clarity and eliminate repetition">easier to maintain and easier to read</a>.
|
|
1304
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_internal_cross_references"></a>17.1.2. Internal Cross References</h4></div></div></div><p>Two <span class="emphasis"><em>AsciiDoc</em></span> inline macros are provided for creating hypertext links
|
|
1305
|
+
within an <span class="emphasis"><em>AsciiDoc</em></span> document. You can use either the standard macro
|
|
1306
|
+
syntax or the (preferred) alternative.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a id="X30"></a>17.1.2.1. anchor</h5></div></div></div><p>Used to specify hypertext link targets:</p><pre class="literallayout">[[<id>,<xreflabel>]]
|
|
1307
|
+
anchor:<id>[<xreflabel>]</pre><p>The <code class="literal"><id></code> is a unique identifier that must begin with a letter. The
|
|
1308
|
+
optional <code class="literal"><xreflabel></code> is the text to be displayed by captionless
|
|
1309
|
+
<span class="emphasis"><em>xref</em></span> macros that refer to this anchor. The optional <code class="literal"><xreflabel></code> is
|
|
1310
|
+
only really useful when generating DocBook output. Example anchor:</p><pre class="literallayout">[[X1]]</pre><p>You may have noticed that the syntax of this inline element is the
|
|
1311
|
+
same as that of the <a href="#X41" title="10. BlockId Element">BlockId block element</a>, this is no
|
|
1312
|
+
coincidence since they are functionally equivalent.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a id="_xref"></a>17.1.2.2. xref</h5></div></div></div><p>Creates a hypertext link to a document anchor.</p><pre class="literallayout"><<<id>,<caption>>>
|
|
1313
|
+
xref:<id>[<caption>]</pre><p>The <code class="literal"><id></code> refers to an existing anchor <code class="literal"><id></code>. The optional
|
|
1314
|
+
<code class="literal"><caption></code> is the link's displayed text. Example:</p><pre class="literallayout"><<X21,attribute lists>></pre><p>If <code class="literal"><caption></code> is not specified then the displayed text is
|
|
1315
|
+
auto-generated:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1316
|
+
The <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">xhtml11</code> backend displays the <code class="literal"><id></code> enclosed in
|
|
1317
|
+
square brackets.
|
|
1318
|
+
</li><li>
|
|
1319
|
+
If DocBook is produced the DocBook toolchain is responsible for the
|
|
1320
|
+
displayed text which will normally be the referenced figure, table
|
|
1321
|
+
or section title number followed by the element's title text.
|
|
1322
|
+
</li></ul></div><p>Here is an example:</p><pre class="screen">[[tiger_image]]
|
|
1323
|
+
.Tyger tyger
|
|
1324
|
+
image::tiger.png[]
|
|
1325
|
+
|
|
1326
|
+
This can be seen in <<tiger_image>>.</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_linking_to_local_documents"></a>17.1.3. Linking to Local Documents</h4></div></div></div><p>Hypertext links to files on the local file system are specified using
|
|
1327
|
+
the <span class="emphasis"><em>link</em></span> inline macro.</p><pre class="literallayout">link:<target>[<caption>]</pre><p>The <span class="emphasis"><em>link</em></span> macro generates relative URLs. The link macro <code class="literal"><target></code> is
|
|
1328
|
+
the target file name (relative to the file system location of the
|
|
1329
|
+
referring document). The optional <code class="literal"><caption></code> is the link's displayed
|
|
1330
|
+
text. If <code class="literal"><caption></code> is not specified then <code class="literal"><target></code> is displayed.
|
|
1331
|
+
Example:</p><pre class="literallayout">link:downloads/foo.zip[download foo.zip]</pre><p>You can use the <code class="literal"><filename>#<id></code> syntax to refer to an anchor within
|
|
1332
|
+
a target document but this usually only makes sense when targeting
|
|
1333
|
+
HTML documents.</p><p>Images can serve as hyperlinks using the <a href="#X9" title="17.1.4. Images"><code class="literal">image</code> macro</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X9"></a>17.1.4. Images</h4></div></div></div><p>Inline images are inserted into the output document using the <span class="emphasis"><em>image</em></span>
|
|
1334
|
+
macro. The inline syntax is:</p><pre class="literallayout">image:<target>[<attributes>]</pre><p>The contents of the image file <code class="literal"><target></code> is displayed. To display the
|
|
1335
|
+
image its file format must be supported by the target backend
|
|
1336
|
+
application. HTML and DocBook applications normally support PNG or JPG
|
|
1337
|
+
files.</p><p><code class="literal"><target></code> file name paths are relative to the location of the
|
|
1338
|
+
referring document.</p><div class="itemizedlist"><a id="X55"></a><p class="title"><b>Image macro attributes</b></p><ul type="disc"><li><p>
|
|
1339
|
+
The optional first positional attribute list entry specifies the
|
|
1340
|
+
alternative text which is displayed if the output application is
|
|
1341
|
+
unable to process the image file. For example:
|
|
1342
|
+
</p><pre class="literallayout">image:images/logo.png[Company Logo]</pre></li><li><p>
|
|
1343
|
+
The optional <code class="literal">width</code> and <code class="literal">height</code> attributes scale the image size
|
|
1344
|
+
and can be used in any combination. The units are pixels. The
|
|
1345
|
+
following example scales the previous example to a height of 32
|
|
1346
|
+
pixels:
|
|
1347
|
+
</p><pre class="literallayout">image:images/logo.png["Company Logo",height=32]</pre></li><li><p>
|
|
1348
|
+
The optional <code class="literal">link</code> attribute is used to link the image to an
|
|
1349
|
+
external document. The following example links a screenshot
|
|
1350
|
+
thumbnail to a full size version:
|
|
1351
|
+
</p><pre class="literallayout">image:screen-thumbnail.png[height=32,link="screen.png"]</pre></li><li><p>
|
|
1352
|
+
The optional <code class="literal">scaledwidth</code> attribute is only used in DocBook block
|
|
1353
|
+
images (specifically for PDF documents). The following example
|
|
1354
|
+
scales the images to 75% of the available print width:
|
|
1355
|
+
</p><pre class="literallayout">image::images/logo.png["Company Logo",scaledwidth="75%"]</pre></li><li><p>
|
|
1356
|
+
The optional <code class="literal">align</code> attribute is used for horizontal image
|
|
1357
|
+
alignment in DocBook block images (specifically for PDF documents).
|
|
1358
|
+
Allowed values are <code class="literal">center</code>, <code class="literal">left</code> and <code class="literal">right</code>. For example:
|
|
1359
|
+
</p><pre class="literallayout">image::images/tiger.png["Tiger image",align="left"]</pre></li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_block_macros"></a>17.2. Block Macros</h3></div></div></div><p>A Block macro reference must be contained in a single line separated
|
|
1360
|
+
either side by a blank line or a block delimiter.</p><p>Block macros behave just like Inline macros, with the following
|
|
1361
|
+
differences:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1362
|
+
They occur in a block context.
|
|
1363
|
+
</li><li>
|
|
1364
|
+
The default syntax is <code class="literal"><name>::<target>[<attributelist>]</code> (two
|
|
1365
|
+
colons, not one).
|
|
1366
|
+
</li><li>
|
|
1367
|
+
Markup template section names end in <code class="literal">-blockmacro</code> instead of
|
|
1368
|
+
<code class="literal">-inlinemacro</code>.
|
|
1369
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_block_identifier"></a>17.2.1. Block Identifier</h4></div></div></div><p>The Block Identifier macro sets the <code class="literal">id</code> attribute and has the same
|
|
1370
|
+
syntax as the <a href="#X30" title="17.1.2.1. anchor">anchor inline macro</a> since it performs
|
|
1371
|
+
essentially the same function — block templates employ the <code class="literal">id</code>
|
|
1372
|
+
attribute as a block link target. For example:</p><pre class="literallayout">[[X30]]</pre><p>This is equivalent to the <code class="literal">[id="X30"]</code> block attribute list.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X49"></a>17.2.2. Images</h4></div></div></div><p>Formal titled images are inserted into the output document using the
|
|
1373
|
+
<span class="emphasis"><em>image</em></span> macro. The syntax is:</p><pre class="literallayout">image::<target>[<attributes>]</pre><p>The block <code class="literal">image</code> macro has the same <a href="#X55" title="Image macro attributes">macro attributes</a> as its
|
|
1374
|
+
<a href="#X9" title="17.1.4. Images">inline counterpart</a>.</p><p>Images can be titled by preceding the <code class="literal">image</code> macro with a
|
|
1375
|
+
<span class="emphasis"><em>BlockTitle</em></span>. DocBook toolchains normally number examples and
|
|
1376
|
+
generate a <span class="emphasis"><em>List of Figures</em></span> backmatter section.</p><p>For example:</p><pre class="literallayout">.Main circuit board
|
|
1377
|
+
image::images/layout.png[J14P main circuit board]</pre><p><code class="literal">xhtml11</code> and <code class="literal">html4</code> backends precede the title with a <code class="literal">Figure :</code>
|
|
1378
|
+
prefix. You can customize this prefix with the <code class="literal">caption</code> attribute.
|
|
1379
|
+
For example:</p><pre class="literallayout">.Main circuit board
|
|
1380
|
+
[caption="Figure 2:"]
|
|
1381
|
+
image::images/layout.png[J14P main circuit board]</pre><div class="sidebar"><a id="X66"></a><p class="title"><b>Embedding images in XHTML documents</b></p><p>If you define the <code class="literal">data-uri</code> attribute then images referenced by
|
|
1382
|
+
<span class="emphasis"><em>image</em></span> macros will be embedded in XHTML outputs using the
|
|
1383
|
+
<a href="http://en.wikipedia.org/wiki/Data:_URI_scheme" target="_top">data: URI scheme</a>. You
|
|
1384
|
+
can use the <code class="literal">data-uri</code> attribute to produce single-file XHTML
|
|
1385
|
+
documents with embedded images and CSS, for example:</p><pre class="literallayout">$ asciidoc --unsafe -a data-uri mydocument.txt</pre><p>You will need to specify the <code class="literal">—unsafe</code> option because the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
1386
|
+
<code class="literal">data-uri</code> is implemented using the <code class="literal">{sys}</code> attribute.</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>Internet Explorer up to version 7 does not support <span class="emphasis"><em>data: URIs</em></span>,
|
|
1387
|
+
but it is supported by Internet Explorer 8 Beta 1.</p></td></tr></table></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X25"></a>17.2.3. Comment Lines</h4></div></div></div><p>Single lines starting with two forward slashes hard up against the
|
|
1388
|
+
left margin are treated as comments and are stripped from the output.
|
|
1389
|
+
Comment lines have been implemented as a block macro and are only
|
|
1390
|
+
valid in a block context — they are not treated as comments inside
|
|
1391
|
+
paragraphs or delimited blocks. Example comment line:</p><pre class="literallayout">// This is a comment.</pre><p>See also <a 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 which is
|
|
1392
|
+
hardwired into the <code class="literal">asciidoc(1)</code> program.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1393
|
+
You can't escape system macros with a leading backslash character
|
|
1394
|
+
(as you can with other macros).
|
|
1395
|
+
</li><li>
|
|
1396
|
+
The syntax and tasks performed by system macros is built into
|
|
1397
|
+
<code class="literal">asciidoc(1)</code> so they don't appear in configuration files. You can
|
|
1398
|
+
however customize the syntax by adding entries to a configuration
|
|
1399
|
+
file <code class="literal">[macros]</code> section.
|
|
1400
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X63"></a>17.3.1. Include Macros</h4></div></div></div><p>The <code class="literal">include</code> and <code class="literal">include1</code> system macros to include the contents of
|
|
1401
|
+
a named file into the source document.</p><p>The <code class="literal">include</code> macro includes a file as if it were part of the parent
|
|
1402
|
+
document — tabs are expanded and system macros processed. The
|
|
1403
|
+
contents of <code class="literal">include1</code> files are not subject to tab expansion or
|
|
1404
|
+
system macro processing nor are attribute or lower priority
|
|
1405
|
+
substitutions performed. The <code class="literal">include1</code> macro's main use is to include
|
|
1406
|
+
verbatim embedded CSS or scripts into configuration file headers.
|
|
1407
|
+
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>
|
|
1408
|
+
If the included file name is specified with a relative path then the
|
|
1409
|
+
path is relative to the location of the referring document.
|
|
1410
|
+
</li><li>
|
|
1411
|
+
Include macros can appear inside configuration files.
|
|
1412
|
+
</li><li>
|
|
1413
|
+
Files included from within <code class="literal">DelimitedBlocks</code> are read to completion
|
|
1414
|
+
to avoid false end-of-block underline termination.
|
|
1415
|
+
</li><li>
|
|
1416
|
+
File inclusion is limited to a depth of 5 to catch recursive loops.
|
|
1417
|
+
</li><li>
|
|
1418
|
+
Attribute references are expanded inside the include <code class="literal">target</code>; if an
|
|
1419
|
+
attribute is undefined then the included file is silently skipped.
|
|
1420
|
+
</li><li>
|
|
1421
|
+
The <span class="emphasis"><em>tabsize</em></span> macro attribute sets the number of space characters to
|
|
1422
|
+
be used for tab expansion in the included file.
|
|
1423
|
+
</li><li>
|
|
1424
|
+
Internally the <code class="literal">include1</code> macro is translated to the <code class="literal">include1</code>
|
|
1425
|
+
system attribute which means it must be evaluated in a region where
|
|
1426
|
+
attribute substitution is enabled — use the <code class="literal">include</code> macro
|
|
1427
|
+
instead.
|
|
1428
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_conditional_inclusion_macros"></a>17.3.2. Conditional Inclusion Macros</h4></div></div></div><p>Lines of text in the source document can be selectively included or
|
|
1429
|
+
excluded from processing based on the existence (or not) of a
|
|
1430
|
+
document attribute. There are two forms of conditional inclusion
|
|
1431
|
+
macro usage, the first includes document text between the <code class="literal">ifdef</code> and
|
|
1432
|
+
<code class="literal">endif</code> macros if a document attribute is defined:</p><pre class="literallayout">ifdef::<attribute>[]
|
|
1433
|
+
:
|
|
1434
|
+
endif::<attribute>[]</pre><p>The second for includes document text between the <code class="literal">ifndef</code> and <code class="literal">endif</code>
|
|
1435
|
+
macros if the attribute is not defined:</p><pre class="literallayout">ifndef::<attribute>[]
|
|
1436
|
+
:
|
|
1437
|
+
endif::<attribute>[]</pre><p><code class="literal"><attribute></code> is an attribute name which is optional in the trailing
|
|
1438
|
+
<code class="literal">endif</code> macro.</p><p>Take a look at the <code class="literal">*.conf</code> configuration files in the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
1439
|
+
distribution for examples of conditional inclusion macro usage.</p><div class="sidebar"><p class="title"><b>Two types of conditional inclusion</b></p><p>Conditional inclusion macros are evaluated when they are read, but
|
|
1440
|
+
there is another type of conditional inclusion based on attribute
|
|
1441
|
+
references, the latter being evaluated when the output file is
|
|
1442
|
+
written.</p><p>These examples illustrate the two forms of conditional inclusion. The
|
|
1443
|
+
only difference between them is that the first is evaluated at program
|
|
1444
|
+
load time while the second is evaluated when the output is written:</p><pre class="literallayout">ifdef::world[]
|
|
1445
|
+
Hello World!
|
|
1446
|
+
endif::world[]</pre><pre class="literallayout">{world#}Hello World!</pre><p>In this example when the <code class="literal">{world#}</code> conditional attribute reference
|
|
1447
|
+
is evaluates to a zero length string if <code class="literal">world</code> is defined; if <code class="literal">world</code>
|
|
1448
|
+
is not defined the whole line is dropped.</p><p>The subtle difference between the two types of conditional inclusion
|
|
1449
|
+
has implications for <span class="emphasis"><em>AsciiDoc</em></span> configuration files: <span class="emphasis"><em>AsciiDoc</em></span> has to
|
|
1450
|
+
read the configuration files <span class="strong"><strong>before</strong></span> reading the source document,
|
|
1451
|
+
this is necessary because the <span class="emphasis"><em>AsciiDoc</em></span> source syntax is mostly defined
|
|
1452
|
+
by the configuration files. This means that any lines of markup
|
|
1453
|
+
enveloped by conditional inclusion macros will be included or excluded
|
|
1454
|
+
<span class="strong"><strong>before</strong></span> the attribute entries in the <span class="emphasis"><em>AsciiDoc</em></span> document header are
|
|
1455
|
+
read, so setting related attributes in the <span class="emphasis"><em>AsciiDoc</em></span> source document
|
|
1456
|
+
header will have no effect. If you need to control configuration file
|
|
1457
|
+
markup inclusion with attribute entries in the <span class="emphasis"><em>AsciiDoc</em></span> source file
|
|
1458
|
+
header you need to use attribute references to control inclusion
|
|
1459
|
+
instead of conditional inclusion macros (attribute references are
|
|
1460
|
+
substituted at the time the output is written rather than at program
|
|
1461
|
+
startup).</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_eval_sys_and_sys2_system_macros"></a>17.3.3. eval, sys and sys2 System Macros</h4></div></div></div><p>These block macros exhibit the same behavior as their same named
|
|
1462
|
+
<a href="#X24" title="24.3. System Attribute References">system attribute references</a>. The difference is that system
|
|
1463
|
+
macros occur in a block macro context whereas system attributes are
|
|
1464
|
+
confined to an inline context where attribute substitution is enabled.</p><p>The following example displays a long directory listing inside a
|
|
1465
|
+
literal block:</p><pre class="literallayout">------------------
|
|
1466
|
+
sys::[ls -l *.txt]
|
|
1467
|
+
------------------</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_template_system_macro"></a>17.3.4. Template System Macro</h4></div></div></div><p>The <code class="literal">template</code> block macro allows the inclusion of one configuration
|
|
1468
|
+
file template section within another. The following example includes
|
|
1469
|
+
the <code class="literal">[admonitionblock]</code> section in the <code class="literal">[admonitionparagraph]</code>
|
|
1470
|
+
section:</p><pre class="literallayout">[admonitionparagraph]
|
|
1471
|
+
template::[admonitionblock]</pre><div class="itemizedlist"><p class="title"><b>Template macro behavior</b></p><ul type="disc"><li>
|
|
1472
|
+
The <code class="literal">template::[]</code> macro is useful for factoring configuration file
|
|
1473
|
+
markup.
|
|
1474
|
+
</li><li>
|
|
1475
|
+
<code class="literal">template::[]</code> macros cannot be nested.
|
|
1476
|
+
</li><li>
|
|
1477
|
+
<code class="literal">template::[]</code> macro expansion is applied to all sections
|
|
1478
|
+
after all configuration files have been read.
|
|
1479
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_macro_definitions"></a>17.4. Macro Definitions</h3></div></div></div><p>Each entry in the configuration <code class="literal">[macros]</code> section is a macro
|
|
1480
|
+
definition which can take one of the following forms:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1481
|
+
<code class="literal"><pattern>=<name></code>
|
|
1482
|
+
</span></dt><dd>
|
|
1483
|
+
Inline macro definition.
|
|
1484
|
+
</dd><dt><span class="term">
|
|
1485
|
+
<code class="literal"><pattern>=#<name></code>
|
|
1486
|
+
</span></dt><dd>
|
|
1487
|
+
Block macro definition.
|
|
1488
|
+
</dd><dt><span class="term">
|
|
1489
|
+
<code class="literal"><pattern>=+<name></code>
|
|
1490
|
+
</span></dt><dd>
|
|
1491
|
+
System macro definition.
|
|
1492
|
+
</dd><dt><span class="term">
|
|
1493
|
+
<code class="literal"><pattern></code>
|
|
1494
|
+
</span></dt><dd>
|
|
1495
|
+
Delete the existing macro with this <code class="literal"><pattern></code>.
|
|
1496
|
+
</dd></dl></div><p><code class="literal"><pattern></code> is a Python regular expression and <code class="literal"><name></code> is the name of
|
|
1497
|
+
a markup template. If <code class="literal"><name></code> is omitted then it is the value of the
|
|
1498
|
+
regular expression match group named <span class="emphasis"><em>name</em></span>.</p><div class="itemizedlist"><p class="title"><b>Here's what happens during macro substitution</b></p><ul type="disc"><li>
|
|
1499
|
+
Each contextually relevant macro <span class="emphasis"><em>pattern</em></span> from the <code class="literal">[macros]</code>
|
|
1500
|
+
section is matched against the input source line.
|
|
1501
|
+
</li><li>
|
|
1502
|
+
If a match is found the text to be substituted is loaded from a
|
|
1503
|
+
configuration markup template section named like
|
|
1504
|
+
<code class="literal"><name>-inlinemacro</code> or <code class="literal"><name>-blockmacro</code> (depending on the macro
|
|
1505
|
+
type).
|
|
1506
|
+
</li><li>
|
|
1507
|
+
Global and macro attribute list attributes are substituted in the
|
|
1508
|
+
macro's markup template.
|
|
1509
|
+
</li><li>
|
|
1510
|
+
The substituted template replaces the macro reference in the output
|
|
1511
|
+
document.
|
|
1512
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_tables"></a>18. Tables</h2></div></div></div><p>Tables are the most complex <span class="emphasis"><em>AsciiDoc</em></span> elements and this section is
|
|
1513
|
+
quite long. <sup>[<a id="id2544594" href="#ftn.id2544594">3</a>]</sup></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><span class="emphasis"><em>AsciiDoc</em></span> generates nice HTML tables, but the current crop of
|
|
1514
|
+
DocBook toolchains render tables with varying degrees of success. Use
|
|
1515
|
+
tables only when really necessary.</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_example_tables"></a>18.1. Example Tables</h3></div></div></div><p>The following annotated examples are all you'll need to start creating
|
|
1516
|
+
your own tables.</p><p>The only non-obvious thing you'll need to remember are the column stop
|
|
1517
|
+
characters:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1518
|
+
Backtick (`) — align left.
|
|
1519
|
+
</li><li>
|
|
1520
|
+
Single quote (') — align right.
|
|
1521
|
+
</li><li>
|
|
1522
|
+
Period (.) — align center.
|
|
1523
|
+
</li></ul></div><p>Simple table:</p><pre class="screen"> `---`---
|
|
1524
|
+
1 2
|
|
1525
|
+
3 4
|
|
1526
|
+
5 6
|
|
1527
|
+
--------</pre><p>Output:</p><div class="informaltable"><table cellpadding="4px" border="0" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; "><colgroup><col align="left" /><col align="left" /></colgroup><tbody><tr><td style="" align="left">
|
|
1528
|
+
1
|
|
1529
|
+
</td><td style="" align="left">
|
|
1530
|
+
2
|
|
1531
|
+
</td></tr><tr><td style="" align="left">
|
|
1532
|
+
3
|
|
1533
|
+
</td><td style="" align="left">
|
|
1534
|
+
4
|
|
1535
|
+
</td></tr><tr><td style="" align="left">
|
|
1536
|
+
5
|
|
1537
|
+
</td><td style="" align="left">
|
|
1538
|
+
6
|
|
1539
|
+
</td></tr></tbody></table></div><p>Table with title, header and footer:</p><pre class="screen"> .An example table
|
|
1540
|
+
[grid="all"]
|
|
1541
|
+
'---------.--------------
|
|
1542
|
+
Column 1 Column 2
|
|
1543
|
+
-------------------------
|
|
1544
|
+
1 Item 1
|
|
1545
|
+
2 Item 2
|
|
1546
|
+
3 Item 3
|
|
1547
|
+
-------------------------
|
|
1548
|
+
6 Three items
|
|
1549
|
+
-------------------------</pre><p>Output:</p><div class="table"><a id="id2544765"></a><p class="title"><b>Table 2. An example table</b></p><div class="table-contents"><table summary="An example table" cellpadding="4px" border="0" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; "><colgroup><col align="left" /><col align="center" /></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1550
|
+
Column 1
|
|
1551
|
+
</th><th style="border-bottom: 1px solid ; " align="center">
|
|
1552
|
+
Column 2
|
|
1553
|
+
</th></tr></thead><tfoot><tr><th style="border-right: 1px solid ; " align="left">
|
|
1554
|
+
6
|
|
1555
|
+
</th><th style="" align="center">
|
|
1556
|
+
Three items
|
|
1557
|
+
</th></tr></tfoot><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1558
|
+
1
|
|
1559
|
+
</td><td style="border-bottom: 1px solid ; " align="center">
|
|
1560
|
+
Item 1
|
|
1561
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1562
|
+
2
|
|
1563
|
+
</td><td style="border-bottom: 1px solid ; " align="center">
|
|
1564
|
+
Item 2
|
|
1565
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1566
|
+
3
|
|
1567
|
+
</td><td style="border-bottom: 1px solid ; " align="center">
|
|
1568
|
+
Item 3
|
|
1569
|
+
</td></tr></tbody></table></div></div><br class="table-break" /><p>Four columns totaling 15% of the <span class="emphasis"><em>pagewidth</em></span>, CSV data:</p><pre class="screen">[frame="all"]
|
|
1570
|
+
````~15
|
|
1571
|
+
1,2,3,4
|
|
1572
|
+
a,b,c,d
|
|
1573
|
+
A,B,C,D
|
|
1574
|
+
~~~~~~~~</pre><p>Output:</p><div class="informaltable"><table cellpadding="4px" border="0" 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="left" /><col align="left" /><col align="left" /></colgroup><tbody><tr><td style="" align="left">
|
|
1575
|
+
1
|
|
1576
|
+
</td><td style="" align="left">
|
|
1577
|
+
2
|
|
1578
|
+
</td><td style="" align="left">
|
|
1579
|
+
3
|
|
1580
|
+
</td><td style="" align="left">
|
|
1581
|
+
4
|
|
1582
|
+
</td></tr><tr><td style="" align="left">
|
|
1583
|
+
a
|
|
1584
|
+
</td><td style="" align="left">
|
|
1585
|
+
b
|
|
1586
|
+
</td><td style="" align="left">
|
|
1587
|
+
c
|
|
1588
|
+
</td><td style="" align="left">
|
|
1589
|
+
d
|
|
1590
|
+
</td></tr><tr><td style="" align="left">
|
|
1591
|
+
A
|
|
1592
|
+
</td><td style="" align="left">
|
|
1593
|
+
B
|
|
1594
|
+
</td><td style="" align="left">
|
|
1595
|
+
C
|
|
1596
|
+
</td><td style="" align="left">
|
|
1597
|
+
D
|
|
1598
|
+
</td></tr></tbody></table></div><p>A table with a numeric ruler and externally sourced CSV data:</p><pre class="screen"> [frame="all", grid="all"]
|
|
1599
|
+
.15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1600
|
+
ID,Customer Name,Contact Name,Customer Address,Phone
|
|
1601
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1602
|
+
include::customers.csv[]
|
|
1603
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</pre><p>Renders:</p><div class="informaltable"><table cellpadding="4px" border="0" 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="center" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1604
|
+
ID
|
|
1605
|
+
</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1606
|
+
Customer Name
|
|
1607
|
+
</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1608
|
+
Contact Name
|
|
1609
|
+
</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1610
|
+
Customer Address
|
|
1611
|
+
</th><th style="border-bottom: 1px solid ; " align="left">
|
|
1612
|
+
Phone
|
|
1613
|
+
</th></tr></thead><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1614
|
+
AROUT
|
|
1615
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1616
|
+
Around the Horn
|
|
1617
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1618
|
+
Thomas Hardy
|
|
1619
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1620
|
+
120 Hanover Sq.
|
|
1621
|
+
London
|
|
1622
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1623
|
+
(171) 555-7788
|
|
1624
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1625
|
+
BERGS
|
|
1626
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1627
|
+
Berglunds snabbkop
|
|
1628
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1629
|
+
Christina Berglund
|
|
1630
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1631
|
+
Berguvsvagen 8
|
|
1632
|
+
Lulea
|
|
1633
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1634
|
+
0921-12 34 65
|
|
1635
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1636
|
+
BLAUS
|
|
1637
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1638
|
+
Blauer See Delikatessen
|
|
1639
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1640
|
+
Hanna Moos
|
|
1641
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1642
|
+
Forsterstr. 57
|
|
1643
|
+
Mannheim
|
|
1644
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1645
|
+
0621-08460
|
|
1646
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1647
|
+
BLONP
|
|
1648
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1649
|
+
Blondel pere et fils
|
|
1650
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1651
|
+
Frederique Citeaux
|
|
1652
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1653
|
+
24, place Kleber
|
|
1654
|
+
Strasbourg
|
|
1655
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1656
|
+
88.60.15.31
|
|
1657
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1658
|
+
BOLID
|
|
1659
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1660
|
+
Bolido Comidas preparadas
|
|
1661
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1662
|
+
Martin Sommer
|
|
1663
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1664
|
+
C/ Araquil, 67
|
|
1665
|
+
Madrid
|
|
1666
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1667
|
+
(91) 555 22 82
|
|
1668
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1669
|
+
BONAP
|
|
1670
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1671
|
+
Bon app'
|
|
1672
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1673
|
+
Laurence Lebihan
|
|
1674
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1675
|
+
12, rue des Bouchers
|
|
1676
|
+
Marseille
|
|
1677
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1678
|
+
91.24.45.40
|
|
1679
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1680
|
+
BOTTM
|
|
1681
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1682
|
+
Bottom-Dollar Markets
|
|
1683
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1684
|
+
Elizabeth Lincoln
|
|
1685
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1686
|
+
23 Tsawassen Blvd.
|
|
1687
|
+
Tsawassen
|
|
1688
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1689
|
+
(604) 555-4729
|
|
1690
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center">
|
|
1691
|
+
BSBEV
|
|
1692
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1693
|
+
B's Beverages
|
|
1694
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1695
|
+
Victoria Ashworth
|
|
1696
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
1697
|
+
Fauntleroy Circus
|
|
1698
|
+
London
|
|
1699
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
1700
|
+
(171) 555-1212
|
|
1701
|
+
</td></tr><tr><td style="border-right: 1px solid ; " align="center">
|
|
1702
|
+
CACTU
|
|
1703
|
+
</td><td style="border-right: 1px solid ; " align="left">
|
|
1704
|
+
Cactus Comidas para llevar
|
|
1705
|
+
</td><td style="border-right: 1px solid ; " align="left">
|
|
1706
|
+
Patricio Simpson
|
|
1707
|
+
</td><td style="border-right: 1px solid ; " align="left">
|
|
1708
|
+
Cerrito 333
|
|
1709
|
+
Buenos Aires
|
|
1710
|
+
</td><td style="" align="left">
|
|
1711
|
+
(1) 135-5555
|
|
1712
|
+
</td></tr></tbody></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_asciidoc_table_block_elements"></a>18.2. AsciiDoc Table Block Elements</h3></div></div></div><p>This sub-section details the <span class="emphasis"><em>AsciiDoc</em></span> table format.</p><pre class="literallayout">Table ::= (Ruler,Header?,Body,Footer?)
|
|
1713
|
+
Header ::= (Row+,Underline)
|
|
1714
|
+
Footer ::= (Row+,Underline)
|
|
1715
|
+
Body ::= (Row+,Underline)
|
|
1716
|
+
Row ::= (Data+)</pre><p>A table is terminated when the table underline is followed by a blank
|
|
1717
|
+
line or an end of file. Table underlines which separate table headers,
|
|
1718
|
+
bodies and footers should not be followed by a blank line.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_ruler"></a>18.2.1. Ruler</h4></div></div></div><p>The first line of the table is called the <span class="emphasis"><em>Ruler</em></span>. The Ruler specifies
|
|
1719
|
+
which configuration file table definition to use, column widths,
|
|
1720
|
+
column alignments and the overall table width.</p><p>There are two ruler formats:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1721
|
+
Character ruler
|
|
1722
|
+
</span></dt><dd>
|
|
1723
|
+
The column widths are determined by the number of table fill
|
|
1724
|
+
characters between column stop characters.
|
|
1725
|
+
</dd><dt><span class="term">
|
|
1726
|
+
Numeric ruler
|
|
1727
|
+
</span></dt><dd>
|
|
1728
|
+
The column widths are specified numerically. If a column width
|
|
1729
|
+
is omitted the previous width is used. In the degenerate case
|
|
1730
|
+
of no widths being specified columns are allocated equal
|
|
1731
|
+
widths.
|
|
1732
|
+
</dd></dl></div><p>The ruler format can be summarized as:</p><pre class="literallayout">ruler ::= ((colstop,colwidth?,fillchar*)+, fillchar+, tablewidth?</pre><div class="itemizedlist"><ul type="disc"><li>
|
|
1733
|
+
The <span class="emphasis"><em>ruler</em></span> starts with a column stop character (designating the
|
|
1734
|
+
start of the first column).
|
|
1735
|
+
</li><li><p>
|
|
1736
|
+
Column stop characters specify the start and alignment of each
|
|
1737
|
+
column:
|
|
1738
|
+
</p><div class="itemizedlist"><ul type="circle"><li>
|
|
1739
|
+
Backtick (`) — align left.
|
|
1740
|
+
</li><li>
|
|
1741
|
+
Single quote (') — align right.
|
|
1742
|
+
</li><li>
|
|
1743
|
+
Period (.) — align center.
|
|
1744
|
+
</li></ul></div></li><li>
|
|
1745
|
+
In the case of <span class="emphasis"><em>fixed</em></span> format tables the ruler column widths specify
|
|
1746
|
+
source row data column boundaries.
|
|
1747
|
+
</li><li>
|
|
1748
|
+
The optional <span class="emphasis"><em>tablewidth</em></span> is a number representing the size of the
|
|
1749
|
+
output table relative to the <span class="emphasis"><em>pagewidth</em></span>. If <span class="emphasis"><em>tablewidth</em></span> is less
|
|
1750
|
+
than one then it is interpreted as a fraction of the page width; if
|
|
1751
|
+
it is greater than one then it is interpreted as a percentage of
|
|
1752
|
+
the page width. If <span class="emphasis"><em>tablewidth</em></span> is not specified then the table
|
|
1753
|
+
occupies the full <span class="emphasis"><em>pagewidth</em></span> (numeric rulers) or the relative width
|
|
1754
|
+
of the ruler compared to the <span class="emphasis"><em>textwidth</em></span> (character rulers).
|
|
1755
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_row_and_data_elements"></a>18.2.2. Row and Data Elements</h4></div></div></div><p>Each table row consists of a line of text containing the same number
|
|
1756
|
+
of <span class="emphasis"><em>Data</em></span> items as there are columns in the table,</p><p>Lines ending in a backslash character are continued on the next line.</p><p>Each <span class="emphasis"><em>Data</em></span> item is an <span class="emphasis"><em>AsciiDoc</em></span> substitutable string. The substitutions
|
|
1757
|
+
performed are specified by the <span class="emphasis"><em>subs</em></span> table definition entry. Data
|
|
1758
|
+
cannot contain <span class="emphasis"><em>AsciiDoc</em></span> block elements.</p><p>The format of the row is determined by the table definition <span class="emphasis"><em>format</em></span>
|
|
1759
|
+
value:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1760
|
+
fixed
|
|
1761
|
+
</span></dt><dd>
|
|
1762
|
+
Row data items are assigned by chopping the row up at ruler column
|
|
1763
|
+
width boundaries.
|
|
1764
|
+
</dd><dt><span class="term">
|
|
1765
|
+
csv
|
|
1766
|
+
</span></dt><dd>
|
|
1767
|
+
Data items are assigned the parsed CSV (Comma Separated Values)
|
|
1768
|
+
data.
|
|
1769
|
+
</dd><dt><span class="term">
|
|
1770
|
+
dsv
|
|
1771
|
+
</span></dt><dd><p>
|
|
1772
|
+
The DSV (Delimiter Separated Values) format is a common UNIX tabular
|
|
1773
|
+
text file format.
|
|
1774
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1775
|
+
The separator character is a colon (although this can be set to
|
|
1776
|
+
any letter using the <span class="emphasis"><em>separator</em></span> table attribute).
|
|
1777
|
+
</li><li>
|
|
1778
|
+
Common C-style backslash escapes are supported.
|
|
1779
|
+
</li><li>
|
|
1780
|
+
Blank lines are skipped.
|
|
1781
|
+
</li></ul></div></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_underline"></a>18.2.3. Underline</h4></div></div></div><p>A table <span class="emphasis"><em>Underline</em></span> consists of a line of three or more <span class="emphasis"><em>fillchar</em></span>
|
|
1782
|
+
characters which are end delimiters for table header, footer and body
|
|
1783
|
+
sections.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_attribute_list"></a>18.2.4. Attribute List</h4></div></div></div><p>The following optional table attributes can be specified in an
|
|
1784
|
+
<a href="#X21" title="23. Attribute Lists">AttributeList</a> preceding the table:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1785
|
+
separator
|
|
1786
|
+
</span></dt><dd>
|
|
1787
|
+
The default DSV format colon separator can be changed using the
|
|
1788
|
+
<span class="emphasis"><em>separator</em></span> attribute. For example: <code class="literal">[separator="|"]</code>.
|
|
1789
|
+
</dd><dt><span class="term">
|
|
1790
|
+
frame
|
|
1791
|
+
</span></dt><dd>
|
|
1792
|
+
Defines the table border and can take the following values: <span class="emphasis"><em>topbot</em></span>
|
|
1793
|
+
(top and bottom), <span class="emphasis"><em>all</em></span> (all sides), <span class="emphasis"><em>none</em></span> and <span class="emphasis"><em>sides</em></span> (left and
|
|
1794
|
+
right sides). The default value is <span class="emphasis"><em>topbot</em></span>.
|
|
1795
|
+
</dd><dt><span class="term">
|
|
1796
|
+
grid
|
|
1797
|
+
</span></dt><dd>
|
|
1798
|
+
Defines which ruler lines are drawn between table rows and columns.
|
|
1799
|
+
The <span class="emphasis"><em>grid</em></span> attribute value can be any of the following values:
|
|
1800
|
+
<span class="emphasis"><em>none</em></span>, <span class="emphasis"><em>cols</em></span>, <span class="emphasis"><em>rows</em></span> and <span class="emphasis"><em>all</em></span>. The default value is <span class="emphasis"><em>none</em></span>. For
|
|
1801
|
+
example <code class="literal">[frame="all", grid="none"]</code>.
|
|
1802
|
+
</dd><dt><span class="term">
|
|
1803
|
+
format, tablewidth
|
|
1804
|
+
</span></dt><dd>
|
|
1805
|
+
See <a href="#X37" title="18.2.5. Markup Attributes">Markup Attributes</a> below.
|
|
1806
|
+
</dd></dl></div><p>You can also use an AttributeList to override the following table
|
|
1807
|
+
definition and ruler parameters: <span class="emphasis"><em>format</em></span>, <span class="emphasis"><em>subs</em></span>, <span class="emphasis"><em>tablewidth</em></span>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X37"></a>18.2.5. Markup Attributes</h4></div></div></div><p>The following attributes are automatically available inside table tag
|
|
1808
|
+
and markup templates.</p><div class="variablelist"><dl><dt><span class="term">
|
|
1809
|
+
cols
|
|
1810
|
+
</span></dt><dd>
|
|
1811
|
+
The number of columns in the table.
|
|
1812
|
+
</dd><dt><span class="term">
|
|
1813
|
+
colalign
|
|
1814
|
+
</span></dt><dd>
|
|
1815
|
+
Column alignment assumes one of three values (<span class="emphasis"><em>left</em></span>, <span class="emphasis"><em>right</em></span> or
|
|
1816
|
+
<span class="emphasis"><em>center</em></span>). The value is determined by the corresponding ruler column
|
|
1817
|
+
stop character (only valid inside <span class="emphasis"><em>colspec</em></span>, <span class="emphasis"><em>headdata</em></span>, <span class="emphasis"><em>bodydata</em></span>
|
|
1818
|
+
and <span class="emphasis"><em>footdata</em></span> tags).
|
|
1819
|
+
</dd><dt><span class="term">
|
|
1820
|
+
colwidth
|
|
1821
|
+
</span></dt><dd>
|
|
1822
|
+
The output column widths are calculated integers (only valid inside
|
|
1823
|
+
<span class="emphasis"><em>colspec</em></span>, <span class="emphasis"><em>headdata</em></span>, <span class="emphasis"><em>bodydata</em></span> and <span class="emphasis"><em>footdata</em></span> tags).
|
|
1824
|
+
</dd><dt><span class="term">
|
|
1825
|
+
colnumber
|
|
1826
|
+
</span></dt><dd>
|
|
1827
|
+
The table column number starting at 1 (only valid inside <span class="emphasis"><em>colspec</em></span>,
|
|
1828
|
+
'headdata`, <code class="literal">bodydata</code> and <code class="literal">footdata</code> tags).
|
|
1829
|
+
</dd><dt><span class="term">
|
|
1830
|
+
format
|
|
1831
|
+
</span></dt><dd>
|
|
1832
|
+
The table definition <span class="emphasis"><em>format</em></span> value (can be overridden with
|
|
1833
|
+
attribute list entry).
|
|
1834
|
+
</dd><dt><span class="term">
|
|
1835
|
+
tablewidth
|
|
1836
|
+
</span></dt><dd>
|
|
1837
|
+
The ruler <span class="emphasis"><em>tablewidth</em></span> value (can be overridden with attribute list
|
|
1838
|
+
entry).
|
|
1839
|
+
</dd><dt><span class="term">
|
|
1840
|
+
pagewidth
|
|
1841
|
+
</span></dt><dd>
|
|
1842
|
+
The <span class="emphasis"><em>pagewidth</em></span> miscellaneous configuration option.
|
|
1843
|
+
</dd><dt><span class="term">
|
|
1844
|
+
pageunits
|
|
1845
|
+
</span></dt><dd>
|
|
1846
|
+
The <span class="emphasis"><em>pageunits</em></span> miscellaneous configuration option.
|
|
1847
|
+
</dd></dl></div><p>The <span class="emphasis"><em>colwidth</em></span> value is calculated as (<code class="literal">N</code> is the ruler column width
|
|
1848
|
+
number and <code class="literal">M</code> is the sum of the ruler column widths):</p><pre class="literallayout">( N / M ) * pagewidth</pre><p>If the ruler <span class="emphasis"><em>tablewidth</em></span> was specified the column width is multiplied
|
|
1849
|
+
again by this value.</p><p>There is one exception: character rulers that have no <span class="emphasis"><em>pagewidth</em></span>
|
|
1850
|
+
specified. In this case the <span class="emphasis"><em>colwidth</em></span> value is calculated as (where
|
|
1851
|
+
<code class="literal">N</code> is the column character width measured on the table ruler):</p><pre class="literallayout">( N / textwidth ) * pagewidth</pre><p>The following attributes are available to the table markup template:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1852
|
+
comspecs
|
|
1853
|
+
</span></dt><dd>
|
|
1854
|
+
Expands to N substituted <span class="emphasis"><em>comspec</em></span> tags where N is the number of
|
|
1855
|
+
columns.
|
|
1856
|
+
</dd><dt><span class="term">
|
|
1857
|
+
headrows, footrows, bodyrows
|
|
1858
|
+
</span></dt><dd>
|
|
1859
|
+
These references expand to sets of substituted header, footer and
|
|
1860
|
+
body rows as defined by the corresponding row and data configuration
|
|
1861
|
+
parameters.
|
|
1862
|
+
</dd><dt><span class="term">
|
|
1863
|
+
rows
|
|
1864
|
+
</span></dt><dd>
|
|
1865
|
+
Experimental attribute (number of source lines in table) available
|
|
1866
|
+
in table markup templates (used by experimental LaTeX backend).
|
|
1867
|
+
</dd></dl></div></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X1"></a>19. Manpage Documents</h2></div></div></div><p>Sooner or later, if you program for a UNIX environment, you're going
|
|
1868
|
+
to have to write a man page.</p><p>By observing a couple of additional conventions you can compose
|
|
1869
|
+
<span class="emphasis"><em>AsciiDoc</em></span> files that will translate to a DocBook refentry (man page)
|
|
1870
|
+
document. The resulting DocBook file can then be translated to the
|
|
1871
|
+
native roff man page format (or other formats).</p><p>For example, the <code class="literal">asciidoc.1.txt</code> file in the <span class="emphasis"><em>AsciiDoc</em></span> distribution
|
|
1872
|
+
<code class="literal">./doc</code> directory was used to generate both the
|
|
1873
|
+
<code class="literal">asciidoc.1.css-embedded.html</code> HTML file the <code class="literal">asciidoc.1</code> roff
|
|
1874
|
+
formatted <code class="literal"><code class="literal">asciidoc(1)</code></code> man page.</p><div class="sidebar"><p class="title"><b>Viewing and printing manpage files</b></p><p>Use the <code class="literal">man(1)</code> command to view the manpage file:</p><pre class="literallayout">$ man -l asciidoc.1</pre><p>To print a high quality man page to a postscript printer:</p><pre class="literallayout">$ man -l -Tps asciidoc.1 | lpr</pre><p>You could also create a PDF version of the man page by converting
|
|
1875
|
+
PostScript to PDF using <code class="literal">ps2pdf(1)</code>:</p><pre class="literallayout">$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf</pre><p>The <code class="literal">ps2pdf(1)</code> command is included in the Ghostscript distribution.</p></div><p>To find out more about man pages view the <code class="literal">man(7)</code> manpage
|
|
1876
|
+
(<code class="literal">man 7 man</code> and <code class="literal">man man-pages</code> commands).</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_document_header"></a>19.1. Document Header</h3></div></div></div><p>A document Header is mandatory. The title line contains the man page
|
|
1877
|
+
name followed immediately by the manual section number in brackets,
|
|
1878
|
+
for example <span class="emphasis"><em>ASCIIDOC(1)</em></span>. The title name should not contain white
|
|
1879
|
+
space and the manual section number is a single digit optionally
|
|
1880
|
+
followed by a single character.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_the_name_section"></a>19.2. The NAME Section</h3></div></div></div><p>The first manpage section is mandatory, must be titled <span class="emphasis"><em>NAME</em></span> and must
|
|
1881
|
+
contain a single paragraph (usually a single line) consisting of a
|
|
1882
|
+
list of one or more comma separated command name(s) separated from the
|
|
1883
|
+
command purpose by a dash character. The dash must have at least one
|
|
1884
|
+
white space character on either side. For example:</p><pre class="literallayout">printf, fprintf, sprintf - print formatted output</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_the_synopsis_section"></a>19.3. The SYNOPSIS Section</h3></div></div></div><p>The second manpage section is mandatory and must be titled <span class="emphasis"><em>SYNOPSIS</em></span>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_refmiscinfo_attributes"></a>19.4. refmiscinfo attributes</h3></div></div></div><p>In addition to the automatically created man page <a href="#X60" title="25. Intrinsic Attributes">intrinsic attributes</a> you can assign DocBook
|
|
1885
|
+
<a href="http://www.docbook.org/tdg5/en/html/refmiscinfo.html" target="_top">refmiscinfo</a>
|
|
1886
|
+
element <span class="emphasis"><em>source</em></span>, <span class="emphasis"><em>version</em></span> and <span class="emphasis"><em>manual</em></span> values using <span class="emphasis"><em>AsciiDoc</em></span>
|
|
1887
|
+
<code class="literal">{mansource}</code>, <code class="literal">{manversion}</code> and <code class="literal">{manmanual}</code> attributes
|
|
1888
|
+
respectively. This example is from the <span class="emphasis"><em>AsciiDoc</em></span> header of a man page
|
|
1889
|
+
source file:</p><pre class="literallayout">:man source: AsciiDoc
|
|
1890
|
+
:man version: {revision}
|
|
1891
|
+
:man manual: AsciiDoc Manual</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X7"></a>20. Configuration Files</h2></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> source file syntax and output file markup is largely
|
|
1892
|
+
controlled by a set of cascading, text based, configuration files. At
|
|
1893
|
+
runtime The <span class="emphasis"><em>AsciiDoc</em></span> default configuration files are combined with
|
|
1894
|
+
optional user and document specific configuration files.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_configuration_file_format"></a>20.1. Configuration File Format</h3></div></div></div><p>Configuration files contain named sections. Each section begins with a
|
|
1895
|
+
section name in square brackets []. The section body consists of the
|
|
1896
|
+
lines of text between adjacent section headings.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1897
|
+
Section names consist of one or more alphanumeric, underscore or
|
|
1898
|
+
dash characters and cannot begin or end with a dash.
|
|
1899
|
+
</li><li>
|
|
1900
|
+
Lines starting with a hash character "#" are treated as comments and
|
|
1901
|
+
ignored.
|
|
1902
|
+
</li><li>
|
|
1903
|
+
Same named sections and section entries override previously loaded
|
|
1904
|
+
sections and section entries (this is sometimes referred to as
|
|
1905
|
+
<span class="emphasis"><em>cascading</em></span>). Consequently, downstream configuration files need
|
|
1906
|
+
only contain those sections and section entries that need to be
|
|
1907
|
+
overridden.
|
|
1908
|
+
</li></ul></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>When creating custom configuration files you only need to include
|
|
1909
|
+
the sections and entries that differ from the default configuration.</p></td></tr></table></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The best way to learn about configuration files is to read the
|
|
1910
|
+
default configuration files in the <span class="emphasis"><em>AsciiDoc</em></span> distribution in
|
|
1911
|
+
conjunction with <code class="literal">asciidoc(1)</code> output files. You can view configuration
|
|
1912
|
+
file load sequence by turning on the <code class="literal">asciidoc(1)</code> <code class="literal">-v</code> (<code class="literal">—verbose</code>)
|
|
1913
|
+
command-line option.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_markup_template_sections"></a>20.2. Markup Template Sections</h3></div></div></div><p>Markup template sections supply backend markup for translating
|
|
1914
|
+
<span class="emphasis"><em>AsciiDoc</em></span> elements. Since the text is normally backend dependent
|
|
1915
|
+
you'll find these sections in the backend specific configuration
|
|
1916
|
+
files. A markup template section body can contain:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1917
|
+
Backend markup
|
|
1918
|
+
</li><li>
|
|
1919
|
+
Attribute references
|
|
1920
|
+
</li><li>
|
|
1921
|
+
System macro calls.
|
|
1922
|
+
</li><li>
|
|
1923
|
+
A document content placeholder
|
|
1924
|
+
</li></ul></div><p>The document content placeholder is a single | character and is
|
|
1925
|
+
replaced by text from the source element. Use the <code class="literal">{brvbar}</code>
|
|
1926
|
+
attribute reference if you need a literal | character in the template.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_special_sections"></a>20.3. Special Sections</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> reserves the following predefined special section names for
|
|
1927
|
+
specific purposes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1928
|
+
miscellaneous
|
|
1929
|
+
</span></dt><dd>
|
|
1930
|
+
Configuration options that don't belong anywhere else.
|
|
1931
|
+
</dd><dt><span class="term">
|
|
1932
|
+
attributes
|
|
1933
|
+
</span></dt><dd>
|
|
1934
|
+
Attribute name/value entries.
|
|
1935
|
+
</dd><dt><span class="term">
|
|
1936
|
+
specialcharacters
|
|
1937
|
+
</span></dt><dd>
|
|
1938
|
+
Special characters reserved by the backend markup.
|
|
1939
|
+
</dd><dt><span class="term">
|
|
1940
|
+
tags
|
|
1941
|
+
</span></dt><dd>
|
|
1942
|
+
Backend markup tags.
|
|
1943
|
+
</dd><dt><span class="term">
|
|
1944
|
+
quotes
|
|
1945
|
+
</span></dt><dd>
|
|
1946
|
+
Definitions for quoted inline character formatting.
|
|
1947
|
+
</dd><dt><span class="term">
|
|
1948
|
+
specialwords
|
|
1949
|
+
</span></dt><dd>
|
|
1950
|
+
Lists of words and phrases singled out for special markup.
|
|
1951
|
+
</dd><dt><span class="term">
|
|
1952
|
+
replacements, replacements2
|
|
1953
|
+
</span></dt><dd>
|
|
1954
|
+
Find and replace substitution definitions.
|
|
1955
|
+
</dd><dt><span class="term">
|
|
1956
|
+
specialsections
|
|
1957
|
+
</span></dt><dd>
|
|
1958
|
+
Used to single out special section names for specific markup.
|
|
1959
|
+
</dd><dt><span class="term">
|
|
1960
|
+
macros
|
|
1961
|
+
</span></dt><dd>
|
|
1962
|
+
Macro syntax definitions.
|
|
1963
|
+
</dd><dt><span class="term">
|
|
1964
|
+
titles
|
|
1965
|
+
</span></dt><dd>
|
|
1966
|
+
Heading, section and block title definitions.
|
|
1967
|
+
</dd><dt><span class="term">
|
|
1968
|
+
paradef*
|
|
1969
|
+
</span></dt><dd>
|
|
1970
|
+
Paragraph element definitions.
|
|
1971
|
+
</dd><dt><span class="term">
|
|
1972
|
+
blockdef*
|
|
1973
|
+
</span></dt><dd>
|
|
1974
|
+
DelimitedBlock element definitions.
|
|
1975
|
+
</dd><dt><span class="term">
|
|
1976
|
+
listdef*
|
|
1977
|
+
</span></dt><dd>
|
|
1978
|
+
List element definitions.
|
|
1979
|
+
</dd><dt><span class="term">
|
|
1980
|
+
tabledef*
|
|
1981
|
+
</span></dt><dd>
|
|
1982
|
+
Table element definitions.
|
|
1983
|
+
</dd></dl></div><p>Each line of text in a special section is a <span class="emphasis"><em>section entry</em></span>. Section
|
|
1984
|
+
entries share the following syntax:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1985
|
+
<span class="emphasis"><em>name=value</em></span>
|
|
1986
|
+
</span></dt><dd>
|
|
1987
|
+
The entry value is set to <span class="emphasis"><em>value</em></span>.
|
|
1988
|
+
</dd><dt><span class="term">
|
|
1989
|
+
<span class="emphasis"><em>name=</em></span>
|
|
1990
|
+
</span></dt><dd>
|
|
1991
|
+
The entry value is set to a zero length string.
|
|
1992
|
+
</dd><dt><span class="term">
|
|
1993
|
+
<span class="emphasis"><em>name</em></span>
|
|
1994
|
+
</span></dt><dd>
|
|
1995
|
+
The entry is undefined (deleted from the configuration).
|
|
1996
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>Section entry behavior</b></p><ul type="disc"><li>
|
|
1997
|
+
All equals characters inside the <code class="literal">name</code> must be escaped with a
|
|
1998
|
+
backslash character.
|
|
1999
|
+
</li><li>
|
|
2000
|
+
<code class="literal">name</code> and <code class="literal">value</code> are stripped of leading and trailing white space.
|
|
2001
|
+
</li><li>
|
|
2002
|
+
Attribute names, tag entry names and markup template section names
|
|
2003
|
+
consist of one or more alphanumeric, underscore or dash characters.
|
|
2004
|
+
Names should not begin or end with a dash.
|
|
2005
|
+
</li><li>
|
|
2006
|
+
A blank configuration file section (one without any entries) deletes
|
|
2007
|
+
any preceding section with the same name (applies to non-markup
|
|
2008
|
+
template sections).
|
|
2009
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_miscellaneous"></a>20.3.1. Miscellaneous</h4></div></div></div><p>The optional <code class="literal">[miscellaneous]</code> section specifies the following
|
|
2010
|
+
<code class="literal">name=value</code> options:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2011
|
+
newline
|
|
2012
|
+
</span></dt><dd><p>
|
|
2013
|
+
Output file line termination characters. Can include any
|
|
2014
|
+
valid Python string escape sequences. The default value is
|
|
2015
|
+
<code class="literal">\r\n</code> (carriage return, line feed). Should not be quoted or
|
|
2016
|
+
contain explicit spaces (use <code class="literal">\x20</code> instead). For example:
|
|
2017
|
+
</p><pre class="literallayout">$ asciidoc -a 'newline=\n' -b docbook mydoc.txt</pre></dd><dt><span class="term">
|
|
2018
|
+
outfilesuffix
|
|
2019
|
+
</span></dt><dd>
|
|
2020
|
+
The default extension for the output file, for example
|
|
2021
|
+
<code class="literal">outfilesuffix=.html</code>. Defaults to backend name.
|
|
2022
|
+
</dd><dt><span class="term">
|
|
2023
|
+
tabsize
|
|
2024
|
+
</span></dt><dd>
|
|
2025
|
+
The number of spaces to expand tab characters, for example
|
|
2026
|
+
<code class="literal">tabsize=4</code>. Defaults to 8. A <span class="emphasis"><em>tabsize</em></span> of zero suppresses tab
|
|
2027
|
+
expansion (useful when piping included files through block
|
|
2028
|
+
filters). Included files can override this option using the
|
|
2029
|
+
<span class="emphasis"><em>tabsize</em></span> attribute.
|
|
2030
|
+
</dd><dt><span class="term">
|
|
2031
|
+
textwidth, pagewidth, pageunits
|
|
2032
|
+
</span></dt><dd>
|
|
2033
|
+
These global table related options are documented in the
|
|
2034
|
+
<a href="#X4">Table Configuration File Definitions</a> sub-section.
|
|
2035
|
+
</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><code class="literal">[miscellaneous]</code> configuration file entries can be set using
|
|
2036
|
+
the <code class="literal">asciidoc(1)</code> <code class="literal">-a</code> (<code class="literal">—attribute</code>) command-line option.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_titles"></a>20.3.2. Titles</h4></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
2037
|
+
sectiontitle
|
|
2038
|
+
</span></dt><dd>
|
|
2039
|
+
Two line section title pattern. The entry value is a Python
|
|
2040
|
+
regular expression containing the named group <span class="emphasis"><em>title</em></span>.
|
|
2041
|
+
</dd><dt><span class="term">
|
|
2042
|
+
underlines
|
|
2043
|
+
</span></dt><dd><p>
|
|
2044
|
+
A comma separated list of document and section title underline
|
|
2045
|
+
character pairs starting with the section level 0 and ending
|
|
2046
|
+
with section level 4 underline. The default setting is:
|
|
2047
|
+
</p><pre class="literallayout">underlines="==","--","~~","^^","++"</pre></dd><dt><span class="term">
|
|
2048
|
+
sect0…sect4
|
|
2049
|
+
</span></dt><dd>
|
|
2050
|
+
One line section title patterns. The entry value is a Python
|
|
2051
|
+
regular expression containing the named group <span class="emphasis"><em>title</em></span>.
|
|
2052
|
+
</dd><dt><span class="term">
|
|
2053
|
+
blocktitle
|
|
2054
|
+
</span></dt><dd>
|
|
2055
|
+
<a href="#X42" title="9. BlockTitles">BlockTitle element</a> pattern. The entry value is a
|
|
2056
|
+
Python regular expression containing the named group <span class="emphasis"><em>title</em></span>.
|
|
2057
|
+
</dd><dt><span class="term">
|
|
2058
|
+
subs
|
|
2059
|
+
</span></dt><dd>
|
|
2060
|
+
A comma separated list of substitutions that are performed on
|
|
2061
|
+
the document header and section titles. Defaults to <span class="emphasis"><em>normal</em></span>
|
|
2062
|
+
substitution.
|
|
2063
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_tags"></a>20.3.3. Tags</h4></div></div></div><p>The <code class="literal">[tags]</code> section contains backend tag definitions (one per
|
|
2064
|
+
line). Tags are used to translate <span class="emphasis"><em>AsciiDoc</em></span> elements to backend
|
|
2065
|
+
markup.</p><p>An <span class="emphasis"><em>AsciiDoc</em></span> tag definition is formatted like
|
|
2066
|
+
<code class="literal"><tagname>=<starttag>|<endtag></code>. For example:</p><pre class="literallayout">emphasis=<em>|</em></pre><p>In this example <code class="literal">asciidoc(1)</code> replaces the | character with the
|
|
2067
|
+
emphasized text from the <span class="emphasis"><em>AsciiDoc</em></span> input file and writes the result to
|
|
2068
|
+
the output file.</p><p>Use the <code class="literal">{brvbar}</code> attribute reference if you need to include a | pipe
|
|
2069
|
+
character inside tag text.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_attributes_section"></a>20.3.4. Attributes Section</h4></div></div></div><p>The optional <code class="literal">[attributes]</code> section contains predefined attributes.</p><p>If the attribute value requires leading or trailing spaces then the
|
|
2070
|
+
text text should be enclosed in double-quote (") characters.</p><p>To delete a attribute insert a name only entry in a downstream
|
|
2071
|
+
configuration file or use the <code class="literal">asciidoc(1)</code> <code class="literal">—attribute name!</code>
|
|
2072
|
+
command-line option (the attribute name is suffixed with a ! character
|
|
2073
|
+
to delete it).</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_special_characters"></a>20.3.5. Special Characters</h4></div></div></div><p>The <code class="literal">[specialcharacters]</code> section specifies how to escape characters
|
|
2074
|
+
reserved by the backend markup. Each translation is specified on a
|
|
2075
|
+
single line formatted like:</p><pre class="literallayout">special_character=translated_characters</pre><p>Special characters are normally confined to those that resolve
|
|
2076
|
+
markup ambiguity (in the case of SGML/XML markups the ampersand, less
|
|
2077
|
+
than and greater than characters). The following example causes all
|
|
2078
|
+
occurrences of the <code class="literal"><</code> character to be replaced by <code class="literal">&lt;</code>.</p><pre class="literallayout"><=&lt;</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_quoted_text"></a>20.3.6. Quoted Text</h4></div></div></div><p>Quoting is used primarily for text formatting. The <code class="literal">[quotes]</code> section
|
|
2079
|
+
defines <span class="emphasis"><em>AsciiDoc</em></span> quoting characters and their corresponding backend
|
|
2080
|
+
markup tags. Each section entry value is the name of a of a <code class="literal">[tags]</code>
|
|
2081
|
+
section entry. The entry name is the character (or characters) that
|
|
2082
|
+
quote the text. The following examples are taken from <span class="emphasis"><em>AsciiDoc</em></span>
|
|
2083
|
+
configuration files:</p><pre class="literallayout">[quotes]
|
|
2084
|
+
_=emphasis</pre><pre class="literallayout">[tags]
|
|
2085
|
+
emphasis=<em>|</em></pre><p>You can specify the left and right quote strings separately by
|
|
2086
|
+
separating them with a | character, for example:</p><pre class="literallayout">``|''=quoted</pre><p>Omitting the tag will disable quoting, for example, if you don't want
|
|
2087
|
+
superscripts or subscripts put the following in a custom configuration
|
|
2088
|
+
file or edit the global <code class="literal">asciidoc.conf</code> configuration file:</p><pre class="literallayout">[quotes]
|
|
2089
|
+
^=
|
|
2090
|
+
~=</pre><p><a href="#X52" title="7.1.1. Constrained and Unconstrained Quotes">Unconstrained quotes</a> are differentiated by prefixing the tag
|
|
2091
|
+
name with a hash character, for example:</p><pre class="literallayout">__=#emphasis</pre><div class="itemizedlist"><p class="title"><b>Quoted text behavior</b></p><ul type="disc"><li>
|
|
2092
|
+
Quote characters must be non-alphanumeric.
|
|
2093
|
+
</li><li>
|
|
2094
|
+
To minimize quoting ambiguity try not to use the same quote
|
|
2095
|
+
characters in different quote types.
|
|
2096
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_special_words_2"></a>20.3.7. Special Words</h4></div></div></div><p>The <code class="literal">[specialwords]</code> section is used to single out words and phrases
|
|
2097
|
+
that you want to consistently format in some way throughout your
|
|
2098
|
+
document without having to repeatedly specify the markup. The name of
|
|
2099
|
+
each entry corresponds to a markup template section and the entry
|
|
2100
|
+
value consists of a list of words and phrases to be marked up. For
|
|
2101
|
+
example:</p><pre class="literallayout">[specialwords]
|
|
2102
|
+
strongwords=NOTE: IMPORTANT:</pre><pre class="literallayout">[strongwords]
|
|
2103
|
+
<strong>{words}</strong></pre><p>The examples specifies that any occurrence of <code class="literal">NOTE:</code> or <code class="literal">IMPORTANT:</code>
|
|
2104
|
+
should appear in a bold font.</p><p>Words and word phrases are treated as Python regular expressions: for
|
|
2105
|
+
example, the word <code class="literal">^NOTE:</code> would only match <code class="literal">NOTE:</code> if appeared at
|
|
2106
|
+
the start of a line.</p><p><span class="emphasis"><em>AsciiDoc</em></span> comes with three built-in Special Word types:
|
|
2107
|
+
<span class="emphasis"><em>emphasizedwords</em></span>, <span class="emphasis"><em>monospacedwords</em></span> and <span class="emphasis"><em>strongwords</em></span>, each has a
|
|
2108
|
+
corresponding (backend specific) markup template section. Edit the
|
|
2109
|
+
configuration files to customize existing Special Words and to add new
|
|
2110
|
+
ones.</p><div class="itemizedlist"><p class="title"><b>Special word behavior</b></p><ul type="disc"><li>
|
|
2111
|
+
Word list entries must be separated by space characters.
|
|
2112
|
+
</li><li>
|
|
2113
|
+
Word list entries with embedded spaces should be enclosed in quotation (")
|
|
2114
|
+
characters.
|
|
2115
|
+
</li><li>
|
|
2116
|
+
A <code class="literal">[specialwords]</code> section entry of the form
|
|
2117
|
+
<code class="literal">name=word1 [word2…]</code> adds words to existing <code class="literal">name</code> entries.
|
|
2118
|
+
</li><li>
|
|
2119
|
+
A <code class="literal">[specialwords]</code> section entry of the form <code class="literal">name</code> undefines
|
|
2120
|
+
(deletes) all existing <code class="literal">name</code> words.
|
|
2121
|
+
</li><li>
|
|
2122
|
+
Since word list entries are processed as Python regular expressions
|
|
2123
|
+
you need to be careful to escape regular expression special
|
|
2124
|
+
characters.
|
|
2125
|
+
</li><li>
|
|
2126
|
+
By default Special Words are substituted before Inline Macros, this
|
|
2127
|
+
may lead to undesirable consequences. For example the special word
|
|
2128
|
+
<code class="literal">foobar</code> would be expanded inside the macro call
|
|
2129
|
+
<code class="literal"><a href="http://www.foobar.com" target="_top">http://www.foobar.com</a></code>. A possible solution is to emphasize
|
|
2130
|
+
whole words only by defining the word using regular expression
|
|
2131
|
+
characters, for example <code class="literal">\bfoobar\b</code>.
|
|
2132
|
+
</li><li>
|
|
2133
|
+
If the first matched character of a special word is a backslash then
|
|
2134
|
+
the remaining characters are output without markup i.e. the
|
|
2135
|
+
backslash can be used to escape special word markup. For example
|
|
2136
|
+
the special word <code class="literal">\\?\b[Tt]en\b</code> will mark up the words <code class="literal">Ten</code> and
|
|
2137
|
+
<code class="literal">ten</code> only if they are not preceded by a backslash.
|
|
2138
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X10"></a>20.3.8. Replacements</h4></div></div></div><p><code class="literal">[replacements]</code> and <code class="literal">[replacements2]</code> configuration file entries
|
|
2139
|
+
specify find and replace text and are formatted like:</p><pre class="literallayout">find_pattern=replacement_text</pre><p>The find text can be a Python regular expression; the replace text can
|
|
2140
|
+
contain Python regular expression group references.</p><p>Use Replacement shortcuts for often used macro references, for
|
|
2141
|
+
example (the second replacement allows us to backslash escape the
|
|
2142
|
+
macro name):</p><pre class="literallayout">NEW!=image:./images/smallnew.png[New!]
|
|
2143
|
+
\\NEW!=NEW!</pre><div class="itemizedlist"><p class="title"><b>Replacement behavior</b></p><ul type="disc"><li>
|
|
2144
|
+
The built-in replacements can be escaped with a backslash.
|
|
2145
|
+
</li><li>
|
|
2146
|
+
If the find or replace text has leading or trailing spaces then the
|
|
2147
|
+
text should be enclosed in quotation (") characters.
|
|
2148
|
+
</li><li>
|
|
2149
|
+
Since the find text is processed as a regular expression you need to
|
|
2150
|
+
be careful to escape regular expression special characters.
|
|
2151
|
+
</li><li>
|
|
2152
|
+
Replacements are performed in the same order they appear in the
|
|
2153
|
+
configuration file replacements section.
|
|
2154
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X27"></a>20.4. Configuration File Names and Locations</h3></div></div></div><p>Configuration files have a <code class="literal">.conf</code> file name extension; they are
|
|
2155
|
+
loaded implicitly (using predefined file names and locations) or
|
|
2156
|
+
explicitly (using the <code class="literal">asciidoc(1)</code> <code class="literal">-f</code> (<code class="literal">—conf-file</code>) command-line
|
|
2157
|
+
option).</p><p>Implicit configuration files are loaded from the following directories
|
|
2158
|
+
in the following order:</p><div class="orderedlist"><ol type="1"><li>
|
|
2159
|
+
The <code class="literal">/etc/asciidoc</code> directory (if it exists).
|
|
2160
|
+
</li><li>
|
|
2161
|
+
The directory containing the asciidoc executable.
|
|
2162
|
+
</li><li>
|
|
2163
|
+
The user's <code class="literal">$HOME/.asciidoc</code> directory (if it exists).
|
|
2164
|
+
</li><li>
|
|
2165
|
+
The directory containing the <span class="emphasis"><em>AsciiDoc</em></span> source file.
|
|
2166
|
+
</li></ol></div><p>The following implicit configuration files from each of the above
|
|
2167
|
+
locations are loaded in the following order:</p><div class="orderedlist"><ol type="1"><li>
|
|
2168
|
+
<code class="literal">asciidoc.conf</code>
|
|
2169
|
+
</li><li>
|
|
2170
|
+
<code class="literal"><backend>.conf</code>
|
|
2171
|
+
</li><li>
|
|
2172
|
+
<code class="literal"><backend>-<doctype>.conf</code>
|
|
2173
|
+
</li><li>
|
|
2174
|
+
<code class="literal">lang-<lang>.conf</code>
|
|
2175
|
+
</li></ol></div><p>Where <code class="literal"><backend></code> and <code class="literal"><doctype></code> are values specified by the
|
|
2176
|
+
<code class="literal">asciidoc(1)</code> <code class="literal">-b</code> (<code class="literal">—backend</code>) and <code class="literal">-d</code> (<code class="literal">—doctype</code>) command-line
|
|
2177
|
+
options. <code class="literal"><lang></code> is the value of the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">lang</code> attribute
|
|
2178
|
+
(defaults to <code class="literal">en</code> (English)).</p><p>Finally, configuration files named like the source file will be
|
|
2179
|
+
automatically loaded if they are found in the source file directory.
|
|
2180
|
+
For example if the source file is <code class="literal">mydoc.txt</code> and the
|
|
2181
|
+
<code class="literal">—backend=html4</code> option is used then <code class="literal">asciidoc(1)</code> will look for
|
|
2182
|
+
<code class="literal">mydoc.conf</code> and <code class="literal">mydoc-html4.conf</code> in that order.</p><p>Implicit configuration files that don't exist will be silently
|
|
2183
|
+
skipped.</p><p>The user can explicitly specify additional configuration files using
|
|
2184
|
+
the <code class="literal">asciidoc(1)</code> <code class="literal">-f</code> (<code class="literal">—conf-file</code>) command-line option. The <code class="literal">-f</code>
|
|
2185
|
+
option can be specified multiple times, in which case configuration
|
|
2186
|
+
files will be processed in the order they appear on the command-line.</p><p>For example, when we translate our <span class="emphasis"><em>AsciiDoc</em></span> document <code class="literal">mydoc.txt</code> with:</p><pre class="literallayout">$ asciidoc -f extra.conf mydoc.txt</pre><p>Configuration files (if they exist) will be processed in the following
|
|
2187
|
+
order:</p><div class="orderedlist"><ol type="1"><li><p>
|
|
2188
|
+
First default global configuration files from the asciidoc program
|
|
2189
|
+
directory are loaded:
|
|
2190
|
+
</p><pre class="literallayout">asciidoc.conf
|
|
2191
|
+
xhtml11.conf</pre></li><li><p>
|
|
2192
|
+
Then, from the users home <code class="literal">~/.asciidoc</code> directory. This is were
|
|
2193
|
+
you put customization specific to your own asciidoc documents:
|
|
2194
|
+
</p><pre class="literallayout">asciidoc.conf
|
|
2195
|
+
xhtml11.conf
|
|
2196
|
+
xhtml11-article.conf</pre></li><li><p>
|
|
2197
|
+
Next from the source document project directory (the first three
|
|
2198
|
+
apply to all documents in the directory, the last two are specific
|
|
2199
|
+
to the mydoc.txt document):
|
|
2200
|
+
</p><pre class="literallayout">asciidoc.conf
|
|
2201
|
+
xhtml11.conf
|
|
2202
|
+
xhtml11-article.conf
|
|
2203
|
+
mydoc.conf
|
|
2204
|
+
mydoc-xhtml11.conf</pre></li><li><p>
|
|
2205
|
+
Finally the file specified by the <code class="literal">-f</code> command-line option is
|
|
2206
|
+
loaded:
|
|
2207
|
+
</p><pre class="literallayout">extra.conf</pre></li></ol></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Use the <code class="literal">asciidoc(1)</code> <code class="literal">-v</code> (<code class="literal">—verbose</code>) command-line option to see
|
|
2208
|
+
which configuration files are loaded and the order in which they are
|
|
2209
|
+
loaded.</p></td></tr></table></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_document_attributes"></a>21. Document Attributes</h2></div></div></div><p>A document attribute is comprised of a <span class="emphasis"><em>name</em></span> and a textual <span class="emphasis"><em>value</em></span>
|
|
2210
|
+
and is used for textual substitution in <span class="emphasis"><em>AsciiDoc</em></span> documents and
|
|
2211
|
+
configuration files. An attribute reference (an attribute name
|
|
2212
|
+
enclosed in braces) is replaced by its corresponding attribute
|
|
2213
|
+
value.</p><p>There are four sources of document attributes (from highest to lowest
|
|
2214
|
+
precedence):</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2215
|
+
Command-line attributes.
|
|
2216
|
+
</li><li>
|
|
2217
|
+
AttributeEntry, AttributeList, Macro and BlockId elements.
|
|
2218
|
+
</li><li>
|
|
2219
|
+
Configuration file <code class="literal">[attributes]</code> sections.
|
|
2220
|
+
</li><li>
|
|
2221
|
+
Intrinsic attributes.
|
|
2222
|
+
</li></ul></div><p>Within each of these divisions the last processed entry takes
|
|
2223
|
+
precedence.</p><div class="important" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="./images/icons/important.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>If an attribute is not defined then the line containing the
|
|
2224
|
+
attribute reference is dropped. This property is used extensively in
|
|
2225
|
+
<span class="emphasis"><em>AsciiDoc</em></span> configuration files to facilitate conditional markup
|
|
2226
|
+
generation.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X18"></a>22. Attribute Entries</h2></div></div></div><p>The <code class="literal">AttributeEntry</code> block element allows document attributes to be
|
|
2227
|
+
assigned within an <span class="emphasis"><em>AsciiDoc</em></span> document. Attribute entries are added to
|
|
2228
|
+
the global document attributes dictionary. The attribute name/value
|
|
2229
|
+
syntax is a single line like:</p><pre class="literallayout">:<name>: <value></pre><p>For example:</p><pre class="literallayout">:Author Initials: JB</pre><p>This will set an attribute reference <code class="literal">{authorinitials}</code> to the value
|
|
2230
|
+
<span class="emphasis"><em>JB</em></span> in the current document.</p><p>To delete (undefine) an attribute use the following syntax:</p><pre class="literallayout">:<name>!:</pre><div class="itemizedlist"><p class="title"><b>AttributeEntry properties</b></p><ul type="disc"><li>
|
|
2231
|
+
The attribute entry line begins with colon — no white space allowed
|
|
2232
|
+
in left margin.
|
|
2233
|
+
</li><li>
|
|
2234
|
+
<span class="emphasis"><em>AsciiDoc</em></span> converts the <code class="literal"><name></code> to a legal attribute name (lower
|
|
2235
|
+
case, alphanumeric and dash characters only — all other characters
|
|
2236
|
+
deleted). This allows more reader friendly text to be used.
|
|
2237
|
+
</li><li>
|
|
2238
|
+
Leading and trailing white space is stripped from the <code class="literal"><value></code>.
|
|
2239
|
+
</li><li>
|
|
2240
|
+
If the <code class="literal"><value></code> is blank then the corresponding attribute value is
|
|
2241
|
+
set to an empty string.
|
|
2242
|
+
</li><li>
|
|
2243
|
+
Special characters in the entry <code class="literal"><value></code> are substituted. To
|
|
2244
|
+
include special characters use the predefined <code class="literal">{gt}</code>, <code class="literal">{lt}</code>,
|
|
2245
|
+
<code class="literal">{amp}</code> attribute references.
|
|
2246
|
+
</li><li>
|
|
2247
|
+
Attribute references contained in the entry <code class="literal"><value></code> will be
|
|
2248
|
+
expanded.
|
|
2249
|
+
</li><li>
|
|
2250
|
+
By default AttributeEntry values are substituted for
|
|
2251
|
+
<code class="literal">specialcharacters</code> and <code class="literal">attributes</code> (see above), if you want a
|
|
2252
|
+
different AttributeEntry substitution set the <code class="literal">attributeentry-subs</code>
|
|
2253
|
+
attribute.
|
|
2254
|
+
</li><li>
|
|
2255
|
+
Attribute entries in the document Header are available for header
|
|
2256
|
+
markup template substitution.
|
|
2257
|
+
</li><li>
|
|
2258
|
+
Attribute elements override configuration file and intrinsic
|
|
2259
|
+
attributes but do not override command-line attributes.
|
|
2260
|
+
</li></ul></div><p>Here's another example:</p><pre class="screen">AsciiDoc User Manual
|
|
2261
|
+
====================
|
|
2262
|
+
:Author: Stuart Rackham
|
|
2263
|
+
:Email: srackham@gmail.com
|
|
2264
|
+
:Date: April 23, 2004
|
|
2265
|
+
:Revision: 5.1.1
|
|
2266
|
+
:Key words: linux, ralink, debian, wireless
|
|
2267
|
+
:Revision history:</pre><p>Which creates these attributes:</p><pre class="literallayout">{author}, {firstname}, {lastname}, {authorinitials}, {email},
|
|
2268
|
+
{date}, {revision}, {keywords}, {revisionhistory}</pre><p>The preceding example is equivalent to the standard <span class="emphasis"><em>AsciiDoc</em></span> two line
|
|
2269
|
+
document header. Actually it's a little bit different with the
|
|
2270
|
+
addition of the <code class="literal">{keywords}</code> and <code class="literal">{revisionhistory}</code> attributes
|
|
2271
|
+
<sup>[<a id="id2548980" href="#ftn.id2548980">4</a>]</sup>.</p><div class="sidebar"><a id="X62"></a><p class="title"><b>Attribute entries promote clarity and eliminate repetition</b></p><p>URLs and file names in <span class="emphasis"><em>AsciiDoc</em></span> macros are often quite long — they
|
|
2272
|
+
break paragraph flow and readability suffers. The problem is
|
|
2273
|
+
compounded by redundancy if the same name is used repeatedly.
|
|
2274
|
+
Attribute entries can be used to make your documents easier to read
|
|
2275
|
+
and write, here are some examples:</p><pre class="literallayout">:1: http://freshmeat.net/projects/asciidoc/
|
|
2276
|
+
:homepage: http://hg.sharesource.org/asciidoc/[AsciiDoc home page]
|
|
2277
|
+
:new: image:./images/smallnew.png[]</pre><pre class="literallayout">Using previously defined attributes: See the {1}[Freshmeat summary]
|
|
2278
|
+
or the {homepage} for something new {new}.</pre><div class="itemizedlist"><p class="title"><b>Note</b></p><ul type="disc"><li>
|
|
2279
|
+
The attribute entry definition must precede it's usage.
|
|
2280
|
+
</li><li>
|
|
2281
|
+
You are not limited to URLs or file names, entire macro calls or
|
|
2282
|
+
arbitrary lines of text can be abbreviated.
|
|
2283
|
+
</li><li>
|
|
2284
|
+
Shared attributes entries could be grouped into a separate file and
|
|
2285
|
+
<a href="#X63" title="17.3.1. Include Macros">included</a> in multiple documents.
|
|
2286
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X21"></a>23. Attribute Lists</h2></div></div></div><p>An attribute list is a comma separated list of attribute values. The
|
|
2287
|
+
entire list is enclosed in square brackets. Attribute lists are used
|
|
2288
|
+
to pass parameters to macros, blocks and inline quotes.</p><p>The list consists of zero or more positional attribute values followed
|
|
2289
|
+
by zero or more named attribute values. Here are three examples:</p><pre class="literallayout">[Hello]
|
|
2290
|
+
[quote, Bertrand Russell, The World of Mathematics (1956)]
|
|
2291
|
+
["22 times", backcolor="#0e0e0e", options="noborders,wide"]</pre><div class="itemizedlist"><p class="title"><b>Attribute list properties</b></p><ul type="disc"><li>
|
|
2292
|
+
If one or more attribute values contains a comma the all values must
|
|
2293
|
+
be quoted (enclosed in quotation characters).
|
|
2294
|
+
</li><li>
|
|
2295
|
+
If the list contains any named attributes the all string attribute
|
|
2296
|
+
values must be quoted.
|
|
2297
|
+
</li><li>
|
|
2298
|
+
List attributes take precedence over existing attributes.
|
|
2299
|
+
</li><li>
|
|
2300
|
+
List attributes can only be referenced in configuration file markup
|
|
2301
|
+
templates and tags, they are not available inside the document.
|
|
2302
|
+
</li><li>
|
|
2303
|
+
Attribute references are allowed inside attribute lists.
|
|
2304
|
+
</li><li>
|
|
2305
|
+
Setting a named attribute to <code class="literal">None</code> undefines the attribute.
|
|
2306
|
+
</li><li>
|
|
2307
|
+
Positional attributes are referred to as <code class="literal">{1}</code>,<code class="literal">{2}</code>,<code class="literal">{3}</code>,…
|
|
2308
|
+
</li><li>
|
|
2309
|
+
Attribute <code class="literal">{0}</code> refers to the entire list (excluding the enclosing
|
|
2310
|
+
square brackets).
|
|
2311
|
+
</li><li>
|
|
2312
|
+
If an attribute named <code class="literal">options</code> is present it is processed as a
|
|
2313
|
+
comma separated list of attributes with zero length string values.
|
|
2314
|
+
For example <code class="literal">[options="opt1,opt2,opt3"]</code> is equivalent to
|
|
2315
|
+
<code class="literal">[opt1="",opt2="",opt2=""]</code>.
|
|
2316
|
+
</li><li>
|
|
2317
|
+
Attribute lists are evaluated as a list of Python function
|
|
2318
|
+
arguments. If this fails or any of the items do not evaluate to a
|
|
2319
|
+
string, a number or None then all list items are treated as string
|
|
2320
|
+
literals.
|
|
2321
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_macro_attribute_lists"></a>23.1. Macro Attribute lists</h3></div></div></div><p>Macros calls are suffixed with an attribute list. The list may be
|
|
2322
|
+
empty but it cannot be omitted. List entries are used to pass
|
|
2323
|
+
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>23.2. AttributeList Element</h3></div></div></div><p>An attribute list on a line by itself constitutes an <span class="emphasis"><em>AttributeList</em></span>
|
|
2324
|
+
block element, its function is to parametrize the following block
|
|
2325
|
+
element. The list attributes are passed to the next block element for
|
|
2326
|
+
markup template substitution.</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>24. Attribute References</h2></div></div></div><p>An attribute references is an attribute name (possibly followed by an
|
|
2327
|
+
additional parameters) enclosed in braces. When an attribute
|
|
2328
|
+
reference is encountered it is evaluated and replaced by its
|
|
2329
|
+
corresponding text value. If the attribute is undefined the line
|
|
2330
|
+
containing the attribute is dropped.</p><p>There are three types of attribute reference: <span class="emphasis"><em>Simple</em></span>, <span class="emphasis"><em>Conditional</em></span>
|
|
2331
|
+
and <span class="emphasis"><em>System</em></span>.</p><div class="itemizedlist"><p class="title"><b>Attribute reference behavior</b></p><ul type="disc"><li>
|
|
2332
|
+
You can suppress attribute reference expansion by placing a
|
|
2333
|
+
backslash character immediately in front of the opening brace
|
|
2334
|
+
character.
|
|
2335
|
+
</li><li>
|
|
2336
|
+
By default attribute references are not expanded in
|
|
2337
|
+
LiteralParagraphs, ListingBlocks or LiteralBlocks.
|
|
2338
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_simple_attributes_references"></a>24.1. Simple Attributes References</h3></div></div></div><p>Simple attribute references take the form <code class="literal">{<name>}</code>. If the
|
|
2339
|
+
attribute name is defined its text value is substituted otherwise the
|
|
2340
|
+
line containing the reference is dropped from the output.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_conditional_attribute_references"></a>24.2. Conditional Attribute References</h3></div></div></div><p>Additional parameters are used in conjunction with the attribute name
|
|
2341
|
+
to calculate a substitution value. Conditional attribute references
|
|
2342
|
+
take the following forms:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2343
|
+
<code class="literal">{<name>=<value>}</code>
|
|
2344
|
+
</span></dt><dd>
|
|
2345
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is
|
|
2346
|
+
undefined otherwise its value is substituted. <code class="literal"><value></code> can
|
|
2347
|
+
contain simple attribute references.
|
|
2348
|
+
</dd><dt><span class="term">
|
|
2349
|
+
<code class="literal">{<name>?<value>}</code>
|
|
2350
|
+
</span></dt><dd>
|
|
2351
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is defined
|
|
2352
|
+
otherwise an empty string is substituted. <code class="literal"><value></code> can
|
|
2353
|
+
contain simple attribute references.
|
|
2354
|
+
</dd><dt><span class="term">
|
|
2355
|
+
<code class="literal">{<name>!<value>}</code>
|
|
2356
|
+
</span></dt><dd>
|
|
2357
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is
|
|
2358
|
+
undefined otherwise an empty string is substituted. <code class="literal"><value></code>
|
|
2359
|
+
can contain simple attribute references.
|
|
2360
|
+
</dd><dt><span class="term">
|
|
2361
|
+
<code class="literal">{<name>#<value>}</code>
|
|
2362
|
+
</span></dt><dd>
|
|
2363
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is defined
|
|
2364
|
+
otherwise the undefined attribute entry causes the containing
|
|
2365
|
+
line to be dropped. <code class="literal"><value></code> can contain simple attribute
|
|
2366
|
+
references.
|
|
2367
|
+
</dd><dt><span class="term">
|
|
2368
|
+
<code class="literal">{<name>%<value>}</code>
|
|
2369
|
+
</span></dt><dd>
|
|
2370
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is not
|
|
2371
|
+
defined otherwise the containing line is dropped. <code class="literal"><value></code>
|
|
2372
|
+
can contain simple attribute references.
|
|
2373
|
+
</dd><dt><span class="term">
|
|
2374
|
+
<code class="literal">{<name>@<regexp>:<value1>[:<value2>]}</code>
|
|
2375
|
+
</span></dt><dd>
|
|
2376
|
+
<code class="literal"><value1></code> is substituted if the value of attribute <code class="literal"><name></code>
|
|
2377
|
+
matches the regular expression <code class="literal"><regexp></code> otherwise <code class="literal"><value2></code>
|
|
2378
|
+
is substituted. If attribute <code class="literal"><name></code> is not defined the
|
|
2379
|
+
containing line is dropped. If <code class="literal"><value2></code> is omitted an empty
|
|
2380
|
+
string is assumed. The values and the regular expression can
|
|
2381
|
+
contain simple attribute references. To embed colons in the
|
|
2382
|
+
values or the regular expression escape them with backslashes.
|
|
2383
|
+
</dd><dt><span class="term">
|
|
2384
|
+
<code class="literal">{<name>$<regexp>:<value1>[:<value2>]}</code>
|
|
2385
|
+
</span></dt><dd><p>
|
|
2386
|
+
Same behavior as the previous ternary attribute except for
|
|
2387
|
+
the following cases:
|
|
2388
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
2389
|
+
<code class="literal">{<name>$<regexp>:<value>}</code>
|
|
2390
|
+
</span></dt><dd>
|
|
2391
|
+
Substitutes <code class="literal"><value></code> if <code class="literal"><name></code> matches <code class="literal"><regexp></code>
|
|
2392
|
+
otherwise the result is undefined and the containing
|
|
2393
|
+
line is dropped.
|
|
2394
|
+
</dd><dt><span class="term">
|
|
2395
|
+
<code class="literal">{<name>$<regexp>::<value>}</code>
|
|
2396
|
+
</span></dt><dd>
|
|
2397
|
+
Substitutes <code class="literal"><value></code> if <code class="literal"><name></code> does not match
|
|
2398
|
+
<code class="literal"><regexp></code> otherwise the result is undefined and the
|
|
2399
|
+
containing line is dropped.
|
|
2400
|
+
</dd></dl></div></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_conditional_attribute_examples"></a>24.2.1. Conditional attribute examples</h4></div></div></div><p>Conditional attributes are mainly used in <span class="emphasis"><em>AsciiDoc</em></span> configuration
|
|
2401
|
+
files — see the distribution <code class="literal">.conf</code> files for examples.</p><div class="variablelist"><dl><dt><span class="term">
|
|
2402
|
+
Attribute equality test
|
|
2403
|
+
</span></dt><dd><p>
|
|
2404
|
+
If <code class="literal">{backend}</code> is <code class="literal">docbook</code> or <code class="literal">xhtml11</code> the example evaluates to
|
|
2405
|
+
“DocBook or XHTML backend” otherwise it evaluates to “some other
|
|
2406
|
+
backend”:
|
|
2407
|
+
</p><pre class="literallayout">{backend@docbook|xhtml11:DocBook or XHTML backend:some other backend}</pre></dd><dt><span class="term">
|
|
2408
|
+
Attribute value map
|
|
2409
|
+
</span></dt><dd><p>
|
|
2410
|
+
This example maps the <code class="literal">frame</code> attribute values [<code class="literal">topbot</code>, <code class="literal">all</code>,
|
|
2411
|
+
<code class="literal">none</code>, <code class="literal">sides</code>] to [<code class="literal">hsides</code>, <code class="literal">border</code>, <code class="literal">void</code>, <code class="literal">vsides</code>]:
|
|
2412
|
+
</p><pre class="literallayout">{frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides}</pre></dd></dl></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X24"></a>24.3. System Attribute References</h3></div></div></div><p>System attribute references generate the attribute text value by
|
|
2413
|
+
executing a predefined action that is parametrized by a single
|
|
2414
|
+
argument. The syntax is <code class="literal">{<action>:<argument>}</code>.</p><div class="variablelist"><dl><dt><span class="term">
|
|
2415
|
+
<code class="literal">{eval:<expression>}</code>
|
|
2416
|
+
</span></dt><dd>
|
|
2417
|
+
Substitutes the result of the Python <code class="literal"><expression></code>. If
|
|
2418
|
+
<code class="literal"><expression></code> evaluates to <code class="literal">None</code> or <code class="literal">False</code> the reference is
|
|
2419
|
+
deemed undefined and the line containing the reference is
|
|
2420
|
+
dropped from the output. If the expression evaluates to
|
|
2421
|
+
<code class="literal">True</code> the attribute evaluates to an empty string. In all
|
|
2422
|
+
remaining cases the attribute evaluates to a string
|
|
2423
|
+
representation of the <code class="literal"><expression></code> result.
|
|
2424
|
+
</dd><dt><span class="term">
|
|
2425
|
+
<code class="literal">{include:<filename>}</code>
|
|
2426
|
+
</span></dt><dd><p>
|
|
2427
|
+
Substitutes contents of the file named <code class="literal"><filename></code>.
|
|
2428
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2429
|
+
The included file is read at the time of attribute
|
|
2430
|
+
substitution.
|
|
2431
|
+
</li><li>
|
|
2432
|
+
If the file does not exist a warning is emitted and the line
|
|
2433
|
+
containing the reference is dropped from the output file.
|
|
2434
|
+
</li><li>
|
|
2435
|
+
Tabs are expanded based on the current <span class="emphasis"><em>tabsize</em></span> attribute
|
|
2436
|
+
value.
|
|
2437
|
+
</li></ul></div></dd><dt><span class="term">
|
|
2438
|
+
<code class="literal">{sys:<command>}</code>
|
|
2439
|
+
</span></dt><dd>
|
|
2440
|
+
Substitutes the stdout generated by the execution of the shell
|
|
2441
|
+
<code class="literal"><command></code>.
|
|
2442
|
+
</dd><dt><span class="term">
|
|
2443
|
+
<code class="literal">{sys2:<command>}</code>
|
|
2444
|
+
</span></dt><dd>
|
|
2445
|
+
Substitutes the stdout and stderr generated by the execution
|
|
2446
|
+
of the shell <code class="literal"><command></code>.
|
|
2447
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>System reference behavior</b></p><ul type="disc"><li>
|
|
2448
|
+
System attribute arguments can contain non-system attribute
|
|
2449
|
+
references.
|
|
2450
|
+
</li><li>
|
|
2451
|
+
Closing brace characters inside system attribute arguments must be
|
|
2452
|
+
escaped them with a backslash.
|
|
2453
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X60"></a>25. Intrinsic Attributes</h2></div></div></div><p>Intrinsic attributes are simple attributes that are created
|
|
2454
|
+
automatically from <span class="emphasis"><em>AsciiDoc</em></span> document header parameters, <code class="literal">asciidoc(1)</code>
|
|
2455
|
+
command-line arguments, execution parameters along with attributes
|
|
2456
|
+
defined in the default configuration files. Here's the list of
|
|
2457
|
+
predefined intrinsic attributes:</p><pre class="literallayout">{asciidoc-dir} the asciidoc(1) application directory
|
|
2458
|
+
{asciidoc-version} the version of asciidoc(1)
|
|
2459
|
+
{author} author's full name
|
|
2460
|
+
{authored} empty string '' if {author} or {email} defined,
|
|
2461
|
+
{authorinitials} author initials (from document header)
|
|
2462
|
+
{backend-<backend>} empty string ''
|
|
2463
|
+
{<backend>-<doctype>} empty string ''
|
|
2464
|
+
{backend} document backend specified by `-b` option
|
|
2465
|
+
{basebackend-<base>} empty string ''
|
|
2466
|
+
{basebackend} html or docbook
|
|
2467
|
+
{brvbar} broken vertical bar (|) character
|
|
2468
|
+
{date} document date (from document header)
|
|
2469
|
+
{docname} document file name without extension
|
|
2470
|
+
{doctitle} document title (from document header)
|
|
2471
|
+
{doctype-<doctype>} empty string ''
|
|
2472
|
+
{doctype} document type specified by `-d` option
|
|
2473
|
+
{email} author's email address (from document header)
|
|
2474
|
+
{empty} empty string ''
|
|
2475
|
+
{filetype-<fileext>} empty string ''
|
|
2476
|
+
{filetype} output file name file extension
|
|
2477
|
+
{firstname} author first name (from document header)
|
|
2478
|
+
{gt} greater than (>) character
|
|
2479
|
+
{id} running block id generated by BlockId elements
|
|
2480
|
+
{indir} document input directory name (note 1)
|
|
2481
|
+
{infile} input file name (note 1)
|
|
2482
|
+
{lastname} author last name (from document header)
|
|
2483
|
+
{listindex} the list index (1..) of the most recent list item
|
|
2484
|
+
{localdate} the current date
|
|
2485
|
+
{localtime} the current time
|
|
2486
|
+
{lt} less than (<) character
|
|
2487
|
+
{manname} manpage name (defined in NAME section)
|
|
2488
|
+
{manpurpose} manpage (defined in NAME section)
|
|
2489
|
+
{mantitle} document title minus the manpage volume number
|
|
2490
|
+
{manvolnum} manpage volume number (1..8) (from document header)
|
|
2491
|
+
{middlename} author middle name (from document header)
|
|
2492
|
+
{outdir} document output directory name (note 1)
|
|
2493
|
+
{outfile} output file name (note 1)
|
|
2494
|
+
{revision} document revision number (from document header)
|
|
2495
|
+
{sectnum} section number (in section titles)
|
|
2496
|
+
{title} section title (in titled elements)
|
|
2497
|
+
{user-dir} the ~/.asciidoc directory (if it exists)
|
|
2498
|
+
{verbose} defined as '' if --verbose command option specified</pre><div class="orderedlist"><p class="title"><b>NOTES</b></p><ol type="1"><li>
|
|
2499
|
+
Intrinsic attributes are global so avoid defining custom attributes
|
|
2500
|
+
with the same names.
|
|
2501
|
+
</li><li>
|
|
2502
|
+
<code class="literal">{infile}</code>, <code class="literal">{outdir}</code>, <code class="literal">{infile}</code>, <code class="literal">{indir}</code> attributes are
|
|
2503
|
+
effectively read-only (you can set them but it won't affect the
|
|
2504
|
+
input or output file paths).
|
|
2505
|
+
</li><li>
|
|
2506
|
+
See also the <a href="#X33" title="4.2. xhtml11">xhtml11</a> subsection for attributes that relate
|
|
2507
|
+
to <span class="emphasis"><em>AsciiDoc</em></span> XHTML file generation.
|
|
2508
|
+
</li><li>
|
|
2509
|
+
The entries that translate to blank strings are designed to be used
|
|
2510
|
+
for conditional text inclusion. You can also use the <code class="literal">ifdef</code>,
|
|
2511
|
+
<code class="literal">ifndef</code> and <code class="literal">endif</code> System macros for conditional inclusion.
|
|
2512
|
+
<sup>[<a id="id2550395" href="#ftn.id2550395">5</a>]</sup>
|
|
2513
|
+
</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="_block_element_definitions"></a>26. Block Element Definitions</h2></div></div></div><p>The syntax and behavior of Paragraph, DelimitedBlock, List and Table
|
|
2514
|
+
block elements is determined by block definitions contained in
|
|
2515
|
+
<a href="#X7" title="20. 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
|
|
2516
|
+
section entries. Each entry defines a block parameter controlling some
|
|
2517
|
+
aspect of the block's behavior. Here's an example:</p><pre class="screen">[blockdef-listing]
|
|
2518
|
+
delimiter=^-{4,}$
|
|
2519
|
+
template=listingblock
|
|
2520
|
+
presubs=specialcharacters,callouts</pre><p><span class="emphasis"><em>AsciiDoc</em></span> Paragraph, DelimitedBlock, List and Table block elements
|
|
2521
|
+
share a common subset of configuration file parameters:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2522
|
+
delimiter
|
|
2523
|
+
</span></dt><dd>
|
|
2524
|
+
A Python regular expression that matches the first line of a block
|
|
2525
|
+
element — in the case of DelimitedBlocks it also matches the last
|
|
2526
|
+
line. Table elements don't have an explicit delimiter — they
|
|
2527
|
+
synthesize their delimiters at runtime.
|
|
2528
|
+
</dd><dt><span class="term">
|
|
2529
|
+
template
|
|
2530
|
+
</span></dt><dd>
|
|
2531
|
+
The name of the configuration file markup template section that will
|
|
2532
|
+
envelope the block contents. The pipe | character is substituted for
|
|
2533
|
+
the block contents. List elements use a set of (list specific) tag
|
|
2534
|
+
parameters instead of a single template.
|
|
2535
|
+
</dd><dt><span class="term">
|
|
2536
|
+
options
|
|
2537
|
+
</span></dt><dd>
|
|
2538
|
+
A comma delimited list of element specific option names.
|
|
2539
|
+
</dd><dt><span class="term">
|
|
2540
|
+
subs, presubs, postsubs
|
|
2541
|
+
</span></dt><dd><div class="itemizedlist"><ul type="disc"><li>
|
|
2542
|
+
<span class="emphasis"><em>presubs</em></span> and <span class="emphasis"><em>postsubs</em></span> are lists of comma separated substitutions that are
|
|
2543
|
+
performed on the block contents. <span class="emphasis"><em>presubs</em></span> is applied first,
|
|
2544
|
+
<span class="emphasis"><em>postsubs</em></span> (if specified) second.
|
|
2545
|
+
</li><li>
|
|
2546
|
+
<span class="emphasis"><em>subs</em></span> is an alias for <span class="emphasis"><em>presubs</em></span>.
|
|
2547
|
+
</li><li>
|
|
2548
|
+
If a <span class="emphasis"><em>filter</em></span> is allowed (Paragraphs and DelimitedBlocks) and has
|
|
2549
|
+
been specified then <span class="emphasis"><em>presubs</em></span> and <span class="emphasis"><em>postsubs</em></span> substitutions are
|
|
2550
|
+
performed before and after the filter is run respectively.
|
|
2551
|
+
</li><li>
|
|
2552
|
+
Allowed values: <span class="emphasis"><em>specialcharacters</em></span>, <span class="emphasis"><em>quotes</em></span>, <span class="emphasis"><em>specialwords</em></span>,
|
|
2553
|
+
<span class="emphasis"><em>replacements</em></span>, <span class="emphasis"><em>macros</em></span>, <span class="emphasis"><em>attributes</em></span>, <span class="emphasis"><em>callouts</em></span>.
|
|
2554
|
+
</li><li><p>
|
|
2555
|
+
The following composite values are also allowed:
|
|
2556
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
2557
|
+
<span class="emphasis"><em>none</em></span>
|
|
2558
|
+
</span></dt><dd>
|
|
2559
|
+
No substitutions.
|
|
2560
|
+
</dd><dt><span class="term">
|
|
2561
|
+
<span class="emphasis"><em>normal</em></span>
|
|
2562
|
+
</span></dt><dd>
|
|
2563
|
+
The following substitutions:
|
|
2564
|
+
<span class="emphasis"><em>specialcharacters</em></span>,<span class="emphasis"><em>quotes</em></span>,<span class="emphasis"><em>attributes</em></span>,<span class="emphasis"><em>specialwords</em></span>,
|
|
2565
|
+
<span class="emphasis"><em>replacements</em></span>,<span class="emphasis"><em>macros</em></span>,<span class="emphasis"><em>passthroughs</em></span>.
|
|
2566
|
+
</dd><dt><span class="term">
|
|
2567
|
+
<span class="emphasis"><em>verbatim</em></span>
|
|
2568
|
+
</span></dt><dd>
|
|
2569
|
+
<span class="emphasis"><em>specialcharacters</em></span> and <span class="emphasis"><em>callouts</em></span> substitutions.
|
|
2570
|
+
</dd></dl></div></li><li>
|
|
2571
|
+
<span class="emphasis"><em>normal</em></span> and <span class="emphasis"><em>verbatim</em></span> substitutions can be redefined by with
|
|
2572
|
+
<code class="literal">subsnormal</code> and <code class="literal">subsverbatim</code> entries in a configuration file
|
|
2573
|
+
<code class="literal">[miscellaneous]</code> section.
|
|
2574
|
+
</li><li>
|
|
2575
|
+
The substitutions are processed in the order in which they are
|
|
2576
|
+
listed and can appear more than once.
|
|
2577
|
+
</li></ul></div></dd><dt><span class="term">
|
|
2578
|
+
filter
|
|
2579
|
+
</span></dt><dd>
|
|
2580
|
+
This optional entry specifies an executable shell command for
|
|
2581
|
+
processing block content (Paragraphs and DelimitedBlocks). The
|
|
2582
|
+
filter command can contain attribute references.
|
|
2583
|
+
</dd><dt><span class="term">
|
|
2584
|
+
posattrs
|
|
2585
|
+
</span></dt><dd><p>
|
|
2586
|
+
Optional comma separated list of positional attribute names. This
|
|
2587
|
+
list maps positional attributes (in the block's <a href="#X21" title="23. Attribute Lists">attribute list</a>) to named block attributes. The following example, from the
|
|
2588
|
+
QuoteBlock definition, maps the first and section positional
|
|
2589
|
+
attributes:
|
|
2590
|
+
</p><pre class="literallayout">posattrs=attribution,citetitle</pre></dd><dt><span class="term">
|
|
2591
|
+
style
|
|
2592
|
+
</span></dt><dd>
|
|
2593
|
+
This optional parameter specifies the default style name.
|
|
2594
|
+
</dd><dt><span class="term">
|
|
2595
|
+
<stylename>-style
|
|
2596
|
+
</span></dt><dd>
|
|
2597
|
+
Optional style definition (see <a href="#X23" title="26.1. Styles">Styles</a> below).
|
|
2598
|
+
</dd></dl></div><p>The following block parameters behave like document attributes and can
|
|
2599
|
+
be set in block attribute lists and style definitions: <span class="emphasis"><em>template</em></span>,
|
|
2600
|
+
<span class="emphasis"><em>options</em></span>, <span class="emphasis"><em>subs</em></span>, <span class="emphasis"><em>presubs</em></span>, <span class="emphasis"><em>postsubs</em></span>, <span class="emphasis"><em>filter</em></span>.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X23"></a>26.1. Styles</h3></div></div></div><p>A style is a set of block attributes bundled as a single named
|
|
2601
|
+
attribute. The following example defines a style named <span class="emphasis"><em>verbatim</em></span>:</p><pre class="literallayout">verbatim-style=template="literalblock",subs="verbatim",font="monospaced"</pre><div class="itemizedlist"><ul type="disc"><li>
|
|
2602
|
+
All style parameter names must be suffixed with <code class="literal">-style</code> and the
|
|
2603
|
+
style parameter value is in the form of a list of <a href="#X21" title="23. Attribute Lists">named attributes</a>.
|
|
2604
|
+
</li><li>
|
|
2605
|
+
Multi-item style attributes (<span class="emphasis"><em>subs</em></span>,<span class="emphasis"><em>presubs</em></span>,<span class="emphasis"><em>postsubs</em></span>,<span class="emphasis"><em>posattrs</em></span>)
|
|
2606
|
+
must be specified using Python tuple syntax rather than a simple
|
|
2607
|
+
list of values as they in separate entries e.g.
|
|
2608
|
+
<code class="literal">postsubs=("callouts",)</code> not <code class="literal">postsubs="callouts"</code>.
|
|
2609
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_paragraphs_2"></a>26.2. Paragraphs</h3></div></div></div><p>Paragraph translation is controlled by <code class="literal">[paradef*]</code> configuration file
|
|
2610
|
+
section entries. Users can define new types of paragraphs and modify
|
|
2611
|
+
the behavior of existing types by editing <span class="emphasis"><em>AsciiDoc</em></span> configuration
|
|
2612
|
+
files.</p><p>Here is the shipped Default paragraph definition:</p><pre class="screen">[paradef-default]
|
|
2613
|
+
delimiter=(?P<text>\S.*)
|
|
2614
|
+
template=paragraph</pre><p>The Default paragraph definition has a couple of special properties:</p><div class="orderedlist"><ol type="1"><li>
|
|
2615
|
+
It must exist and be defined in a configuration file section named
|
|
2616
|
+
<code class="literal">[paradef-default]</code>.
|
|
2617
|
+
</li><li>
|
|
2618
|
+
Irrespective of its position in the configuration files default
|
|
2619
|
+
paragraph document matches are attempted only after trying all
|
|
2620
|
+
other paragraph types.
|
|
2621
|
+
</li></ol></div><p>Paragraph specific block parameter notes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2622
|
+
delimiter
|
|
2623
|
+
</span></dt><dd>
|
|
2624
|
+
This regular expression must contain the named group <span class="emphasis"><em>text</em></span> which
|
|
2625
|
+
matches the text on the first line. Paragraphs are terminated by a
|
|
2626
|
+
blank line, the end of file, or the start of a DelimitedBlock.
|
|
2627
|
+
</dd><dt><span class="term">
|
|
2628
|
+
options
|
|
2629
|
+
</span></dt><dd>
|
|
2630
|
+
The only allowable option is <span class="emphasis"><em>listelement</em></span>. The <span class="emphasis"><em>listelement</em></span>
|
|
2631
|
+
option specifies that paragraphs of this type will automatically be
|
|
2632
|
+
considered part of immediately preceding list items.
|
|
2633
|
+
</dd></dl></div><div class="orderedlist"><p class="title"><b>Paragraph processing proceeds as follows:</b></p><ol type="1"><li>
|
|
2634
|
+
The paragraph text is aligned to the left margin.
|
|
2635
|
+
</li><li>
|
|
2636
|
+
Optional <span class="emphasis"><em>presubs</em></span> inline substitutions are performed on the
|
|
2637
|
+
paragraph text.
|
|
2638
|
+
</li><li>
|
|
2639
|
+
If a filter command is specified it is executed and the paragraph
|
|
2640
|
+
text piped to its standard input; the filter output replaces the
|
|
2641
|
+
paragraph text.
|
|
2642
|
+
</li><li>
|
|
2643
|
+
Optional <span class="emphasis"><em>postsubs</em></span> inline substitutions are performed on the
|
|
2644
|
+
paragraph text.
|
|
2645
|
+
</li><li>
|
|
2646
|
+
The paragraph text is enveloped by the paragraph's markup template
|
|
2647
|
+
and written to the output file.
|
|
2648
|
+
</li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_delimited_blocks_2"></a>26.3. Delimited Blocks</h3></div></div></div><p>DelimitedBlock specific block definition notes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2649
|
+
options
|
|
2650
|
+
</span></dt><dd><p>
|
|
2651
|
+
Allowed values are:
|
|
2652
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
2653
|
+
<span class="emphasis"><em>sectionbody</em></span>
|
|
2654
|
+
</span></dt><dd>
|
|
2655
|
+
The block contents are processed as a SectionBody.
|
|
2656
|
+
</dd><dt><span class="term">
|
|
2657
|
+
<span class="emphasis"><em>skip</em></span>
|
|
2658
|
+
</span></dt><dd>
|
|
2659
|
+
The block is treated as a comment (see <span class="emphasis"><em>CommentBlocks</em></span>).
|
|
2660
|
+
</dd><dt><span class="term">
|
|
2661
|
+
<span class="emphasis"><em>list</em></span>
|
|
2662
|
+
</span></dt><dd>
|
|
2663
|
+
The block is a <a href="#X29" title="13.8. List Block">list block</a>.
|
|
2664
|
+
</dd></dl></div></dd></dl></div><p><span class="emphasis"><em>presubs</em></span>, <span class="emphasis"><em>postsubs</em></span> and <span class="emphasis"><em>filter</em></span> entries are meaningless when
|
|
2665
|
+
<span class="emphasis"><em>sectionbody</em></span>, <span class="emphasis"><em>skip</em></span> or <span class="emphasis"><em>list</em></span> options are set.</p><p>DelimitedBlock processing proceeds as follows:</p><div class="orderedlist"><ol type="1"><li>
|
|
2666
|
+
Optional <span class="emphasis"><em>presubs</em></span> substitutions are performed on the block
|
|
2667
|
+
contents.
|
|
2668
|
+
</li><li>
|
|
2669
|
+
If a filter is specified it is executed and the block's contents
|
|
2670
|
+
piped to its standard input. The filter output replaces the block
|
|
2671
|
+
contents.
|
|
2672
|
+
</li><li>
|
|
2673
|
+
Optional <span class="emphasis"><em>postsubs</em></span> substitutions are performed on the block
|
|
2674
|
+
contents.
|
|
2675
|
+
</li><li>
|
|
2676
|
+
The block contents is enveloped by the block's markup template and
|
|
2677
|
+
written to the output file.
|
|
2678
|
+
</li></ol></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Attribute expansion is performed on the block filter command
|
|
2679
|
+
before it is executed, this is useful for passing arguments to the
|
|
2680
|
+
filter.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_lists"></a>26.4. Lists</h3></div></div></div><p>List behavior and syntax is determined by <code class="literal">[listdef*]</code> configuration
|
|
2681
|
+
file sections. The user can change existing list behavior and add new
|
|
2682
|
+
list types by editing configuration files.</p><p>List specific block definition notes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2683
|
+
type
|
|
2684
|
+
</span></dt><dd>
|
|
2685
|
+
This is either <span class="emphasis"><em>bulleted</em></span>,<span class="emphasis"><em>numbered</em></span>,<span class="emphasis"><em>labeled</em></span> or <span class="emphasis"><em>callout</em></span>.
|
|
2686
|
+
</dd><dt><span class="term">
|
|
2687
|
+
delimiter
|
|
2688
|
+
</span></dt><dd>
|
|
2689
|
+
A Python regular expression that matches the first line of a
|
|
2690
|
+
list element entry. This expression must contain the named
|
|
2691
|
+
group <span class="emphasis"><em>text</em></span> which matches text in the first line.
|
|
2692
|
+
</dd><dt><span class="term">
|
|
2693
|
+
subs
|
|
2694
|
+
</span></dt><dd>
|
|
2695
|
+
Substitutions that are performed on list item text and terms.
|
|
2696
|
+
</dd><dt><span class="term">
|
|
2697
|
+
listtag
|
|
2698
|
+
</span></dt><dd>
|
|
2699
|
+
The name of the tag that envelopes the List.
|
|
2700
|
+
</dd><dt><span class="term">
|
|
2701
|
+
itemtag
|
|
2702
|
+
</span></dt><dd>
|
|
2703
|
+
The name of the tag that envelopes the ListItem.
|
|
2704
|
+
</dd><dt><span class="term">
|
|
2705
|
+
texttag
|
|
2706
|
+
</span></dt><dd>
|
|
2707
|
+
The name of the tag that envelopes the list item text.
|
|
2708
|
+
</dd><dt><span class="term">
|
|
2709
|
+
labeltag
|
|
2710
|
+
</span></dt><dd>
|
|
2711
|
+
The name of the tag that envelopes a variable list label.
|
|
2712
|
+
</dd><dt><span class="term">
|
|
2713
|
+
entrytag
|
|
2714
|
+
</span></dt><dd>
|
|
2715
|
+
The name of the tag that envelopes a labeled list entry.
|
|
2716
|
+
</dd></dl></div><p>The tag entries map the <span class="emphasis"><em>AsciiDoc</em></span> list structure to backend markup; see
|
|
2717
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">.conf</code> configuration files for examples.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_tables_2"></a>26.5. Tables</h3></div></div></div><p>Table behavior and syntax is determined by <code class="literal">[tabledef*]</code> configuration
|
|
2718
|
+
file sections. The user can change existing list behavior and add new
|
|
2719
|
+
list types by editing configuration files.</p><p>Table specific block definition notes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2720
|
+
fillchar
|
|
2721
|
+
</span></dt><dd>
|
|
2722
|
+
A single character that fills table ruler and underline
|
|
2723
|
+
lines.
|
|
2724
|
+
</dd><dt><span class="term">
|
|
2725
|
+
subs
|
|
2726
|
+
</span></dt><dd>
|
|
2727
|
+
Substitutions performed on table data items.
|
|
2728
|
+
</dd><dt><span class="term">
|
|
2729
|
+
format
|
|
2730
|
+
</span></dt><dd>
|
|
2731
|
+
The source row data format (<span class="emphasis"><em>fixed</em></span>, <span class="emphasis"><em>csv</em></span> or <span class="emphasis"><em>dsv</em></span>).
|
|
2732
|
+
</dd><dt><span class="term">
|
|
2733
|
+
comspec
|
|
2734
|
+
</span></dt><dd>
|
|
2735
|
+
The table <span class="emphasis"><em>comspec</em></span> tag definition.
|
|
2736
|
+
</dd><dt><span class="term">
|
|
2737
|
+
headrow, footrow, bodyrow
|
|
2738
|
+
</span></dt><dd>
|
|
2739
|
+
Table header, footer and body row tag definitions. <span class="emphasis"><em>headrow</em></span> and
|
|
2740
|
+
<span class="emphasis"><em>footrow</em></span> table definition entries default to <span class="emphasis"><em>bodyrow</em></span> if
|
|
2741
|
+
they are undefined.
|
|
2742
|
+
</dd><dt><span class="term">
|
|
2743
|
+
headdata, footdata, bodydata
|
|
2744
|
+
</span></dt><dd>
|
|
2745
|
+
Table header, footer and body data tag definitions. <span class="emphasis"><em>headdata</em></span> and
|
|
2746
|
+
<span class="emphasis"><em>footdata</em></span> table definition entries default to <span class="emphasis"><em>bodydata</em></span> if they
|
|
2747
|
+
are undefined.
|
|
2748
|
+
</dd></dl></div><p><a id="X4"></a>Table behavior is also influenced by the following <code class="literal">[miscellaneous]</code>
|
|
2749
|
+
configuration file entries:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2750
|
+
textwidth
|
|
2751
|
+
</span></dt><dd>
|
|
2752
|
+
The page width (in characters) of the source text. This setting is
|
|
2753
|
+
compared to the table ruler width when calculating the relative
|
|
2754
|
+
size of character ruler tables on the output page.
|
|
2755
|
+
</dd><dt><span class="term">
|
|
2756
|
+
pagewidth
|
|
2757
|
+
</span></dt><dd>
|
|
2758
|
+
This integer value is the printable width of the output media. Used
|
|
2759
|
+
to calculate <span class="emphasis"><em>colwidth</em></span> and <span class="emphasis"><em>tablewidth</em></span> substitution values.
|
|
2760
|
+
</dd><dt><span class="term">
|
|
2761
|
+
pageunits
|
|
2762
|
+
</span></dt><dd>
|
|
2763
|
+
The units of width in output markup width attribute values.
|
|
2764
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>Table definition behavior</b></p><ul type="disc"><li>
|
|
2765
|
+
The output markup generation is specifically designed to work with
|
|
2766
|
+
the HTML and CALS (DocBook) table models, but should be adaptable to
|
|
2767
|
+
most XML table schema.
|
|
2768
|
+
</li><li>
|
|
2769
|
+
Table definitions can be “mixed in” from multiple cascading
|
|
2770
|
+
configuration files.
|
|
2771
|
+
</li><li>
|
|
2772
|
+
New table definitions inherit the default table definition
|
|
2773
|
+
(<span class="emphasis"><em>[tabledef-default]</em></span>) so you only need to override those conf file
|
|
2774
|
+
entries that require modification when defining a new table type.
|
|
2775
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X59"></a>27. Filters</h2></div></div></div><p>Filters are external shell commands used to process Paragraph and
|
|
2776
|
+
DelimitedBlock content; they are specified in configuration file
|
|
2777
|
+
Paragraph and DelimitedBlock definitions.</p><p>There's nothing special about the filters, they're just standard UNIX
|
|
2778
|
+
filters: they read text from the standard input, process it, and write
|
|
2779
|
+
to the standard output.</p><p>Attribute substitution is performed on the filter command prior to
|
|
2780
|
+
execution — attributes can be used to pass parameters from the
|
|
2781
|
+
<span class="emphasis"><em>AsciiDoc</em></span> source document to the filter.</p><div class="warning" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="./images/icons/warning.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Filters can potentially generate unsafe output. Before
|
|
2782
|
+
installing a filter you should verify that it can't be coerced into
|
|
2783
|
+
generating malicious output or exposing sensitive information.</p></td></tr></table></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>Filter functionality is currently only available on POSIX
|
|
2784
|
+
platforms (this includes Cygwin).</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_filter_search_paths"></a>27.1. Filter Search Paths</h3></div></div></div><p>If the filter command does not specify a directory path then
|
|
2785
|
+
<code class="literal">asciidoc(1)</code> searches for the command:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2786
|
+
First it looks in the user's <code class="literal">$HOME/.asciidoc/filters</code> directory.
|
|
2787
|
+
</li><li>
|
|
2788
|
+
Next the <code class="literal">/etc/asciidoc/filters</code> directory is searched.
|
|
2789
|
+
</li><li>
|
|
2790
|
+
Then it looks in the <code class="literal">asciidoc(1)</code> <code class="literal">./filters</code> directory.
|
|
2791
|
+
</li><li>
|
|
2792
|
+
Finally it relies on the executing shell to search the environment
|
|
2793
|
+
search path (<code class="literal">$PATH</code>).
|
|
2794
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_filter_configuration_files"></a>27.2. Filter Configuration Files</h3></div></div></div><p>Filters are normally accompanied by a configuration file containing a
|
|
2795
|
+
Paragraph or DelimitedBlock definition along with corresponding markup
|
|
2796
|
+
templates.</p><p>There are two ways to implement filters:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2797
|
+
As a new Paragraph or DelimitedBlock definition.
|
|
2798
|
+
</li><li>
|
|
2799
|
+
By styling an existing Paragraph or DelimitedBlock using a <span class="emphasis"><em>style</em></span>
|
|
2800
|
+
configuration entry — the <span class="emphasis"><em>source highlight</em></span> and <span class="emphasis"><em>music</em></span> filters
|
|
2801
|
+
use this technique to customize the ListingBlock. By convention the
|
|
2802
|
+
style is given the same name as the filter.
|
|
2803
|
+
</li></ul></div><p><code class="literal">asciidoc(1)</code> auto-loads all <code class="literal">.conf</code> files found in the filter search
|
|
2804
|
+
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>27.3. Code Filter</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes with a simple minded for highlighting source code
|
|
2805
|
+
keywords and comments. See also the
|
|
2806
|
+
<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 —
|
|
2807
|
+
it's much to simplistic to be passed off as a code syntax highlighter.
|
|
2808
|
+
If you want a full featured multi-language highlighter use the
|
|
2809
|
+
<a href="#X57" title="27.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>.</p></td></tr></table></div><pre class="literallayout">.Code filter example
|
|
2810
|
+
[code,python]
|
|
2811
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
2812
|
+
''' A multi-line
|
|
2813
|
+
comment.'''
|
|
2814
|
+
def sub_word(mo):
|
|
2815
|
+
''' Single line comment.'''
|
|
2816
|
+
word = mo.group('word') # Inline comment
|
|
2817
|
+
if word in keywords[language]:
|
|
2818
|
+
return quote + word + quote
|
|
2819
|
+
else:
|
|
2820
|
+
return word
|
|
2821
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</pre><p>Outputs:</p><div class="example"><a id="id2552123"></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>
|
|
2822
|
+
<span class="emphasis"><em> comment.'''</em></span>
|
|
2823
|
+
<span class="strong"><strong>def</strong></span> sub_word(mo):
|
|
2824
|
+
<span class="emphasis"><em> ''' Single line comment.'''</em></span>
|
|
2825
|
+
word = mo.group('word') <span class="emphasis"><em># Inline comment</em></span>
|
|
2826
|
+
<span class="strong"><strong>if</strong></span> word <span class="strong"><strong>in</strong></span> keywords[language]:
|
|
2827
|
+
<span class="strong"><strong>return</strong></span> quote + word + quote
|
|
2828
|
+
<span class="strong"><strong>else</strong></span>:
|
|
2829
|
+
<span class="strong"><strong>return</strong></span> word</pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X57"></a>27.4. Source Code Highlighter Filter</h3></div></div></div><p>A
|
|
2830
|
+
<a href="http://www.methods.co.nz/asciidoc/source-highlight-filter.html" target="_top">source
|
|
2831
|
+
code highlighter filter</a> can be found in the <span class="emphasis"><em>AsciiDoc</em></span> distribution
|
|
2832
|
+
<code class="literal">./filters</code> directory.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X58"></a>27.5. Music Filter</h3></div></div></div><p>A <a href="http://www.methods.co.nz/asciidoc/music-filter.html" target="_top">music filter</a> is
|
|
2833
|
+
included in the distribution <code class="literal">./filters</code> directory. It translates
|
|
2834
|
+
music in <a href="http://lilypond.org/" target="_top">LilyPond</a> or
|
|
2835
|
+
<a href="http://abcnotation.org.uk/" target="_top">ABC</a> notation to standard Western classical
|
|
2836
|
+
notation in the form of a trimmed PNG image which is automatically
|
|
2837
|
+
inserted into the output document.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X12"></a>28. Converting DocBook to other file formats</h2></div></div></div><p>DocBook files are validated, parsed and translated by a combination of
|
|
2838
|
+
applications collectively called a DocBook <span class="emphasis"><em>tool chain</em></span>. The function
|
|
2839
|
+
of a tool chain is to read the DocBook markup (produced by <span class="emphasis"><em>AsciiDoc</em></span>)
|
|
2840
|
+
and transform it to a presentation format (for example HTML, PDF, HTML
|
|
2841
|
+
Help, DVI, PostScript, LaTeX).</p><p>A wide range of user output format requirements coupled with a choice
|
|
2842
|
+
of available tools and stylesheets results in many valid tool chain
|
|
2843
|
+
combinations.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X43"></a>28.1. a2x Toolchain Wrapper</h3></div></div></div><p>One of the biggest hurdles for new users is installing, configuring
|
|
2844
|
+
and using a DocBook XML toolchain. <code class="literal"><code class="literal">a2x(1)</code></code> can help — it's a
|
|
2845
|
+
toolchain wrapper command that will generate XHTML (chunked and
|
|
2846
|
+
unchunked), PDF, DVI, PS, LaTeX, man page, HTML Help and text file
|
|
2847
|
+
outputs from an <span class="emphasis"><em>AsciiDoc</em></span> text file. <code class="literal">a2x(1)</code> does all the grunt work
|
|
2848
|
+
associated with generating and sequencing the toolchain commands and
|
|
2849
|
+
managing intermediate and output files. <code class="literal">a2x(1)</code> also optionally
|
|
2850
|
+
deploys admonition and navigation icons and a CSS stylesheet. See the
|
|
2851
|
+
<code class="literal"><code class="literal">a2x(1)</code></code> man page for more details. All you need is
|
|
2852
|
+
<a href="#X40" title="???TITLE???">xsltproc(1)</a>, <a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a> and, optionally
|
|
2853
|
+
<a href="#X31" title="???TITLE???">dblatex</a> or <a href="#X14" title="???TITLE???">FOP</a> (if you want PDF), or <code class="literal">lynx(1)</code> (if you
|
|
2854
|
+
want text).</p><p>The following examples generate <code class="literal">doc/source-highlight-filter.pdf</code> from
|
|
2855
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">doc/source-highlight-filter.txt</code> source file. The first
|
|
2856
|
+
example uses <code class="literal">dblatex(1)</code> (the default PDF generator) the second
|
|
2857
|
+
example forces FOP to be used:</p><pre class="literallayout">$ a2x -f pdf doc/source-highlight-filter.txt
|
|
2858
|
+
$ a2x -f pdf --fop-options="" doc/source-highlight-filter.txt</pre><p>See the <code class="literal"><code class="literal">a2x(1)</code></code> man page for details.</p><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Use the <code class="literal">—verbose</code> command-line option to view executed
|
|
2859
|
+
toolchain commands.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_html_generation"></a>28.2. HTML generation</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> produces nicely styled HTML directly without requiring a
|
|
2860
|
+
DocBook toolchain but there are also advantages in going the DocBook
|
|
2861
|
+
route:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2862
|
+
HTML from DocBook includes automatically generated indexes, tables
|
|
2863
|
+
of contents, footnotes, lists of figures and tables.
|
|
2864
|
+
</li><li>
|
|
2865
|
+
DocBook toolchains can also (optionally) generate separate (chunked)
|
|
2866
|
+
linked HTML pages for each document section.
|
|
2867
|
+
</li><li>
|
|
2868
|
+
Toolchain processing performs link and document validity checks.
|
|
2869
|
+
</li><li>
|
|
2870
|
+
If the DocBook <span class="emphasis"><em>lang</em></span> attribute is set then things like table of
|
|
2871
|
+
contents, revision history, figure and table captions and admonition
|
|
2872
|
+
captions will be output in the specified language (setting the
|
|
2873
|
+
<span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>lang</em></span> attribute sets the DocBook <span class="emphasis"><em>lang</em></span> attribute).
|
|
2874
|
+
</li></ul></div><p>On the other hand, HTML output directly from <span class="emphasis"><em>AsciiDoc</em></span> is much faster,
|
|
2875
|
+
is easily customized and can be used in situations where there is no
|
|
2876
|
+
suitable DocBook toolchain (see the
|
|
2877
|
+
<a 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>28.3. PDF generation</h3></div></div></div><p>There are two commonly used tools to generate PDFs from DocBook,
|
|
2878
|
+
<a href="#X31" title="???TITLE???">dblatex</a> and <a href="#X14" title="???TITLE???">FOP</a>.</p><div class="itemizedlist"><p class="title"><b>dblatex or FOP?</b></p><ul type="disc"><li>
|
|
2879
|
+
<span class="emphasis"><em>dblatex</em></span> is easier to install, there's zero configuration
|
|
2880
|
+
required and no Java VM to install — it just works out of the box.
|
|
2881
|
+
</li><li>
|
|
2882
|
+
<span class="emphasis"><em>dblatex</em></span> source code highlighting and numbering is superb.
|
|
2883
|
+
</li><li>
|
|
2884
|
+
<span class="emphasis"><em>dblatex</em></span> is easier to use as it converts DocBook directly to PDF
|
|
2885
|
+
whereas before using <span class="emphasis"><em>FOP</em></span> you have to convert DocBook to XML-FO
|
|
2886
|
+
using <a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a>.
|
|
2887
|
+
</li><li>
|
|
2888
|
+
<span class="emphasis"><em>FOP</em></span> is more feature complete (for example, callouts are processed
|
|
2889
|
+
inside literal layouts) and arguably produces nicer looking output.
|
|
2890
|
+
</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>28.4. HTML Help generation</h3></div></div></div><div class="orderedlist"><ol type="1"><li>
|
|
2891
|
+
Convert DocBook XML documents to HTML Help compiler source files
|
|
2892
|
+
using <a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a> and <a href="#X40" title="???TITLE???">xsltproc(1)</a>.
|
|
2893
|
+
</li><li>
|
|
2894
|
+
Convert the HTML Help source (<code class="literal">.hhp</code> and <code class="literal">.html</code>) files to HTML Help
|
|
2895
|
+
(<code class="literal">.chm</code>) files using the <a href="#X67" title="???TITLE???">Microsoft HTML Help Compiler</a>.
|
|
2896
|
+
</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>28.5. Toolchain components summary</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
2897
|
+
<span class="emphasis"><em>AsciiDoc</em></span>
|
|
2898
|
+
</span></dt><dd>
|
|
2899
|
+
Converts <span class="emphasis"><em>AsciiDoc</em></span> (<code class="literal">.txt</code>) files to DocBook XML (<code class="literal">.xml</code>) files.
|
|
2900
|
+
</dd></dl></div><div class="variablelist"><a id="X13"></a><dl><dt><span class="term">
|
|
2901
|
+
<a href="http://docbook.sourceforge.net/projects/xsl/" target="_top">DocBook XSL Stylesheets</a>
|
|
2902
|
+
</span></dt><dd>
|
|
2903
|
+
These are a set of XSL stylesheets containing rules for converting
|
|
2904
|
+
DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
|
|
2905
|
+
The stylesheets are used in conjunction with an XML parser such as
|
|
2906
|
+
<a href="#X40" title="???TITLE???">xsltproc(1)</a>.
|
|
2907
|
+
</dd></dl></div><div class="variablelist"><a id="X40"></a><dl><dt><span class="term">
|
|
2908
|
+
<a href="http://www.xmlsoft.org" target="_top">xsltproc</a>
|
|
2909
|
+
</span></dt><dd>
|
|
2910
|
+
An XML parser for applying XSLT stylesheets (in our case the
|
|
2911
|
+
<a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a>) to XML documents.
|
|
2912
|
+
</dd></dl></div><div class="variablelist"><a id="X31"></a><dl><dt><span class="term">
|
|
2913
|
+
<a href="http://dblatex.sourceforge.net/" target="_top">dblatex</a>
|
|
2914
|
+
</span></dt><dd>
|
|
2915
|
+
Generates PDF, DVI, PostScript and LaTeX formats directly from
|
|
2916
|
+
DocBook source via the intermediate LaTeX typesetting language —
|
|
2917
|
+
uses <a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a>, <a href="#X40" title="???TITLE???">xsltproc(1)</a> and
|
|
2918
|
+
<code class="literal">latex(1)</code>.
|
|
2919
|
+
</dd></dl></div><div class="variablelist"><a id="X14"></a><dl><dt><span class="term">
|
|
2920
|
+
<a href="http://xml.apache.org/fop/" target="_top">FOP</a>
|
|
2921
|
+
</span></dt><dd>
|
|
2922
|
+
The Apache Formatting Objects Processor converts XSL-FO (<code class="literal">.fo</code>)
|
|
2923
|
+
files to PDF files. The XSL-FO files are generated from DocBook
|
|
2924
|
+
source files using <a href="#X13" title="???TITLE???">DocBook XSL Stylesheets</a> and
|
|
2925
|
+
<a href="#X40" title="???TITLE???">xsltproc(1)</a>.
|
|
2926
|
+
</dd></dl></div><div class="variablelist"><a id="X67"></a><dl><dt><span class="term">
|
|
2927
|
+
Microsoft Help Compiler
|
|
2928
|
+
</span></dt><dd>
|
|
2929
|
+
The Microsoft HTML Help Compiler (<code class="literal">hhc.exe</code>) is a command-line tool
|
|
2930
|
+
that converts HTML Help source files to a single HTML Help (<code class="literal">.chm</code>)
|
|
2931
|
+
file. It runs on MS Windows platforms and can be downloaded from
|
|
2932
|
+
<a href="http://www.microsoft.com" target="_top">http://www.microsoft.com</a>.
|
|
2933
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_asciidoc_dblatex_configuration_files"></a>28.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
|
|
2934
|
+
<code class="literal">asciidoc-dblatex.xsl</code> (customized XSL parameter settings) and
|
|
2935
|
+
<code class="literal">asciidoc-dblatex.sty</code> (customized LaTeX settings). These are examples
|
|
2936
|
+
of optional <a href="#X31" title="???TITLE???">dblatex</a> output customization and are used by
|
|
2937
|
+
<a href="#X43" title="28.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>28.7. AsciiDoc DocBook XSL Stylesheets drivers</h3></div></div></div><p>You will have noticed that the distributed HTML and HTML Help
|
|
2938
|
+
documentation files (for example <code class="literal">./doc/asciidoc.html</code>) are not the
|
|
2939
|
+
plain outputs produced using the default <span class="emphasis"><em>DocBook XSL Stylesheets</em></span>
|
|
2940
|
+
configuration. This is because they have been processed using
|
|
2941
|
+
customized DocBook XSL Stylesheets along with (in the case of HTML
|
|
2942
|
+
outputs) the custom <code class="literal">./stylesheets/docbook.css</code> CSS stylesheet.</p><p>You'll find the customized DocBook XSL drivers along with additional
|
|
2943
|
+
documentation in the distribution <code class="literal">./docbook-xsl</code> directory. The
|
|
2944
|
+
examples that follow are executed from the distribution documentation
|
|
2945
|
+
(<code class="literal">./doc</code>) directory.</p><div class="variablelist"><dl><dt><span class="term">
|
|
2946
|
+
<code class="literal">common.xsl</code>
|
|
2947
|
+
</span></dt><dd>
|
|
2948
|
+
Shared driver parameters. This file is not used directly but is
|
|
2949
|
+
included in all the following drivers.
|
|
2950
|
+
</dd><dt><span class="term">
|
|
2951
|
+
<code class="literal">chunked.xsl</code>
|
|
2952
|
+
</span></dt><dd><p>
|
|
2953
|
+
Generate chunked XHTML (separate HTML pages for each document
|
|
2954
|
+
section) in the <code class="literal">./doc/chunked</code> directory. For example:
|
|
2955
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook asciidoc.txt
|
|
2956
|
+
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml</pre></dd><dt><span class="term">
|
|
2957
|
+
<code class="literal">fo.xsl</code>
|
|
2958
|
+
</span></dt><dd><p>
|
|
2959
|
+
Generate XSL Formatting Object (<code class="literal">.fo</code>) files for subsequent PDF
|
|
2960
|
+
file generation using FOP. For example:
|
|
2961
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook article.txt
|
|
2962
|
+
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
|
|
2963
|
+
$ fop.sh article.fo article.pdf</pre></dd><dt><span class="term">
|
|
2964
|
+
<code class="literal">htmlhelp.xsl</code>
|
|
2965
|
+
</span></dt><dd><p>
|
|
2966
|
+
Generate Microsoft HTML Help source files for the MS HTML Help
|
|
2967
|
+
Compiler in the <code class="literal">./doc/htmlhelp</code> directory. This example is run on
|
|
2968
|
+
MS Windows from a Cygwin shell prompt:
|
|
2969
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook asciidoc.txt
|
|
2970
|
+
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
|
|
2971
|
+
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp</pre></dd><dt><span class="term">
|
|
2972
|
+
<code class="literal">manpage.xsl</code>
|
|
2973
|
+
</span></dt><dd><p>
|
|
2974
|
+
Generate a <code class="literal">roff(1)</code> format UNIX man page from a DocBook XML
|
|
2975
|
+
<span class="emphasis"><em>refentry</em></span> document. This example generates an <code class="literal">asciidoc.1</code> man
|
|
2976
|
+
page file:
|
|
2977
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
|
|
2978
|
+
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml</pre></dd><dt><span class="term">
|
|
2979
|
+
<code class="literal">xhtml.xsl</code>
|
|
2980
|
+
</span></dt><dd><p>
|
|
2981
|
+
Convert a DocBook XML file to a single XHTML file. For example:
|
|
2982
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook asciidoc.txt
|
|
2983
|
+
$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html</pre></dd></dl></div><p>If you want to see how the complete documentation set is processed
|
|
2984
|
+
take a look at the A-A-P script <code class="literal">./doc/main.aap</code>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_generating_plain_text_files"></a>29. Generating Plain Text Files</h2></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> does not have a text backend (for most purposes <span class="emphasis"><em>AsciiDoc</em></span>
|
|
2985
|
+
source text is fine), however you can convert <span class="emphasis"><em>AsciiDoc</em></span> text files to
|
|
2986
|
+
formatted text using the <span class="emphasis"><em>AsciiDoc</em></span> <a href="#X43" title="28.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> toolchain wrapper
|
|
2987
|
+
utility.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_xml_and_character_sets"></a>30. XML and Character Sets</h2></div></div></div><p>The default XML character set <code class="literal">UTF-8</code> is used when <span class="emphasis"><em>AsciiDoc</em></span> generates
|
|
2988
|
+
DocBook files but this can be changed by setting the <code class="literal">xmldecl</code> entry
|
|
2989
|
+
in the <code class="literal">[attributes]</code> section of the <code class="literal">docbook.conf</code> file or by
|
|
2990
|
+
composing your own configuration file <code class="literal">[header]</code> section).</p><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>If you get an <span class="emphasis"><em>undefined entity</em></span> error when processing DocBook
|
|
2991
|
+
files you'll may find that you've used an undefined HTML character
|
|
2992
|
+
entity. An easy (although inelegant) fix is to use the character's
|
|
2993
|
+
character code instead of its symbolic name (for example use <code class="literal">&#160;</code>
|
|
2994
|
+
instead of <code class="literal">&nbsp;</code>).</p></td></tr></table></div><p>If your system has been configured with an XML catalog you may find a
|
|
2995
|
+
number of entity sets are already automatically included.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_pdf_fonts"></a>30.1. PDF Fonts</h3></div></div></div><p>The Adobe PDF Specification states that the following 14 fonts should
|
|
2996
|
+
be available to every PDF reader: Helvetica (normal, bold, italic,
|
|
2997
|
+
bold italic), Times (normal, bold, italic, bold italic), Courier
|
|
2998
|
+
(normal, bold, italic, bold italic), Symbol and ZapfDingbats.
|
|
2999
|
+
Non-standard fonts should be embedded in the distributed document.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X36"></a>31. Help Commands</h2></div></div></div><p>The <code class="literal">asciidoc(1)</code> command has a <code class="literal">--help</code> option which prints help topics
|
|
3000
|
+
to stdout. The default topic summarizes <code class="literal">asciidoc(1)</code> usage:</p><pre class="literallayout">$ asciidoc --help</pre><p>To print a list of help topics:</p><pre class="literallayout">$ asciidoc --help=topics</pre><p>To print a help topic specify the topic name as a command argument.
|
|
3001
|
+
Help topic names can be shortened so long as they are not ambiguous.
|
|
3002
|
+
Examples:</p><pre class="literallayout">$ asciidoc --help=manpage
|
|
3003
|
+
$ asciidoc -hm # Short version of previous example.
|
|
3004
|
+
$ asciidoc --help=syntax
|
|
3005
|
+
$ asciidoc -hs # Short version of previous example.</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_customizing_help"></a>31.1. Customizing Help</h3></div></div></div><p>To change, delete or add your own help topics edit a help
|
|
3006
|
+
configuration file. The help file name <code class="literal">help-<lang>.conf</code> is based on
|
|
3007
|
+
the setting of the <code class="literal">lang</code> attribute, it defaults to <code class="literal">help.conf</code>
|
|
3008
|
+
(English). The <a href="#X27" title="20.4. Configuration File Names and Locations">help file location</a> will depend on whether you
|
|
3009
|
+
want the topics to apply to all users or just the current user.</p><p>The help topic files have the same named section format as other
|
|
3010
|
+
<a href="#X7" title="20. Configuration Files">configuration files</a>. The <code class="literal">help.conf</code> files are stored in the
|
|
3011
|
+
same locations and loaded in the same order as other configuration
|
|
3012
|
+
files.</p><p>When the <code class="literal">--help</code> command-line option is specified <span class="emphasis"><em>AsciiDoc</em></span> loads the
|
|
3013
|
+
appropriate help files and then prints the contents of the section
|
|
3014
|
+
whose name matches the help topic name. If a topic name is not
|
|
3015
|
+
specified <code class="literal">default</code> is used. You don't need to specify the whole help
|
|
3016
|
+
topic name on the command-line, just enough letters to ensure it's not
|
|
3017
|
+
ambiguous. If a matching help file section is not found a list of
|
|
3018
|
+
available topics is printed.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_tips_and_tricks"></a>32. Tips and Tricks</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_know_your_editor"></a>32.1. Know Your Editor</h3></div></div></div><p>Writing <span class="emphasis"><em>AsciiDoc</em></span> documents will be a whole lot more pleasant if you
|
|
3019
|
+
know your favorite text editor. Learn how to indent and reformat text
|
|
3020
|
+
blocks, paragraphs, lists and sentences. <a href="#X20" title="32.2. Vim Commands for Formatting AsciiDoc">Tips for <span class="emphasis"><em>vim</em></span> users</a>
|
|
3021
|
+
follow.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X20"></a>32.2. Vim Commands for Formatting AsciiDoc</h3></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_text_wrap_paragraphs"></a>32.2.1. Text Wrap Paragraphs</h4></div></div></div><p>Use the vim <code class="literal">:gq</code> command to reformat paragraphs. Setting the
|
|
3022
|
+
<span class="emphasis"><em>textwidth</em></span> sets the right text wrap margin; for example:</p><pre class="literallayout">:set textwidth=70</pre><p>To reformat a paragraph:</p><div class="orderedlist"><ol type="1"><li>
|
|
3023
|
+
Position the cursor at the start of the paragraph.
|
|
3024
|
+
</li><li>
|
|
3025
|
+
Type <code class="literal">gq}</code>.
|
|
3026
|
+
</li></ol></div><p>Execute <code class="literal">:help gq</code> command to read about the vim gq command.</p><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><div class="itemizedlist"><ul type="disc"><li>
|
|
3027
|
+
Assign the <code class="literal">gq}</code> command to the Q key with the <code class="literal">nnoremap Q gq}</code>
|
|
3028
|
+
command or put it in your <code class="literal">~/.vimrc</code> file to so it's always
|
|
3029
|
+
available (see the <a href="#X61" title="32.2.4. Example ~/.vimrc File">Example <code class="literal">~/.vimrc</code> file</a>).
|
|
3030
|
+
</li><li>
|
|
3031
|
+
Put <code class="literal">set</code> commands in your <code class="literal">~/.vimrc</code> file so you don't have to
|
|
3032
|
+
enter them manually <a href="#X61" title="32.2.4. Example ~/.vimrc File">Example <code class="literal">~/.vimrc</code> file</a>).
|
|
3033
|
+
</li><li>
|
|
3034
|
+
The Vim website (<a href="http://www.vim.org" target="_top">http://www.vim.org</a>) has a wealth of resources,
|
|
3035
|
+
including scripts for automated spell checking and ASCII Art
|
|
3036
|
+
drawing.
|
|
3037
|
+
</li></ul></div></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_format_lists"></a>32.2.2. Format Lists</h4></div></div></div><p>The <code class="literal">gq</code> command can also be used to format bulleted and numbered
|
|
3038
|
+
lists. First you need to set the <code class="literal">comments</code> and <code class="literal">formatoptions</code> (see
|
|
3039
|
+
the <a href="#X61" title="32.2.4. Example ~/.vimrc File">Example <code class="literal">~/.vimrc</code> file</a>).</p><p>Now you can format simple lists that use dash, asterisk, period and
|
|
3040
|
+
plus bullets along with numbered ordered lists:</p><div class="orderedlist"><ol type="1"><li>
|
|
3041
|
+
Position the cursor at the start of the list.
|
|
3042
|
+
</li><li>
|
|
3043
|
+
Type <code class="literal">gq}</code>.
|
|
3044
|
+
</li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_indent_paragraphs"></a>32.2.3. Indent Paragraphs</h4></div></div></div><p>Indent whole paragraphs by indenting the fist line with the desired
|
|
3045
|
+
indent and then executing the <code class="literal">gq}</code> command.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="X61"></a>32.2.4. Example <code class="literal">~/.vimrc</code> File</h4></div></div></div><pre class="screen">" Show tabs and trailing characters.
|
|
3046
|
+
set listchars=tab:»·,trail:·
|
|
3047
|
+
set list
|
|
3048
|
+
|
|
3049
|
+
" Don't highlight searched text.
|
|
3050
|
+
highlight clear Search
|
|
3051
|
+
|
|
3052
|
+
" Don't move to matched text while search pattern is being entered.
|
|
3053
|
+
set noincsearch
|
|
3054
|
+
|
|
3055
|
+
" Q command to reformat paragraphs and list.
|
|
3056
|
+
nnoremap Q gq}
|
|
3057
|
+
|
|
3058
|
+
" W command to delete trailing white space and Dos-returns and to expand tabs
|
|
3059
|
+
" to spaces.
|
|
3060
|
+
nnoremap W :%s/[\r \t]\+$//<CR>:set et<CR>:retab!<CR>
|
|
3061
|
+
|
|
3062
|
+
autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
|
|
3063
|
+
\ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2
|
|
3064
|
+
\ textwidth=70 wrap formatoptions=tcqn
|
|
3065
|
+
\ 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>32.3. Troubleshooting</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li>
|
|
3066
|
+
The <code class="literal">asciidoc(1)</code> <code class="literal">-v</code> (<code class="literal">—verbose</code>) command-line option displays the
|
|
3067
|
+
order of configuration file loading and warns of potential
|
|
3068
|
+
configuration file problems.
|
|
3069
|
+
</li><li>
|
|
3070
|
+
Not all valid <span class="emphasis"><em>AsciiDoc</em></span> documents produce valid backend markup. Read
|
|
3071
|
+
the <a href="#X5" title="4. AsciiDoc Backends"><span class="emphasis"><em>AsciiDoc</em></span> Backends</a> section if <span class="emphasis"><em>AsciiDoc</em></span> output is rejected
|
|
3072
|
+
as non-conformant by a backend processor.
|
|
3073
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_gotchas"></a>32.4. Gotchas</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
3074
|
+
Incorrect character encoding
|
|
3075
|
+
</span></dt><dd>
|
|
3076
|
+
If you get an error message like <code class="literal">'UTF-8' codec can't decode …</code>
|
|
3077
|
+
then you source file contains invalid UTF-8 characters — set the
|
|
3078
|
+
<span class="emphasis"><em>AsciiDoc</em></span> <a href="#X54" title="???TITLE???">encoding attribute</a> for the correct character set
|
|
3079
|
+
(typically ISO-8859-1 (Latin-1) for European languages).
|
|
3080
|
+
</dd><dt><span class="term">
|
|
3081
|
+
Misinterpreted text formatting
|
|
3082
|
+
</span></dt><dd><p>
|
|
3083
|
+
If text in your document is incorrectly interpreted as formatting
|
|
3084
|
+
instructions you can suppress formatting by placing a backslash
|
|
3085
|
+
character immediately in front of the leading quote character(s).
|
|
3086
|
+
For example in the following line the backslash prevents text
|
|
3087
|
+
between the two asterisks from being output in a strong (bold)
|
|
3088
|
+
font:
|
|
3089
|
+
</p><pre class="literallayout">Add `\*.cs` files and `*.resx` files.</pre></dd><dt><span class="term">
|
|
3090
|
+
Overlapping text formatting
|
|
3091
|
+
</span></dt><dd><p>
|
|
3092
|
+
Overlapping text formatting will generate illegal overlapping
|
|
3093
|
+
markup tags which will result in downstream XML parsing errors.
|
|
3094
|
+
Here's an example:
|
|
3095
|
+
</p><pre class="literallayout">Some *strong markup _that overlaps* emphasized markup_.</pre></dd><dt><span class="term">
|
|
3096
|
+
Ambiguous underlines
|
|
3097
|
+
</span></dt><dd>
|
|
3098
|
+
A DelimitedBlock can immediately follow paragraph without an
|
|
3099
|
+
intervening blank line, but be careful, a single line paragraph
|
|
3100
|
+
underline may be misinterpreted as a section title underline
|
|
3101
|
+
resulting in a “closing block delimiter expected” error.
|
|
3102
|
+
</dd><dt><span class="term">
|
|
3103
|
+
Ambiguous ordered list items
|
|
3104
|
+
</span></dt><dd><p>
|
|
3105
|
+
Lines beginning with numbers at the end of sentences will be
|
|
3106
|
+
interpreted as ordered list items. The following example
|
|
3107
|
+
(incorrectly) begins a new list with item number 1999:
|
|
3108
|
+
</p><pre class="literallayout">He was last sighted in
|
|
3109
|
+
1999. Since then things have moved on.</pre><p>The <span class="emphasis"><em>list item out of sequence</em></span> warning makes it unlikely that this
|
|
3110
|
+
problem will go unnoticed.</p></dd><dt><span class="term">
|
|
3111
|
+
Escaping inside DSV table data
|
|
3112
|
+
</span></dt><dd>
|
|
3113
|
+
Delimiter separated text uses C style backslash escape sequences.
|
|
3114
|
+
If you want to enter a backslash (for example, to escape <span class="emphasis"><em>AsciiDoc</em></span>
|
|
3115
|
+
text formatting or an inline macro) you need to escape it by
|
|
3116
|
+
entering two backslashes.
|
|
3117
|
+
</dd><dt><span class="term">
|
|
3118
|
+
Special characters in attribute values
|
|
3119
|
+
</span></dt><dd><p>
|
|
3120
|
+
Special character substitution precedes attribute substitution so
|
|
3121
|
+
if attribute values contain special characters you may, depending
|
|
3122
|
+
on the substitution context, need to escape the special characters
|
|
3123
|
+
yourself. For example:
|
|
3124
|
+
</p><pre class="literallayout">$ asciidoc -a 'companyname=Bill &amp; Ben' mydoc.txt</pre></dd><dt><span class="term">
|
|
3125
|
+
Macro attribute lists
|
|
3126
|
+
</span></dt><dd><p>
|
|
3127
|
+
If named attribute list entries are present then all string
|
|
3128
|
+
attribute values must be quoted. For example:
|
|
3129
|
+
</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>32.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
|
|
3130
|
+
process as a single document. Simply processing them with a series of
|
|
3131
|
+
<code class="literal">include</code> macros won't work, because instead of starting at level 1
|
|
3132
|
+
the section levels of the combined document start at level 0 (the
|
|
3133
|
+
document title level).</p><p>The solution is to redefine the title underlines so that document and
|
|
3134
|
+
section titles are pushed down one level.</p><div class="orderedlist"><ol type="1"><li><p>
|
|
3135
|
+
Push the standard title underlines down one level by defining a new
|
|
3136
|
+
level 0 underline in a custom configuration file. For example
|
|
3137
|
+
<code class="literal">combined.conf</code>:
|
|
3138
|
+
</p><pre class="literallayout">[titles]
|
|
3139
|
+
underlines="__","==","--","~~","^^"</pre></li><li>
|
|
3140
|
+
If you use single line titles you'll need to make corresponding
|
|
3141
|
+
adjustments to the <code class="literal">[titles]</code> section <code class="literal">sect0</code>…<code class="literal">sect4</code> entries.
|
|
3142
|
+
</li><li><p>
|
|
3143
|
+
Create a top level wrapper document. For example <code class="literal">combined.txt</code>:
|
|
3144
|
+
</p><pre class="screen"> Combined Document Title
|
|
3145
|
+
_______________________
|
|
3146
|
+
|
|
3147
|
+
include::document1.txt[]
|
|
3148
|
+
|
|
3149
|
+
include::document2.txt[]
|
|
3150
|
+
|
|
3151
|
+
include::document3.txt[]</pre></li><li><p>
|
|
3152
|
+
Process the wrapper document. For example:
|
|
3153
|
+
</p><pre class="literallayout">$ asciidoc --conf-file=combined.conf combined.txt</pre></li></ol></div><p>Actually the <code class="literal">—conf-file</code> option is unnecessary as <code class="literal">asciidoc(1)</code>
|
|
3154
|
+
automatically looks for a same-named <code class="literal">.conf</code> file.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3155
|
+
The combined document title uses the newly defined level 0 underline
|
|
3156
|
+
(underscore characters).
|
|
3157
|
+
</li><li>
|
|
3158
|
+
Put a blank line between the <code class="literal">include</code> macro lines to ensure the
|
|
3159
|
+
title of the included document is not seen as part of the last
|
|
3160
|
+
paragraph of the previous document.
|
|
3161
|
+
</li><li>
|
|
3162
|
+
You won't want document Headers (Author and Revision lines) in the
|
|
3163
|
+
included files — conditionally exclude them if they are necessary
|
|
3164
|
+
for stand-alone processing.
|
|
3165
|
+
</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>32.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 top level
|
|
3166
|
+
section) which are combined and processed with the following top level
|
|
3167
|
+
document:</p><pre class="screen"> Combined Document Title
|
|
3168
|
+
=======================
|
|
3169
|
+
Joe Bloggs
|
|
3170
|
+
v1.0, 12-Aug-03
|
|
3171
|
+
|
|
3172
|
+
include::section1.txt[]
|
|
3173
|
+
|
|
3174
|
+
include::section2.txt[]
|
|
3175
|
+
|
|
3176
|
+
include::section3.txt[]</pre><p>You also want to process the section files as separate documents.
|
|
3177
|
+
This is easy because <code class="literal">asciidoc(1)</code> will quite happily process
|
|
3178
|
+
<code class="literal">section1.txt</code>, <code class="literal">section2.txt</code> and <code class="literal">section3.txt</code> separately.</p><p>If you want to promote the section levels up one level, so the
|
|
3179
|
+
document is processed just like a stand-alone document, then pop the
|
|
3180
|
+
section underline definition up one level:</p><pre class="literallayout">[titles]
|
|
3181
|
+
underlines="--","~~","^^","++","__"</pre><p>The last <code class="literal">"__"</code> underline is a dummy that won't actually be used but
|
|
3182
|
+
is necessary to legitimize the underline definition.</p><p>This is just the reverse of the technique used for combining separate
|
|
3183
|
+
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>32.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
|
|
3184
|
+
through it. For example:</p><pre class="literallayout">$ echo 'Hello *World!*' | asciidoc -s -
|
|
3185
|
+
<div class="para"><p>Hello <strong>World!</strong></p></div></pre><p>The <code class="literal">-s</code> (<code class="literal">—no-header-footer</code>) command-line option suppresses header
|
|
3186
|
+
and footer output and is useful if the processed output is to be
|
|
3187
|
+
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>32.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>
|
|
3188
|
+
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>32.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
|
|
3189
|
+
liking you can:</p><div class="orderedlist"><ol type="1"><li>
|
|
3190
|
+
Change the indentation and layout of configuration file markup
|
|
3191
|
+
template sections. The <code class="literal">{empty}</code> glossary entry is useful for
|
|
3192
|
+
outputting trailing blank lines in markup templates.
|
|
3193
|
+
</li><li><p>
|
|
3194
|
+
Or use Dave Raggett's excellent <span class="emphasis"><em>HTML Tidy</em></span> program to tidy
|
|
3195
|
+
<code class="literal">asciidoc(1)</code> output. Example:
|
|
3196
|
+
</p><pre class="literallayout">$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml</pre></li></ol></div><p><span class="emphasis"><em>HTML Tidy</em></span> can be downloaded from <a href="http://tidy.sourceforge.net/" target="_top">http://tidy.sourceforge.net/</a></p></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>32.10. Supporting Minor DocBook DTD Variations</h3></div></div></div><p>The conditional inclusion of DocBook SGML markup at the end of the
|
|
3197
|
+
distribution <code class="literal">docbook.conf</code> file illustrates how to support minor DTD
|
|
3198
|
+
variations. The included sections override corresponding entries from
|
|
3199
|
+
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>32.11. Shipping Stand-alone AsciiDoc Source</h3></div></div></div><p>Reproducing presentation documents from someone else's source has one
|
|
3200
|
+
major problem: unless your configuration files are the same as the
|
|
3201
|
+
creator's you won't get the same output.</p><p>The solution is to create a single backend specific configuration file
|
|
3202
|
+
using the <code class="literal">asciidoc(1)</code> <code class="literal">-c</code> (<code class="literal">—dump-conf</code>) command-line option. You
|
|
3203
|
+
then ship this file along with the <span class="emphasis"><em>AsciiDoc</em></span> source document plus the
|
|
3204
|
+
<code class="literal">asciidoc.py</code> script. The only end user requirement is that they have
|
|
3205
|
+
Python installed (and of course that they consider you a trusted
|
|
3206
|
+
source). This example creates a composite HTML configuration
|
|
3207
|
+
file for <code class="literal">mydoc.txt</code>:</p><pre class="literallayout">$ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf</pre><p>Ship <code class="literal">mydoc.txt</code>, <code class="literal">mydoc-html.conf</code>, and <code class="literal">asciidoc.py</code>. With
|
|
3208
|
+
these three files (and a Python interpreter) the recipient can
|
|
3209
|
+
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
|
|
3210
|
+
configuration files, ensuring that only entries from the
|
|
3211
|
+
<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>32.12. Inserting Blank Space</h3></div></div></div><p>Adjust your style sheets to add the correct separation between block
|
|
3212
|
+
elements. Inserting blank paragraphs containing a single non-breaking
|
|
3213
|
+
space character <code class="literal">{nbsp}</code> works but is an ad hoc solution compared
|
|
3214
|
+
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>32.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
|
|
3215
|
+
<code class="literal">eval::[Section.setlevel(N)]</code> system macro. This is useful if you
|
|
3216
|
+
want to include a section composed of raw markup. The following
|
|
3217
|
+
example includes a DocBook glossary division at the top section level
|
|
3218
|
+
(level 0):</p><pre class="screen"> ifdef::backend-docbook[]
|
|
3219
|
+
|
|
3220
|
+
eval::[Section.setlevel(0)]
|
|
3221
|
+
|
|
3222
|
+
+++++++++++++++++++++++++++++++
|
|
3223
|
+
<glossary>
|
|
3224
|
+
<title>Glossary</title>
|
|
3225
|
+
<glossdiv>
|
|
3226
|
+
...
|
|
3227
|
+
</glossdiv>
|
|
3228
|
+
</glossary>
|
|
3229
|
+
+++++++++++++++++++++++++++++++
|
|
3230
|
+
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>32.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
|
|
3231
|
+
formed and valid. Here are some examples:</p><pre class="literallayout">$ xmllint --nonet --noout --valid docbook-file.xml
|
|
3232
|
+
$ xmllint --nonet --noout --valid xhtml11-file.html
|
|
3233
|
+
$ 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
|
|
3234
|
+
type's DTD, if the DTD is not installed in your system's catalog then
|
|
3235
|
+
it will be fetched from its Internet location. If you omit the
|
|
3236
|
+
<code class="literal">—valid</code> option the document will only be checked that it is well
|
|
3237
|
+
formed.</p></div></div><div class="glossary"><div class="titlepage"><div><div><h2 class="title"><a id="_glossary"></a>Glossary</h2></div></div></div><dl><dt>
|
|
3238
|
+
<a id="X8"></a> Block element
|
|
3239
|
+
</dt><dd><p>
|
|
3240
|
+
An <span class="emphasis"><em>AsciiDoc</em></span> block element is a document entity composed of one or
|
|
3241
|
+
more whole lines of text.
|
|
3242
|
+
</p></dd><dt>
|
|
3243
|
+
<a id="X34"></a> Inline element
|
|
3244
|
+
</dt><dd><p>
|
|
3245
|
+
<span class="emphasis"><em>AsciiDoc</em></span> inline elements occur within block element textual
|
|
3246
|
+
content, they perform formatting and substitution tasks.
|
|
3247
|
+
</p></dd><dt>
|
|
3248
|
+
Formal element
|
|
3249
|
+
</dt><dd><p>
|
|
3250
|
+
An <span class="emphasis"><em>AsciiDoc</em></span> block element that has a BlockTitle. Formal elements
|
|
3251
|
+
are normally listed in front or back matter, for example lists of
|
|
3252
|
+
tables, examples and figures.
|
|
3253
|
+
</p></dd><dt>
|
|
3254
|
+
Verbatim element
|
|
3255
|
+
</dt><dd><p>
|
|
3256
|
+
The word verbatim indicates that white space and line breaks in
|
|
3257
|
+
the source document are to be preserved in the output document.
|
|
3258
|
+
</p></dd></dl></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="_migration_notes"></a>A. Migration Notes</h2><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X53"></a>A.1. Version 7 to version 8</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li>
|
|
3259
|
+
A new set of quotes has been introduced which may match inline text
|
|
3260
|
+
in existing documents — if they do you'll need to escape the
|
|
3261
|
+
matched text with backslashes.
|
|
3262
|
+
</li><li>
|
|
3263
|
+
The index entry inline macro syntax has changed — if your documents
|
|
3264
|
+
include indexes you may need to edit them.
|
|
3265
|
+
</li><li>
|
|
3266
|
+
Replaced <code class="literal">a2x(1)</code> <code class="literal">--no-icons</code> and <code class="literal">--no-copy</code> options with their
|
|
3267
|
+
negated equivalents: <code class="literal">--icons</code> and <code class="literal">--copy</code> respectively. The
|
|
3268
|
+
default behavior has also changed — the use of icons and copying of
|
|
3269
|
+
icon and CSS files must be specified explicitly with the <code class="literal">--icons</code>
|
|
3270
|
+
and <code class="literal">--copy</code> options.
|
|
3271
|
+
</li></ul></div><p>The rationale for the changes can be found in the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
3272
|
+
<code class="literal">CHANGELOG</code>.</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>If you want to disable unconstrained quotes, the new alternative
|
|
3273
|
+
constrained quotes syntax and the new index entry syntax then you can
|
|
3274
|
+
define the attribute <code class="literal">asciidoc7compatible</code> (for example by using the
|
|
3275
|
+
<code class="literal">-a asciidoc7compatible</code> command-line option).</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X32"></a>A.2. Version 6 to version 7</h3></div></div></div><p>The changes that affect the most users relate to renamed and
|
|
3276
|
+
deprecated backends and command-line syntax:</p><div class="orderedlist"><ol type="1"><li>
|
|
3277
|
+
The <span class="emphasis"><em>html</em></span> backend has been renamed <span class="emphasis"><em>html4</em></span>.
|
|
3278
|
+
</li><li>
|
|
3279
|
+
The <span class="emphasis"><em>xhtml</em></span> backend has been deprecated to <span class="emphasis"><em>xhtml-deprecated</em></span> (use
|
|
3280
|
+
the new <span class="emphasis"><em>xhtml11</em></span> backend in preference).
|
|
3281
|
+
</li><li>
|
|
3282
|
+
The use of CSS specific <code class="literal">css</code> and <code class="literal">css-embedded</code> backends has been
|
|
3283
|
+
dropped in favor of using attributes (see the table below and
|
|
3284
|
+
<a href="#X33" title="4.2. xhtml11">xhtml backend attributes</a>).
|
|
3285
|
+
</li><li>
|
|
3286
|
+
Deprecated features that emitted warnings in prior versions are no
|
|
3287
|
+
longer tolerated.
|
|
3288
|
+
</li><li>
|
|
3289
|
+
The command-line syntax for deleting (undefining) an attribute has
|
|
3290
|
+
changed from <code class="literal">-a ^name</code> to <code class="literal">-a name!</code>.
|
|
3291
|
+
</li></ol></div><div class="table"><a id="id2555514"></a><p class="title"><b>Table A.1. Equivalent command-line syntax</b></p><div class="table-contents"><table summary="Equivalent command-line syntax" cellpadding="4px" border="0" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; "><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3292
|
+
Version 6 (old)
|
|
3293
|
+
</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3294
|
+
Version 7 (new)
|
|
3295
|
+
</th><th style="border-bottom: 1px solid ; " align="left">
|
|
3296
|
+
Version 7 (backward compatible)
|
|
3297
|
+
</th></tr></thead><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3298
|
+
-b html
|
|
3299
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3300
|
+
-b html4
|
|
3301
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
3302
|
+
-b html4
|
|
3303
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3304
|
+
-b css
|
|
3305
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3306
|
+
-b xhtml11 -a linkcss -a icons
|
|
3307
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
3308
|
+
-b xhtml-deprecated -a css -a linkcss -a icons
|
|
3309
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3310
|
+
-b css-embedded
|
|
3311
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3312
|
+
-b xhtml11 -a icons
|
|
3313
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
3314
|
+
-b xhtml-deprecated -a css -a icons
|
|
3315
|
+
</td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3316
|
+
-b xhtml
|
|
3317
|
+
</td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left">
|
|
3318
|
+
-b xhtml11
|
|
3319
|
+
</td><td style="border-bottom: 1px solid ; " align="left">
|
|
3320
|
+
-b xhtml-deprecated
|
|
3321
|
+
</td></tr><tr><td style="border-right: 1px solid ; " align="left">
|
|
3322
|
+
-b docbook-sgml
|
|
3323
|
+
</td><td style="border-right: 1px solid ; " align="left">
|
|
3324
|
+
-b docbook -a sgml
|
|
3325
|
+
</td><td style="" align="left">
|
|
3326
|
+
-b docbook -a sgml
|
|
3327
|
+
</td></tr></tbody></table></div></div><br class="table-break" /><p>If you've customized version 6 distribution stylesheets then you'll
|
|
3328
|
+
need to either bring them in line with the new
|
|
3329
|
+
<code class="literal">./stylesheets/xhtml11*.css</code> class and id names or stick with the
|
|
3330
|
+
backward compatible <code class="literal">xhtml-deprecated</code> backend.</p><p>Changes to configuration file syntax:</p><div class="orderedlist"><ol type="1"><li>
|
|
3331
|
+
To undefine an attribute in the <code class="literal">[attributes]</code> section use <code class="literal">name!</code>
|
|
3332
|
+
instead of <code class="literal">name</code> (<code class="literal">name</code> now sets that attribute to a blank
|
|
3333
|
+
string).
|
|
3334
|
+
</li></ol></div></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="X38"></a>B. Packager Notes</h2><p>Read the <code class="literal">README</code> and <code class="literal">INSTALL</code> files (in the distribution root
|
|
3335
|
+
directory) for install prerequisites and procedures.</p><p>The distribution <code class="literal">install.sh</code> shell script is the canonical
|
|
3336
|
+
installation procedure and is the definitive installation description.
|
|
3337
|
+
Here's a summary of the installation procedure:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3338
|
+
Unpack entire distribution tarball to <code class="literal">/usr/share/asciidoc/</code>.
|
|
3339
|
+
</li><li>
|
|
3340
|
+
Move <code class="literal">asciidoc.py</code> to <code class="literal">/usr/bin/</code>; rename to <code class="literal">asciidoc</code>; if
|
|
3341
|
+
necessary modify shebang line; ensure executable permissions are
|
|
3342
|
+
set.
|
|
3343
|
+
</li><li>
|
|
3344
|
+
Move <code class="literal">a2x</code> to <code class="literal">/usr/bin/</code>; if necessary modify shebang line; ensure
|
|
3345
|
+
executable permissions are set.
|
|
3346
|
+
</li><li>
|
|
3347
|
+
Move the <code class="literal">./*.conf</code> files to <code class="literal">/etc/asciidoc/</code>.
|
|
3348
|
+
</li><li>
|
|
3349
|
+
Move <code class="literal">./filters/{*.conf,*.py}</code> to <code class="literal">/etc/asciidoc/filters/</code>.
|
|
3350
|
+
</li><li>
|
|
3351
|
+
Move <code class="literal">./docbook-xsl/*.xsl</code> to <code class="literal">/etc/asciidoc/docbook-xsl/</code>.
|
|
3352
|
+
</li><li>
|
|
3353
|
+
Move <code class="literal">./dblatex/*.{xsl,sty}</code> to <code class="literal">/etc/asciidoc/dblatex/</code>.
|
|
3354
|
+
</li><li>
|
|
3355
|
+
Copy <code class="literal">./stylesheets/*.css</code> to <code class="literal">/etc/asciidoc/stylesheets/</code>.
|
|
3356
|
+
</li><li>
|
|
3357
|
+
Copy <code class="literal">./javascripts/*.js</code> to <code class="literal">/etc/asciidoc/javascripts/</code>.
|
|
3358
|
+
</li><li>
|
|
3359
|
+
Copy <code class="literal">./images/icons/*</code> to <code class="literal">/etc/asciidoc/images/icons/</code>
|
|
3360
|
+
(recursively including the <code class="literal">icons</code> subdirectory and its contents).
|
|
3361
|
+
</li><li>
|
|
3362
|
+
Compress the <code class="literal">asciidoc(1)</code> and ax2(1) man pages (<code class="literal">./doc/*.1</code>) with
|
|
3363
|
+
gzip(1) and move them to <code class="literal">/usr/share/man/man1/</code>.
|
|
3364
|
+
</li><li>
|
|
3365
|
+
If Vim is installed then install Vim syntax and filetype detection
|
|
3366
|
+
files.
|
|
3367
|
+
</li></ul></div><p>Leaving stylesheets and images in <code class="literal">/usr/share/asciidoc/</code> ensures the
|
|
3368
|
+
docs and example website are not broken.</p></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="X39"></a>C. AsciiDoc Safe Mode</h2><p><span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>safe mode</em></span> skips potentially dangerous sections in <span class="emphasis"><em>AsciiDoc</em></span>
|
|
3369
|
+
source files by inhibiting the execution of arbitrary code or the
|
|
3370
|
+
inclusion of arbitrary files.</p><p>The safe mode is enabled by default and can only be disabled using the
|
|
3371
|
+
<code class="literal">asciidoc(1)</code> <code class="literal">—unsafe</code> command-line option.</p><div class="itemizedlist"><p class="title"><b>Safe mode constraints</b></p><ul type="disc"><li>
|
|
3372
|
+
<code class="literal">eval</code>, <code class="literal">sys</code> and <code class="literal">sys2</code> executable attributes and block macros are
|
|
3373
|
+
not executed.
|
|
3374
|
+
</li><li>
|
|
3375
|
+
<code class="literal">include::<filename>[]</code> and <code class="literal">include1::<filename>[]</code> block macro
|
|
3376
|
+
files must reside inside the parent file's directory.
|
|
3377
|
+
</li><li>
|
|
3378
|
+
<code class="literal">{include:<filename>}</code> executable attribute files must reside
|
|
3379
|
+
inside the source document directory.
|
|
3380
|
+
</li><li>
|
|
3381
|
+
Passthrough Blocks are dropped.
|
|
3382
|
+
</li></ul></div><div class="warning" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="./images/icons/warning.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The safe mode is not designed to protect against unsafe <span class="emphasis"><em>AsciiDoc</em></span>
|
|
3383
|
+
configuration files. Be especially careful when:</p><div class="orderedlist"><ol type="1"><li>
|
|
3384
|
+
Implementing filters.
|
|
3385
|
+
</li><li>
|
|
3386
|
+
Implementing elements that don't escape special characters.
|
|
3387
|
+
</li><li>
|
|
3388
|
+
Accepting configuration files from untrusted sources.
|
|
3389
|
+
</li></ol></div></td></tr></table></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="_using_asciidoc_with_non_english_languages"></a>D. Using AsciiDoc with non-English Languages</h2><p><span class="emphasis"><em>AsciiDoc</em></span> can process UTF-8 character sets but there are some things
|
|
3390
|
+
you need to be aware of:</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
3391
|
+
If you are generating output documents using a DocBook toolchain
|
|
3392
|
+
then you should set the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">lang</code> attribute to the appropriate
|
|
3393
|
+
language (it defaults to <code class="literal">en</code> (English)). This will ensure things
|
|
3394
|
+
like table of contents, revision history, figure and table captions
|
|
3395
|
+
and admonition captions are output in the specified language.
|
|
3396
|
+
For example:
|
|
3397
|
+
</p><pre class="literallayout">$ a2x -a lang=es doc/article.txt</pre></li><li>
|
|
3398
|
+
If you are outputting html or xhtml directly from <code class="literal">asciidoc(1)</code> you'll
|
|
3399
|
+
need to set the various <code class="literal">*_caption</code> attributes to match your target
|
|
3400
|
+
language (see the list of captions and titles in the <code class="literal">[attributes]</code>
|
|
3401
|
+
section of the default <code class="literal">asciidoc.conf</code> file). The easiest way is to
|
|
3402
|
+
create a language <code class="literal">.conf</code> file (see the example <code class="literal">lang-es.conf</code> file
|
|
3403
|
+
that comes with the <span class="emphasis"><em>AsciiDoc</em></span> distribution).
|
|
3404
|
+
</li><li>
|
|
3405
|
+
<code class="literal">asciidoc(1)</code> automatically loads configuration files named like
|
|
3406
|
+
<code class="literal">lang-<lang>.conf</code> where <code class="literal"><lang></code> is a two letter language code that
|
|
3407
|
+
matches the current <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">lang</code> attribute. See also
|
|
3408
|
+
<a href="#X27" title="20.4. Configuration File Names and Locations">Configuration File Names and Locations</a>.
|
|
3409
|
+
</li><li>
|
|
3410
|
+
Some character sets display double-width characters (for example
|
|
3411
|
+
Japanese). As far as <a href="#X17" title="8. Titles">title underlines</a> are concerned they
|
|
3412
|
+
should be treated as single character. If you think this looks
|
|
3413
|
+
untidy so you may prefer to use the <a href="#X46" title="8.2. One line titles">single line title</a>
|
|
3414
|
+
format.
|
|
3415
|
+
</li></ul></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="_asciimathml_support"></a>E. ASCIIMathML Support</h2><p><a href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html" target="_top">ASCIIMathML</a> is
|
|
3416
|
+
a clever JavaScript written by Peter Jipsen that transforms
|
|
3417
|
+
mathematical formulae written in plain text to standard mathematical
|
|
3418
|
+
notation on an HTML page.</p><p>To enable ASCIIMathML support on the <code class="literal">xhtml11</code> backend include the <code class="literal">-a
|
|
3419
|
+
asciimath</code> command-line option. Here's what the <code class="literal">asciimath</code> attribute
|
|
3420
|
+
does:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3421
|
+
Embeds the <code class="literal">ASCIIMathML.js</code> script in the output document (links it
|
|
3422
|
+
if <code class="literal">-a linkcss</code> has been specified).
|
|
3423
|
+
</li><li>
|
|
3424
|
+
Escapes ASCIIMathML delimiters.
|
|
3425
|
+
</li></ul></div><p>When entering ASCIIMathML formulas you <span class="strong"><strong>must</strong></span> enclose them inside
|
|
3426
|
+
<a href="#X50" title="7.2. Inline Passthroughs">double-dollar passthroughs</a> (this is necessary because
|
|
3427
|
+
ASCIIMathML characters clash with <span class="emphasis"><em>AsciiDoc</em></span> formatting characters). The
|
|
3428
|
+
double-dollar passthrough has the bonus of also escaping special
|
|
3429
|
+
characters so the output document is valid XHTML. You can see an
|
|
3430
|
+
ASCIIMathML example at
|
|
3431
|
+
<a href="http://www.methods.co.nz/asciidoc/asciimath.html" target="_top">http://www.methods.co.nz/asciidoc/asciimath.html</a>, the same example
|
|
3432
|
+
can be found in the <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">./doc</code> directory.</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"><div class="itemizedlist"><ul type="disc"><li>
|
|
3433
|
+
See the
|
|
3434
|
+
<a href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html" target="_top">ASCIIMathML</a>
|
|
3435
|
+
website for ASCIIMathML documentation and the latest version.
|
|
3436
|
+
</li><li>
|
|
3437
|
+
If you use Mozilla you need to install the
|
|
3438
|
+
<a href="http://www.mozilla.org/projects/mathml/fonts/" target="_top">required math fonts</a>.
|
|
3439
|
+
</li><li>
|
|
3440
|
+
If you use Microsoft Internet Explorer 6 you need to install
|
|
3441
|
+
<a href="http://www.dessci.com/en/products/mathplayer/" target="_top">MathPlayer</a>.
|
|
3442
|
+
</li></ul></div></td></tr></table></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="_vim_syntax_highlighter"></a>F. Vim Syntax Highlighter</h2><p>The <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">./vim/</code> distribution directory contains Vim syntax
|
|
3443
|
+
highlighter and filetype detection scripts for <span class="emphasis"><em>AsciiDoc</em></span>. Syntax
|
|
3444
|
+
highlighting makes it much easier to spot <span class="emphasis"><em>AsciiDoc</em></span> syntax errors.</p><p>If Vim is installed on your system the <span class="emphasis"><em>AsciiDoc</em></span> installer
|
|
3445
|
+
(<code class="literal">install.sh</code>) will automatically install the vim scripts in the Vim
|
|
3446
|
+
global configuration directory (<code class="literal">/etc/vim</code>).</p><p>You can also turn on syntax highlighting by adding the following line
|
|
3447
|
+
to the end of you <span class="emphasis"><em>AsciiDoc</em></span> source files:</p><pre class="literallayout">// vim: set syntax=asciidoc:</pre><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>Dag Wieers has implemented an alternative Vim syntax file for
|
|
3448
|
+
<span class="emphasis"><em>AsciiDoc</em></span> which can be found here
|
|
3449
|
+
<a href="http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/" target="_top">http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/</a>.</p></td></tr></table></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>Emacs users: The <a href="http://xpt.sourceforge.net/" target="_top">*Nix Power Tools
|
|
3450
|
+
project</a> has released an
|
|
3451
|
+
<a href="http://xpt.sourceforge.net/tools/doc-mode/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span> syntax highlighter
|
|
3452
|
+
for emacs</a>.</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_limitations"></a>F.1. Limitations</h3></div></div></div><p>The current implementation does a reasonable job but on occasions gets
|
|
3453
|
+
things wrong. This list of limitations also discusses how to work
|
|
3454
|
+
around the problems:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3455
|
+
Indented lists with preceding blank lines are sometimes mistaken
|
|
3456
|
+
for literal (indented) paragraphs. You can work around this by
|
|
3457
|
+
deleting the preceding blank line, or inserting a space in the
|
|
3458
|
+
preceding blank lines, or putting a list continuation character
|
|
3459
|
+
(<code class="literal">+</code>) in the preceding blank line.
|
|
3460
|
+
</li><li>
|
|
3461
|
+
Nested text formatting is highlighted according to the outer format.
|
|
3462
|
+
</li><li>
|
|
3463
|
+
Most escaped inline elements will be highlighted.
|
|
3464
|
+
</li><li>
|
|
3465
|
+
Unterminated quotes are highlighted, for example <code class="literal">'tis</code> would be
|
|
3466
|
+
seen as the start of emphasized text. As a damage control measure
|
|
3467
|
+
quoted text and macro attribute list containing quoted text always
|
|
3468
|
+
terminate at a blank line. This problem is usually ameliorated by
|
|
3469
|
+
the fact that characters such as <code class="literal">~</code>, <code class="literal">+</code>, <code class="literal">^</code> and <code class="literal">_</code> will
|
|
3470
|
+
normally occur inside monospaced quotes (unless they are used for
|
|
3471
|
+
quoting), for example <code class="literal">~/projects</code>.
|
|
3472
|
+
</li><li>
|
|
3473
|
+
If a closing block delimiter is not preceded by a blank line it is
|
|
3474
|
+
sometimes mistaken for a title underline. A workaround is to insert
|
|
3475
|
+
a blank line before the closing delimiter.
|
|
3476
|
+
</li><li>
|
|
3477
|
+
If a list block delimiter is mistaken for a title underline precede
|
|
3478
|
+
it with a blank line.
|
|
3479
|
+
</li><li>
|
|
3480
|
+
Tables are terminated by a blank line — use a space character on
|
|
3481
|
+
blank lines within your table.
|
|
3482
|
+
</li><li><p>
|
|
3483
|
+
Lines within a paragraph beginning with a period will be highlighted
|
|
3484
|
+
as block titles. For example:
|
|
3485
|
+
</p><pre class="literallayout">.chm file.</pre><p>To work around this restriction move the last word of the previous
|
|
3486
|
+
line to the start of the current (although words starting with a
|
|
3487
|
+
period should probably be quoted monospace which would also get around
|
|
3488
|
+
the problem).</p></li></ul></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="./images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Sometimes incorrect highlighting is caused by preceding lines
|
|
3489
|
+
that appear blank but contain white space characters — setting your
|
|
3490
|
+
editor options so that white space characters are visible is a good
|
|
3491
|
+
idea.</p></td></tr></table></div></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id2536808" href="#id2536808">1</a>] </sup>This is a rough structural guide, not a rigorous syntax
|
|
3492
|
+
definition</p></div><div class="footnote"><p><sup>[<a id="ftn.id2541843" href="#id2541843">2</a>] </sup>An example footnote.</p></div><div class="footnote"><p><sup>[<a id="ftn.id2544594" href="#id2544594">3</a>] </sup>The current table syntax is overly complicated
|
|
3493
|
+
and unwieldy to edit, hopefully a more usable syntax will appear in
|
|
3494
|
+
future versions of <span class="emphasis"><em>AsciiDoc</em></span>.</p></div><div class="footnote"><p><sup>[<a id="ftn.id2548980" href="#id2548980">4</a>] </sup>The existence of a <code class="literal">{revisionhistory}</code> attribute causes a
|
|
3495
|
+
revision history file (if it exists) to be included in DocBook
|
|
3496
|
+
outputs. If a file named like <code class="literal">{docname}-revhistory.xml</code> exists in
|
|
3497
|
+
the document's directory then it will be added verbatim to the DocBook
|
|
3498
|
+
header (see the <code class="literal">./doc/asciidoc-revhistory.xml</code> example that comes
|
|
3499
|
+
with the <span class="emphasis"><em>AsciiDoc</em></span> distribution).</p></div><div class="footnote"><p><sup>[<a id="ftn.id2550395" href="#id2550395">5</a>] </sup>Conditional inclusion using <code class="literal">ifdef</code> and <code class="literal">ifndef</code> macros
|
|
3500
|
+
differs from attribute conditional inclusion in that the former
|
|
3501
|
+
occurs when the file is read while the latter occurs when the
|
|
3502
|
+
contents are written.</p></div></div></div></body></html>
|