mizuho 0.9.6
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 +61 -0
- data/Rakefile +41 -0
- data/asciidoc/BUGS +39 -0
- data/asciidoc/BUGS.txt +32 -0
- data/asciidoc/CHANGELOG +1796 -0
- data/asciidoc/CHANGELOG.txt +1810 -0
- data/asciidoc/COPYING +339 -0
- data/asciidoc/COPYRIGHT +18 -0
- data/asciidoc/INSTALL +76 -0
- data/asciidoc/INSTALL.txt +71 -0
- data/asciidoc/Makefile.in +161 -0
- data/asciidoc/README +46 -0
- data/asciidoc/README.txt +36 -0
- data/asciidoc/a2x +674 -0
- data/asciidoc/asciidoc.conf +455 -0
- data/asciidoc/asciidoc.py +4998 -0
- data/asciidoc/common.aap +9 -0
- data/asciidoc/configure +2840 -0
- data/asciidoc/configure.ac +11 -0
- data/asciidoc/dblatex/asciidoc-dblatex.sty +20 -0
- data/asciidoc/dblatex/asciidoc-dblatex.xsl +32 -0
- data/asciidoc/dblatex/dblatex-readme.txt +39 -0
- data/asciidoc/doc/a2x.1 +257 -0
- data/asciidoc/doc/a2x.1.txt +204 -0
- data/asciidoc/doc/article.css-embedded.html +602 -0
- data/asciidoc/doc/article.html +46 -0
- data/asciidoc/doc/article.pdf +0 -0
- data/asciidoc/doc/article.txt +122 -0
- data/asciidoc/doc/asciidoc-revhistory.xml +27 -0
- data/asciidoc/doc/asciidoc.1 +155 -0
- data/asciidoc/doc/asciidoc.1.css-embedded.html +598 -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 +7853 -0
- data/asciidoc/doc/asciidoc.css.html +7416 -0
- data/asciidoc/doc/asciidoc.dict +733 -0
- data/asciidoc/doc/asciidoc.html +3339 -0
- data/asciidoc/doc/asciidoc.txt +4979 -0
- data/asciidoc/doc/asciimathml.txt +64 -0
- data/asciidoc/doc/book-multi.css-embedded.html +575 -0
- data/asciidoc/doc/book-multi.html +55 -0
- data/asciidoc/doc/book-multi.txt +155 -0
- data/asciidoc/doc/book.css-embedded.html +607 -0
- data/asciidoc/doc/book.html +43 -0
- data/asciidoc/doc/book.txt +131 -0
- data/asciidoc/doc/customers.csv +18 -0
- data/asciidoc/doc/docbook-xsl.css +272 -0
- data/asciidoc/doc/faq.txt +547 -0
- data/asciidoc/doc/latex-backend.html +117 -0
- data/asciidoc/doc/latex-backend.txt +191 -0
- data/asciidoc/doc/latexmath.txt +244 -0
- data/asciidoc/doc/latexmathml.txt +41 -0
- data/asciidoc/doc/main.aap +297 -0
- data/asciidoc/doc/music-filter.html +566 -0
- data/asciidoc/doc/music-filter.pdf +0 -0
- data/asciidoc/doc/music-filter.txt +158 -0
- data/asciidoc/doc/source-highlight-filter.html +214 -0
- data/asciidoc/doc/source-highlight-filter.pdf +0 -0
- data/asciidoc/doc/source-highlight-filter.txt +203 -0
- data/asciidoc/docbook-xsl/asciidoc-docbook-xsl.txt +43 -0
- data/asciidoc/docbook-xsl/chunked.xsl +19 -0
- data/asciidoc/docbook-xsl/common.xsl +67 -0
- data/asciidoc/docbook-xsl/fo.xsl +149 -0
- data/asciidoc/docbook-xsl/htmlhelp.xsl +17 -0
- data/asciidoc/docbook-xsl/manpage.xsl +31 -0
- data/asciidoc/docbook-xsl/text.xsl +50 -0
- data/asciidoc/docbook-xsl/xhtml.xsl +14 -0
- data/asciidoc/docbook.conf +721 -0
- data/asciidoc/examples/website/ASCIIMathML.js +938 -0
- data/asciidoc/examples/website/CHANGELOG.html +4389 -0
- data/asciidoc/examples/website/CHANGELOG.txt +1810 -0
- data/asciidoc/examples/website/INSTALL.html +161 -0
- data/asciidoc/examples/website/INSTALL.txt +71 -0
- data/asciidoc/examples/website/LaTeXMathML.js +1223 -0
- data/asciidoc/examples/website/README-website.html +118 -0
- data/asciidoc/examples/website/README-website.txt +29 -0
- data/asciidoc/examples/website/README.html +125 -0
- data/asciidoc/examples/website/README.txt +36 -0
- data/asciidoc/examples/website/a2x.1.html +419 -0
- data/asciidoc/examples/website/a2x.1.txt +204 -0
- data/asciidoc/examples/website/asciidoc-docbook-xsl.html +130 -0
- data/asciidoc/examples/website/asciidoc-docbook-xsl.txt +43 -0
- data/asciidoc/examples/website/asciidoc-graphviz-sample.txt +130 -0
- data/asciidoc/examples/website/asciimathml.txt +64 -0
- data/asciidoc/examples/website/build-website.sh +25 -0
- data/asciidoc/examples/website/customers.csv +18 -0
- data/asciidoc/examples/website/downloads.html +257 -0
- data/asciidoc/examples/website/downloads.txt +121 -0
- data/asciidoc/examples/website/faq.html +673 -0
- data/asciidoc/examples/website/faq.txt +547 -0
- data/asciidoc/examples/website/index.html +419 -0
- data/asciidoc/examples/website/index.txt +245 -0
- data/asciidoc/examples/website/latex-backend.html +535 -0
- data/asciidoc/examples/website/latex-backend.txt +191 -0
- data/asciidoc/examples/website/latexmathml.txt +41 -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/manpage.txt +118 -0
- data/asciidoc/examples/website/music-filter.html +242 -0
- data/asciidoc/examples/website/music-filter.txt +158 -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/newlists.txt +40 -0
- data/asciidoc/examples/website/newtables.txt +397 -0
- data/asciidoc/examples/website/sample1.png +0 -0
- data/asciidoc/examples/website/sample3.png +0 -0
- data/asciidoc/examples/website/sample4.png +0 -0
- data/asciidoc/examples/website/source-highlight-filter.html +286 -0
- data/asciidoc/examples/website/source-highlight-filter.txt +203 -0
- data/asciidoc/examples/website/support.html +78 -0
- data/asciidoc/examples/website/support.txt +5 -0
- data/asciidoc/examples/website/toc.js +69 -0
- data/asciidoc/examples/website/userguide.html +7460 -0
- data/asciidoc/examples/website/userguide.txt +4979 -0
- data/asciidoc/examples/website/version83.txt +37 -0
- data/asciidoc/examples/website/version9.html +143 -0
- data/asciidoc/examples/website/version9.txt +48 -0
- data/asciidoc/examples/website/xhtml11-manpage.css +18 -0
- data/asciidoc/examples/website/xhtml11-quirks.css +41 -0
- data/asciidoc/examples/website/xhtml11.css +328 -0
- data/asciidoc/filters/code/code-filter-readme.txt +37 -0
- data/asciidoc/filters/code/code-filter-test.txt +15 -0
- data/asciidoc/filters/code/code-filter.conf +8 -0
- data/asciidoc/filters/code/code-filter.py +239 -0
- data/asciidoc/filters/graphviz/asciidoc-graphviz-sample.txt +130 -0
- data/asciidoc/filters/graphviz/graphviz-filter.conf +39 -0
- data/asciidoc/filters/graphviz/graphviz2png.py +154 -0
- data/asciidoc/filters/music/music-filter-test.txt +40 -0
- data/asciidoc/filters/music/music-filter.conf +40 -0
- data/asciidoc/filters/music/music2png.py +189 -0
- data/asciidoc/filters/source/source-highlight-filter-test.txt +19 -0
- data/asciidoc/filters/source/source-highlight-filter.conf +108 -0
- data/asciidoc/help.conf +213 -0
- data/asciidoc/html4.conf +460 -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 +201 -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/stylesheets/docbook-xsl.css +272 -0
- data/asciidoc/stylesheets/xhtml11-manpage.css +18 -0
- data/asciidoc/stylesheets/xhtml11-quirks.css +41 -0
- data/asciidoc/stylesheets/xhtml11.css +328 -0
- data/asciidoc/text.conf +16 -0
- data/asciidoc/vim/ftdetect/asciidoc_filetype.vim +53 -0
- data/asciidoc/vim/syntax/asciidoc.vim +165 -0
- data/asciidoc/wordpress.conf +48 -0
- data/asciidoc/xhtml11-quirks.conf +57 -0
- data/asciidoc/xhtml11.conf +645 -0
- data/bin/mizuho +47 -0
- data/bin/mizuho-asciidoc +4 -0
- data/lib/mizuho.rb +10 -0
- data/lib/mizuho/chapter.rb +54 -0
- data/lib/mizuho/generator.rb +134 -0
- data/lib/mizuho/heading.rb +46 -0
- data/lib/mizuho/parser.rb +103 -0
- data/lib/mizuho/source_highlight.rb +2 -0
- data/lib/mizuho/template.rb +50 -0
- data/source-highlight/ada.lang +38 -0
- data/source-highlight/bib.lang +6 -0
- data/source-highlight/bison.lang +3 -0
- data/source-highlight/c.lang +41 -0
- data/source-highlight/c_comment.lang +27 -0
- data/source-highlight/c_string.lang +9 -0
- data/source-highlight/caml.lang +16 -0
- data/source-highlight/changelog.lang +8 -0
- data/source-highlight/clike_vardeclaration.lang +4 -0
- data/source-highlight/cpp.lang +15 -0
- data/source-highlight/csharp.lang +36 -0
- data/source-highlight/css.lang +14 -0
- data/source-highlight/css_common.outlang +26 -0
- data/source-highlight/darwin/source-highlight +0 -0
- data/source-highlight/default.css +51 -0
- data/source-highlight/default.lang +8 -0
- data/source-highlight/default.style +57 -0
- data/source-highlight/desktop.lang +7 -0
- data/source-highlight/diff.lang +32 -0
- data/source-highlight/docbook.outlang +36 -0
- data/source-highlight/esc.outlang +46 -0
- data/source-highlight/esc.style +35 -0
- data/source-highlight/extreme_comment.lang +5 -0
- data/source-highlight/extreme_comment2.lang +5 -0
- data/source-highlight/extreme_comment3.lang +15 -0
- data/source-highlight/fixed-fortran.lang +5 -0
- data/source-highlight/flex.lang +37 -0
- data/source-highlight/fortran.lang +57 -0
- data/source-highlight/function.lang +2 -0
- data/source-highlight/glsl.lang +86 -0
- data/source-highlight/haxe.lang +7 -0
- data/source-highlight/html.lang +7 -0
- data/source-highlight/html.outlang +25 -0
- data/source-highlight/html_common.outlang +35 -0
- data/source-highlight/html_notfixed.outlang +22 -0
- data/source-highlight/html_ref.outlang +6 -0
- data/source-highlight/htmlcss.outlang +28 -0
- data/source-highlight/htmltable.outlang +14 -0
- data/source-highlight/htmltablelinenum.outlang +26 -0
- data/source-highlight/java.lang +26 -0
- data/source-highlight/javadoc.outlang +24 -0
- data/source-highlight/javascript.lang +27 -0
- data/source-highlight/key_string.lang +4 -0
- data/source-highlight/lang.map +108 -0
- data/source-highlight/langdef.lang +21 -0
- data/source-highlight/latex.lang +52 -0
- data/source-highlight/latex.outlang +59 -0
- data/source-highlight/latexcolor.outlang +44 -0
- data/source-highlight/ldap.lang +10 -0
- data/source-highlight/log.lang +53 -0
- data/source-highlight/logtalk.lang +85 -0
- data/source-highlight/lsm.lang +7 -0
- data/source-highlight/lua.lang +27 -0
- data/source-highlight/m4.lang +27 -0
- data/source-highlight/makefile.lang +42 -0
- data/source-highlight/nohilite.lang +2 -0
- data/source-highlight/number.lang +3 -0
- data/source-highlight/outlang.lang +16 -0
- data/source-highlight/outlang.map +12 -0
- data/source-highlight/pascal.lang +20 -0
- data/source-highlight/perl.lang +134 -0
- data/source-highlight/php.lang +25 -0
- data/source-highlight/postscript.lang +42 -0
- data/source-highlight/prolog.lang +37 -0
- data/source-highlight/properties.lang +7 -0
- data/source-highlight/python.lang +26 -0
- data/source-highlight/ruby.lang +32 -0
- data/source-highlight/scala.lang +31 -0
- data/source-highlight/script_comment.lang +3 -0
- data/source-highlight/sh.lang +38 -0
- data/source-highlight/slang.lang +25 -0
- data/source-highlight/sml.lang +5 -0
- data/source-highlight/source-highlight +24 -0
- data/source-highlight/spec.lang +12 -0
- data/source-highlight/sql.lang +46 -0
- data/source-highlight/style.defaults +15 -0
- data/source-highlight/style.lang +16 -0
- data/source-highlight/style2.style +10 -0
- data/source-highlight/style3.style +10 -0
- data/source-highlight/symbols.lang +2 -0
- data/source-highlight/tcl.lang +35 -0
- data/source-highlight/texinfo.outlang +34 -0
- data/source-highlight/texinfo.style +20 -0
- data/source-highlight/url.lang +3 -0
- data/source-highlight/xhtml.outlang +25 -0
- data/source-highlight/xhtml_common.outlang +8 -0
- data/source-highlight/xhtml_notfixed.outlang +16 -0
- data/source-highlight/xhtmlcss.outlang +19 -0
- data/source-highlight/xhtmltable.outlang +7 -0
- data/source-highlight/xml.lang +17 -0
- data/source-highlight/xorg.lang +10 -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/generator_spec.rb +60 -0
- data/test/parser_spec.rb +239 -0
- data/test/spec_helper.rb +51 -0
- metadata +358 -0
|
@@ -0,0 +1,3339 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
2
|
+
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>AsciiDoc User Guide</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id2425213"></a>AsciiDoc User Guide</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Stuart</span> <span class="surname">Rackham</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:srackham@gmail.com">srackham@gmail.com</a>></code></p></div></div></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 8.3.3</td><td align="left">2 January 2009</td><td align="left">SJR</td></tr></table></div></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#_introduction">1. Introduction</a></span></dt><dt><span class="section"><a href="#X6">2. Getting Started</a></span></dt><dd><dl><dt><span class="section"><a href="#_installing_asciidoc">2.1. Installing AsciiDoc</a></span></dt><dt><span class="section"><a href="#X11">2.2. Example AsciiDoc Documents</a></span></dt></dl></dd><dt><span class="section"><a href="#_asciidoc_document_types">3. AsciiDoc Document Types</a></span></dt><dd><dl><dt><span class="section"><a href="#_article">3.1. article</a></span></dt><dt><span class="section"><a href="#_book">3.2. book</a></span></dt><dt><span class="section"><a href="#_manpage">3.3. manpage</a></span></dt></dl></dd><dt><span class="section"><a href="#X5">4. AsciiDoc Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#_docbook">4.1. docbook</a></span></dt><dt><span class="section"><a href="#X33">4.2. xhtml11</a></span></dt><dt><span class="section"><a href="#_html4">4.3. html4</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_structure">5. Document Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#_block_elements">5.1. Block Elements</a></span></dt><dt><span class="section"><a href="#_header">5.2. Header</a></span></dt><dt><span class="section"><a href="#_preamble">5.3. Preamble</a></span></dt><dt><span class="section"><a href="#_sections">5.4. Sections</a></span></dt><dt><span class="section"><a href="#_inline_elements">5.5. Inline Elements</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_processing">6. Document Processing</a></span></dt><dt><span class="section"><a href="#_text_formatting">7. Text Formatting</a></span></dt><dd><dl><dt><span class="section"><a href="#X51">7.1. Quoted Text</a></span></dt><dt><span class="section"><a href="#_superscripts_and_subscripts">7.2. Superscripts and Subscripts</a></span></dt><dt><span class="section"><a href="#_line_breaks">7.3. Line Breaks</a></span></dt><dt><span class="section"><a href="#_page_breaks">7.4. Page Breaks</a></span></dt><dt><span class="section"><a href="#_rulers">7.5. Rulers</a></span></dt><dt><span class="section"><a href="#_tabs">7.6. Tabs</a></span></dt><dt><span class="section"><a href="#_replacements">7.7. Replacements</a></span></dt><dt><span class="section"><a href="#_special_words">7.8. Special Words</a></span></dt></dl></dd><dt><span class="section"><a href="#X17">8. Titles</a></span></dt><dd><dl><dt><span class="section"><a href="#_two_line_titles">8.1. Two line titles</a></span></dt><dt><span class="section"><a href="#X46">8.2. One line titles</a></span></dt></dl></dd><dt><span class="section"><a href="#X42">9. BlockTitles</a></span></dt><dt><span class="section"><a href="#X41">10. BlockId Element</a></span></dt><dt><span class="section"><a href="#_paragraphs">11. Paragraphs</a></span></dt><dd><dl><dt><span class="section"><a href="#_default_paragraph">11.1. Default Paragraph</a></span></dt><dt><span class="section"><a href="#_literal_paragraph">11.2. Literal Paragraph</a></span></dt><dt><span class="section"><a href="#X28">11.3. Admonition Paragraphs</a></span></dt></dl></dd><dt><span class="section"><a href="#_delimited_blocks">12. Delimited Blocks</a></span></dt><dd><dl><dt><span class="section"><a href="#_predefined_delimited_blocks">12.1. Predefined Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_listing_blocks">12.2. Listing Blocks</a></span></dt><dt><span class="section"><a href="#X65">12.3. Literal Blocks</a></span></dt><dt><span class="section"><a href="#_sidebarblocks">12.4. SidebarBlocks</a></span></dt><dt><span class="section"><a href="#X26">12.5. Comment Blocks</a></span></dt><dt><span class="section"><a href="#X76">12.6. Passthrough Blocks</a></span></dt><dt><span class="section"><a href="#_quote_blocks">12.7. Quote Blocks</a></span></dt><dt><span class="section"><a href="#X48">12.8. Example Blocks</a></span></dt><dt><span class="section"><a href="#X22">12.9. Admonition Blocks</a></span></dt></dl></dd><dt><span class="section"><a href="#X64">13. Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#_bulleted_and_numbered_lists">13.1. Bulleted and Numbered Lists</a></span></dt><dt><span class="section"><a href="#_labeled_lists">13.2. Labeled Lists</a></span></dt><dt><span class="section"><a href="#_question_and_answer_lists">13.3. Question and Answer Lists</a></span></dt><dt><span class="section"><a href="#_glossary_lists">13.4. Glossary Lists</a></span></dt><dt><span class="section"><a href="#_bibliography_lists">13.5. Bibliography Lists</a></span></dt><dt><span class="section"><a href="#X15">13.6. List Item Continuation</a></span></dt><dt><span class="section"><a href="#X29">13.7. List Block</a></span></dt></dl></dd><dt><span class="section"><a href="#_footnotes">14. Footnotes</a></span></dt><dt><span class="section"><a href="#_indexes">15. Indexes</a></span></dt><dt><span class="section"><a href="#_callouts">16. Callouts</a></span></dt><dd><dl><dt><span class="section"><a href="#_implementation_notes">16.1. Implementation Notes</a></span></dt><dt><span class="section"><a href="#_including_callouts_in_included_code">16.2. Including callouts in included code</a></span></dt></dl></dd><dt><span class="section"><a href="#_macros">17. Macros</a></span></dt><dd><dl><dt><span class="section"><a href="#_inline_macros">17.1. Inline Macros</a></span></dt><dt><span class="section"><a href="#_block_macros">17.2. Block Macros</a></span></dt><dt><span class="section"><a href="#_system_macros">17.3. System Macros</a></span></dt><dt><span class="section"><a href="#X77">17.4. Passthrough macros</a></span></dt><dt><span class="section"><a href="#_macro_definitions">17.5. Macro Definitions</a></span></dt></dl></dd><dt><span class="section"><a href="#_tables">18. Tables</a></span></dt><dd><dl><dt><span class="section"><a href="#_example_tables">18.1. Example tables</a></span></dt><dt><span class="section"><a href="#X68">18.2. Table input data formats</a></span></dt><dt><span class="section"><a href="#X69">18.3. Table attributes</a></span></dt><dt><span class="section"><a href="#X70">18.4. Column Specifiers</a></span></dt><dt><span class="section"><a href="#X71">18.5. Table styles</a></span></dt><dt><span class="section"><a href="#X72">18.6. Markup attributes</a></span></dt><dt><span class="section"><a href="#_nested_tables">18.7. Nested tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X1">19. Manpage Documents</a></span></dt><dd><dl><dt><span class="section"><a href="#_document_header">19.1. Document Header</a></span></dt><dt><span class="section"><a href="#_the_name_section">19.2. The NAME Section</a></span></dt><dt><span class="section"><a href="#_the_synopsis_section">19.3. The SYNOPSIS Section</a></span></dt><dt><span class="section"><a href="#_refmiscinfo_attributes">19.4. refmiscinfo attributes</a></span></dt></dl></dd><dt><span class="section"><a href="#X78">20. Mathematical Formulas</a></span></dt><dd><dl><dt><span class="section"><a href="#_latex_math">20.1. LaTeX Math</a></span></dt><dt><span class="section"><a href="#_asciimathml">20.2. ASCIIMathML</a></span></dt><dt><span class="section"><a href="#_latexmathml">20.3. LaTeXMathML</a></span></dt><dt><span class="section"><a href="#_mathml">20.4. MathML</a></span></dt></dl></dd><dt><span class="section"><a href="#X7">21. Configuration Files</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuration_file_format">21.1. Configuration File Format</a></span></dt><dt><span class="section"><a href="#_miscellaneous_section">21.2. Miscellaneous section</a></span></dt><dt><span class="section"><a href="#_titles_section">21.3. Titles section</a></span></dt><dt><span class="section"><a href="#_tags_section">21.4. Tags section</a></span></dt><dt><span class="section"><a href="#_attributes_section">21.5. Attributes section</a></span></dt><dt><span class="section"><a href="#_special_characters_section">21.6. Special Characters section</a></span></dt><dt><span class="section"><a href="#_quoted_text_section">21.7. Quoted Text section</a></span></dt><dt><span class="section"><a href="#_special_words_section">21.8. Special Words section</a></span></dt><dt><span class="section"><a href="#X10">21.9. Replacements section</a></span></dt><dt><span class="section"><a href="#_markup_template_sections">21.10. Markup Template Sections</a></span></dt><dt><span class="section"><a href="#X27">21.11. Configuration File Names and Locations</a></span></dt></dl></dd><dt><span class="section"><a href="#_document_attributes">22. Document Attributes</a></span></dt><dt><span class="section"><a href="#X18">23. Attribute Entries</a></span></dt><dd><dl><dt><span class="section"><a href="#_setting_configuration_entries">23.1. Setting configuration entries</a></span></dt></dl></dd><dt><span class="section"><a href="#X21">24. Attribute Lists</a></span></dt><dd><dl><dt><span class="section"><a href="#X75">24.1. Options attribute</a></span></dt><dt><span class="section"><a href="#_macro_attribute_lists">24.2. Macro Attribute lists</a></span></dt><dt><span class="section"><a href="#_attributelist_element">24.3. AttributeList Element</a></span></dt></dl></dd><dt><span class="section"><a href="#_attribute_references">25. Attribute References</a></span></dt><dd><dl><dt><span class="section"><a href="#_simple_attributes_references">25.1. Simple Attributes References</a></span></dt><dt><span class="section"><a href="#_conditional_attribute_references">25.2. Conditional Attribute References</a></span></dt><dt><span class="section"><a href="#X24">25.3. System Attribute References</a></span></dt></dl></dd><dt><span class="section"><a href="#X60">26. Intrinsic Attributes</a></span></dt><dt><span class="section"><a href="#X73">27. Block Element Definitions</a></span></dt><dd><dl><dt><span class="section"><a href="#X23">27.1. Styles</a></span></dt><dt><span class="section"><a href="#_paragraphs_2">27.2. Paragraphs</a></span></dt><dt><span class="section"><a href="#_delimited_blocks_2">27.3. Delimited Blocks</a></span></dt><dt><span class="section"><a href="#_lists">27.4. Lists</a></span></dt><dt><span class="section"><a href="#_tables_2">27.5. Tables</a></span></dt></dl></dd><dt><span class="section"><a href="#X59">28. Filters</a></span></dt><dd><dl><dt><span class="section"><a href="#_filter_search_paths">28.1. Filter Search Paths</a></span></dt><dt><span class="section"><a href="#_filter_configuration_files">28.2. Filter Configuration Files</a></span></dt><dt><span class="section"><a href="#X56">28.3. Code Filter</a></span></dt><dt><span class="section"><a href="#X57">28.4. Source Code Highlighter Filter</a></span></dt><dt><span class="section"><a href="#X58">28.5. Music Filter</a></span></dt></dl></dd><dt><span class="section"><a href="#X12">29. Converting DocBook to other file formats</a></span></dt><dd><dl><dt><span class="section"><a href="#X43">29.1. a2x Toolchain Wrapper</a></span></dt><dt><span class="section"><a href="#_html_generation">29.2. HTML generation</a></span></dt><dt><span class="section"><a href="#_pdf_generation">29.3. PDF generation</a></span></dt><dt><span class="section"><a href="#_html_help_generation">29.4. HTML Help generation</a></span></dt><dt><span class="section"><a href="#_toolchain_components_summary">29.5. Toolchain components summary</a></span></dt><dt><span class="section"><a href="#X67">29.6. AsciiDoc dblatex configuration files</a></span></dt><dt><span class="section"><a href="#_asciidoc_docbook_xsl_stylesheets_drivers">29.7. AsciiDoc DocBook XSL Stylesheets drivers</a></span></dt></dl></dd><dt><span class="section"><a href="#_generating_plain_text_files">30. Generating Plain Text Files</a></span></dt><dt><span class="section"><a href="#_xml_and_character_sets">31. XML and Character Sets</a></span></dt><dd><dl><dt><span class="section"><a href="#_pdf_fonts">31.1. PDF Fonts</a></span></dt></dl></dd><dt><span class="section"><a href="#X36">32. Help Commands</a></span></dt><dd><dl><dt><span class="section"><a href="#_customizing_help">32.1. Customizing Help</a></span></dt></dl></dd><dt><span class="section"><a href="#_tips_and_tricks">33. Tips and Tricks</a></span></dt><dd><dl><dt><span class="section"><a href="#_know_your_editor">33.1. Know Your Editor</a></span></dt><dt><span class="section"><a href="#X20">33.2. Vim Commands for Formatting AsciiDoc</a></span></dt><dt><span class="section"><a href="#_troubleshooting">33.3. Troubleshooting</a></span></dt><dt><span class="section"><a href="#_gotchas">33.4. Gotchas</a></span></dt><dt><span class="section"><a href="#_combining_separate_documents">33.5. Combining separate documents</a></span></dt><dt><span class="section"><a href="#_processing_document_sections_separately">33.6. Processing document sections separately</a></span></dt><dt><span class="section"><a href="#_processing_document_snippets">33.7. Processing document snippets</a></span></dt><dt><span class="section"><a href="#_badges_in_html_page_footers">33.8. Badges in HTML page footers</a></span></dt><dt><span class="section"><a href="#_pretty_printing_asciidoc_output">33.9. Pretty printing AsciiDoc output</a></span></dt><dt><span class="section"><a href="#_supporting_minor_docbook_dtd_variations">33.10. Supporting minor DocBook DTD variations</a></span></dt><dt><span class="section"><a href="#_shipping_stand_alone_asciidoc_source">33.11. Shipping stand-alone AsciiDoc source</a></span></dt><dt><span class="section"><a href="#_inserting_blank_space">33.12. Inserting blank space</a></span></dt><dt><span class="section"><a href="#_closing_open_sections">33.13. Closing open sections</a></span></dt><dt><span class="section"><a href="#_validating_output_files">33.14. Validating output files</a></span></dt></dl></dd><dt><span class="glossary"><a href="#_glossary">Glossary</a></span></dt><dt><span class="appendix"><a href="#_migration_notes">A. Migration Notes</a></span></dt><dd><dl><dt><span class="section"><a href="#X53">A.1. Version 7 to version 8</a></span></dt></dl></dd><dt><span class="appendix"><a href="#X38">B. Packager Notes</a></span></dt><dt><span class="appendix"><a href="#X39">C. AsciiDoc Safe Mode</a></span></dt><dt><span class="appendix"><a href="#_using_asciidoc_with_non_english_languages">D. Using AsciiDoc with non-English Languages</a></span></dt><dt><span class="appendix"><a href="#_vim_syntax_highlighter">E. Vim Syntax Highlighter</a></span></dt><dd><dl><dt><span class="section"><a href="#_limitations">E.1. Limitations</a></span></dt></dl></dd><dt><span class="appendix"><a href="#X74">F. Attribute Options</a></span></dt></dl></div><p><span class="emphasis"><em>AsciiDoc</em></span> is a text document format for writing short documents,
|
|
3
|
+
articles, books and UNIX man pages. <span class="emphasis"><em>AsciiDoc</em></span> files can be translated
|
|
4
|
+
to HTML and DocBook markups using the <code class="literal">asciidoc(1)</code> command. <span class="emphasis"><em>AsciiDoc</em></span>
|
|
5
|
+
is highly configurable: both the <span class="emphasis"><em>AsciiDoc</em></span> source file syntax and the
|
|
6
|
+
backend output markups (which can be almost any type of SGML/XML
|
|
7
|
+
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
|
|
8
|
+
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 class="link" 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>
|
|
9
|
+
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
|
|
10
|
+
what computing environment you use, you can always read and write
|
|
11
|
+
plain text documentation. But for many applications plain text is not
|
|
12
|
+
a viable presentation format. HTML, PDF and roff (roff is used for
|
|
13
|
+
man pages) are the most widely used UNIX presentation formats.
|
|
14
|
+
DocBook is a popular UNIX documentation markup format which can be
|
|
15
|
+
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
|
|
16
|
+
can be translated to DocBook or HTML using the <code class="literal">asciidoc(1)</code> command.
|
|
17
|
+
You can then either use <code class="literal">asciidoc(1)</code> generated HTML directly or run
|
|
18
|
+
<code class="literal">asciidoc(1)</code> DocBook output through your favorite DocBook toolchain or
|
|
19
|
+
use the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">a2x(1)</code> toolchain wrapper to produce PDF, DVI, LaTeX,
|
|
20
|
+
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:
|
|
21
|
+
<span class="emphasis"><em>AsciiDoc</em></span> files are unencumbered by markup and are easily viewed,
|
|
22
|
+
proofed and edited.</p><p><span class="emphasis"><em>AsciiDoc</em></span> is light weight: it consists of a single Python script and a
|
|
23
|
+
bunch of configuration files. Apart from <code class="literal">asciidoc(1)</code> and a Python
|
|
24
|
+
interpreter, no other programs are required to convert <span class="emphasis"><em>AsciiDoc</em></span> text
|
|
25
|
+
files to DocBook or HTML. See <a class="link" href="#X11" title="2.2. Example AsciiDoc Documents">Example <span class="emphasis"><em>AsciiDoc</em></span> Documents</a>
|
|
26
|
+
below.</p><p>You write an <span class="emphasis"><em>AsciiDoc</em></span> document the same way you would write a normal
|
|
27
|
+
text document, there are no markup tags or arcane notations. Built-in
|
|
28
|
+
<span class="emphasis"><em>AsciiDoc</em></span> formatting rules have been kept to a minimum and are
|
|
29
|
+
reasonably obvious.</p><p>Text markup conventions tend to be a matter of (often strong) personal
|
|
30
|
+
preference: if the default syntax is not to your liking you can define
|
|
31
|
+
your own by editing the text based <code class="literal">asciidoc(1)</code> configuration files.
|
|
32
|
+
You can create your own configuration files to translate <span class="emphasis"><em>AsciiDoc</em></span>
|
|
33
|
+
documents to almost any SGML/XML markup.</p><p><code class="literal">asciidoc(1)</code> comes with a set of configuration files to translate
|
|
34
|
+
<span class="emphasis"><em>AsciiDoc</em></span> articles, books or man pages to HTML or DocBook backend
|
|
35
|
+
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
|
|
36
|
+
format. But DocBook is a complex language, the marked up text is
|
|
37
|
+
difficult to read and even more difficult to write directly — I found
|
|
38
|
+
I was spending more time typing markup tags, consulting reference
|
|
39
|
+
manuals and fixing syntax errors, than I was writing the
|
|
40
|
+
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
|
|
41
|
+
procedures. Packagers take a look at <a class="link" 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
|
|
42
|
+
<span class="emphasis"><em>AsciiDoc</em></span> web site and/or distributed examples:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
43
|
+
Take a look at the linked examples on the <span class="emphasis"><em>AsciiDoc</em></span> web site home
|
|
44
|
+
page <a class="ulink" 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>
|
|
45
|
+
sidebar menu item to view corresponding <span class="emphasis"><em>AsciiDoc</em></span> source.
|
|
46
|
+
</li><li>
|
|
47
|
+
Read the <code class="literal">.txt</code> source files in the distribution <code class="literal">./doc</code> directory
|
|
48
|
+
in conjunction with the corresponding HTML and DocBook XML files.
|
|
49
|
+
</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
|
|
50
|
+
manpage. All document types share the same <span class="emphasis"><em>AsciiDoc</em></span> format with some
|
|
51
|
+
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>
|
|
52
|
+
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
|
|
53
|
+
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
|
|
54
|
+
<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
|
|
55
|
+
option to add level 0 book part sections.</p><p>Book documents will normally be used to produce DocBook output since
|
|
56
|
+
DocBook processors can automatically generate footnotes, table of
|
|
57
|
+
contents, list of tables, list of figures, list of examples and
|
|
58
|
+
indexes.</p><p><span class="emphasis"><em>AsciiDoc</em></span> markup supports standard DocBook frontmatter and backmatter
|
|
59
|
+
<a class="link" href="#X16" title="5.4.1. Special Sections">special sections</a> (dedication, preface, bibliography, glossary,
|
|
60
|
+
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">
|
|
61
|
+
Book
|
|
62
|
+
</span></dt><dd>
|
|
63
|
+
The <code class="literal">./doc/book.txt</code> file in the <span class="emphasis"><em>AsciiDoc</em></span> distribution.
|
|
64
|
+
</dd><dt><span class="term">
|
|
65
|
+
Multi-part book
|
|
66
|
+
</span></dt><dd>
|
|
67
|
+
The <code class="literal">./doc/book-multi.txt</code> file in the <span class="emphasis"><em>AsciiDoc</em></span> distribution.
|
|
68
|
+
</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
|
|
69
|
+
observe special header title and section naming conventions — see the
|
|
70
|
+
<a class="link" 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
|
|
71
|
+
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
|
|
72
|
+
backend format specified by the <code class="literal">-b</code> (<code class="literal">--backend</code>) command-line
|
|
73
|
+
option. <code class="literal">asciidoc(1)</code> itself has little intrinsic knowledge of backend
|
|
74
|
+
formats, all translation rules are contained in customizable cascading
|
|
75
|
+
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
|
|
76
|
+
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
|
|
77
|
+
<span class="emphasis"><em>manpage</em></span> document types).</p><p>DocBook documents are not designed to be viewed directly. Most Linux
|
|
78
|
+
distributions come with conversion tools (collectively called a
|
|
79
|
+
toolchain) for <a class="link" href="#X12" title="29. Converting DocBook to other file formats">converting DocBook files</a> to presentation
|
|
80
|
+
formats such as Postscript, HTML, PDF, DVI, PostScript, LaTeX, roff
|
|
81
|
+
(the native man page format), HTMLHelp, JavaHelp and text.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
82
|
+
The <code class="literal">--backend=docbook</code> command-line option produces DocBook XML.
|
|
83
|
+
You can produce the older DocBook SGML format using the
|
|
84
|
+
<code class="literal">--attribute sgml</code> command-line option.
|
|
85
|
+
</li><li>
|
|
86
|
+
Use the optional <a class="link" href="#X54" title="???TITLE???"><code class="literal">encoding</code></a> attribute to set the character
|
|
87
|
+
set encoding.
|
|
88
|
+
</li><li>
|
|
89
|
+
Use the optional <code class="literal">imagesdir</code> attribute to prepend to the target file
|
|
90
|
+
name paths in image inline and block macros. Defaults to a blank
|
|
91
|
+
string.
|
|
92
|
+
</li><li>
|
|
93
|
+
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>
|
|
94
|
+
element although it’s more usual to use an explicit <span class="emphasis"><em>Preface</em></span>
|
|
95
|
+
special section (see the <code class="literal">./doc/book.txt</code> example book).
|
|
96
|
+
</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
|
|
97
|
+
markup styled with CSS2. Default output file have a <code class="literal">.html</code> extension.
|
|
98
|
+
<span class="emphasis"><em>xhtml11</em></span> document generation is influenced by the following
|
|
99
|
+
optional attributes (the default behavior is to generate XHTML with no
|
|
100
|
+
section numbers, embedded CSS and no linked admonition icon images):</p><div class="variablelist"><dl><dt><span class="term">
|
|
101
|
+
numbered
|
|
102
|
+
</span></dt><dd>
|
|
103
|
+
Adds section numbers to section titles.
|
|
104
|
+
</dd><dt><span class="term">
|
|
105
|
+
toc
|
|
106
|
+
</span></dt><dd><p>
|
|
107
|
+
Adds a table of contents to the start of the document.
|
|
108
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
109
|
+
JavaScript needs to be enabled in your browser for this to work.
|
|
110
|
+
</li><li>
|
|
111
|
+
By default <span class="emphasis"><em>AsciiDoc</em></span> automatically embeds the required <code class="literal">toc.js</code>
|
|
112
|
+
JavaScript in the output document — use the <span class="emphasis"><em>linkcss</em></span> attribute
|
|
113
|
+
to link the script.
|
|
114
|
+
</li><li><p>
|
|
115
|
+
The following example generates a numbered table of contents by
|
|
116
|
+
embedding the <code class="literal">toc.js</code> script in the <code class="literal">mydoc.html</code> output document
|
|
117
|
+
(to link the script to the output document use the <span class="emphasis"><em>linkcss</em></span> and
|
|
118
|
+
<span class="emphasis"><em>scriptsdir</em></span> attributes):
|
|
119
|
+
</p><pre class="literallayout">$ asciidoc -a toc -a numbered mydoc.txt</pre></li></ul></div></dd><dt><span class="term">
|
|
120
|
+
toclevels
|
|
121
|
+
</span></dt><dd><p>
|
|
122
|
+
Sets the number of title levels (1..4) reported in the table of
|
|
123
|
+
contents (see the <span class="emphasis"><em>toc</em></span> attribute above). Defaults to 2 and must be
|
|
124
|
+
used with the <span class="emphasis"><em>toc</em></span> attribute. Example usage:
|
|
125
|
+
</p><pre class="literallayout">$ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt</pre></dd><dt><span class="term">
|
|
126
|
+
toc_title
|
|
127
|
+
</span></dt><dd>
|
|
128
|
+
Sets the table of contents title (defaults to <span class="emphasis"><em>Table of Contents</em></span>).
|
|
129
|
+
</dd><dt><span class="term">
|
|
130
|
+
linkcss
|
|
131
|
+
</span></dt><dd>
|
|
132
|
+
Link CSS stylesheets and JavaScripts (see the <span class="emphasis"><em>stylesdir</em></span> and
|
|
133
|
+
<span class="emphasis"><em>scriptsdir</em></span> attributes below). By default <span class="emphasis"><em>linkcss</em></span> is undefined in
|
|
134
|
+
which case stylesheets and scripts are automatically embedded in the
|
|
135
|
+
output document.
|
|
136
|
+
</dd><dt><span class="term">
|
|
137
|
+
scriptsdir
|
|
138
|
+
</span></dt><dd>
|
|
139
|
+
The name of the directory containing linked JavaScripts. Defaults to
|
|
140
|
+
<code class="literal">.</code> (the same directory as the linking document).
|
|
141
|
+
</dd><dt><span class="term">
|
|
142
|
+
stylesdir
|
|
143
|
+
</span></dt><dd>
|
|
144
|
+
The name of the directory containing linked stylesheets. Defaults to
|
|
145
|
+
<code class="literal">.</code> (the same directory as the linking document).
|
|
146
|
+
</dd><dt><span class="term">
|
|
147
|
+
stylesheet
|
|
148
|
+
</span></dt><dd>
|
|
149
|
+
The file name of an optional additional CSS stylesheet. If you are
|
|
150
|
+
embedding the stylesheet specify the actual file name; if you are
|
|
151
|
+
linking CSS specify the file name relative to the directory
|
|
152
|
+
specified by the <span class="emphasis"><em>stylesdir</em></span> attribute.
|
|
153
|
+
</dd><dt><span class="term">
|
|
154
|
+
icons
|
|
155
|
+
</span></dt><dd>
|
|
156
|
+
Link admonition paragraph and admonition block icon images and badge
|
|
157
|
+
images. By default <span class="emphasis"><em>icons</em></span> is undefined and text is used in place of
|
|
158
|
+
icon images.
|
|
159
|
+
</dd><dt><span class="term">
|
|
160
|
+
iconsdir
|
|
161
|
+
</span></dt><dd>
|
|
162
|
+
The name of the directory containing linked admonition and
|
|
163
|
+
navigation icons. Defaults to <code class="literal">./images/icons</code>.
|
|
164
|
+
</dd><dt><span class="term">
|
|
165
|
+
imagesdir
|
|
166
|
+
</span></dt><dd>
|
|
167
|
+
This attribute is prepended to the target image file name paths in
|
|
168
|
+
image inline and block macros. Defaults to a blank string.
|
|
169
|
+
</dd><dt><span class="term">
|
|
170
|
+
theme
|
|
171
|
+
</span></dt><dd>
|
|
172
|
+
Use alternative stylesheets (see <a class="link" href="#X35" title="4.2.1. Stylesheets">Stylesheets</a>).
|
|
173
|
+
</dd><dt><span class="term">
|
|
174
|
+
badges
|
|
175
|
+
</span></dt><dd>
|
|
176
|
+
Link badges (<span class="emphasis"><em>XHTML 1.1</em></span>, <span class="emphasis"><em>CSS</em></span> and <span class="emphasis"><em>Get Firefox!</em></span>) in document
|
|
177
|
+
footers. By default badges are omitted (<span class="emphasis"><em>badges</em></span> is undefined).
|
|
178
|
+
</dd></dl></div><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"><a id="X44"></a></th></tr><tr><td align="left" valign="top"><p>The path names of images, icons and scripts are relative to the
|
|
179
|
+
output document not the source document.</p></td></tr></table></div><div class="variablelist"><a id="X54"></a><dl><dt><span class="term">
|
|
180
|
+
encoding
|
|
181
|
+
</span></dt><dd><p>
|
|
182
|
+
Set the input and output document character set encoding. For
|
|
183
|
+
example the <code class="literal">--attribute encoding=ISO-8859-1</code> command-line option
|
|
184
|
+
will set the character set encoding to <code class="literal">ISO-8859-1</code>.
|
|
185
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
186
|
+
The default encoding is UTF-8.
|
|
187
|
+
</li><li>
|
|
188
|
+
This attribute specifies the character set in the output document.
|
|
189
|
+
</li><li>
|
|
190
|
+
The encoding name must correspond to a Python codec name or alias.
|
|
191
|
+
</li><li><p>
|
|
192
|
+
The <span class="emphasis"><em>encoding</em></span> attribute can be set using an AttributeEntry inside
|
|
193
|
+
the document header but it must come at the start of the document
|
|
194
|
+
before the document title. For example:
|
|
195
|
+
</p><pre class="literallayout">:encoding: ISO-8859-1</pre></li></ul></div></dd><dt><span class="term">
|
|
196
|
+
quirks
|
|
197
|
+
</span></dt><dd>
|
|
198
|
+
Use the <code class="literal">xhtml11-quirks.css</code> stylesheet to work around IE6 browser
|
|
199
|
+
incompatibilities (this is the default behavior).
|
|
200
|
+
</dd><dt><span class="term">
|
|
201
|
+
data-uri
|
|
202
|
+
</span></dt><dd>
|
|
203
|
+
Embed images referenced by <span class="emphasis"><em>image</em></span> macros using the <a class="link" href="#X66" title="Embedding images in XHTML documents">data: uri scheme</a>.
|
|
204
|
+
</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
|
|
205
|
+
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
|
|
206
|
+
omissions and errors that the <code class="literal">xhtml11-quirks.css</code> stylesheet and
|
|
207
|
+
<code class="literal">xhtml11-quirks.conf</code> configuration files are included during XHTML
|
|
208
|
+
backend processing to to implement workarounds for IE6. If you don’t
|
|
209
|
+
use IE6 then the quirks stylesheet and configuration files can be
|
|
210
|
+
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">
|
|
211
|
+
<code class="literal">./stylesheets/xhtml11.css</code>
|
|
212
|
+
</span></dt><dd>
|
|
213
|
+
The main stylesheet.
|
|
214
|
+
</dd><dt><span class="term">
|
|
215
|
+
<code class="literal">./stylesheets/xhtml11-manpage.css</code>
|
|
216
|
+
</span></dt><dd>
|
|
217
|
+
Tweaks for manpage document type generation.
|
|
218
|
+
</dd><dt><span class="term">
|
|
219
|
+
<code class="literal">./stylesheets/xhtml11-quirks.css</code>
|
|
220
|
+
</span></dt><dd>
|
|
221
|
+
Stylesheet modifications to work around IE6 browser
|
|
222
|
+
incompatibilities.
|
|
223
|
+
</dd></dl></div><p>Use the <span class="emphasis"><em>theme</em></span> attribute to select an alternative set of stylesheets.
|
|
224
|
+
For example, the command-line option <code class="literal">-a theme=foo</code> will use
|
|
225
|
+
stylesheets <code class="literal">foo.css</code>, <code class="literal">foo-manpage.css</code> and <code class="literal">foo-quirks.css</code> instead
|
|
226
|
+
of the default stylesheets.</p><p>Use the <span class="emphasis"><em>stylesheet</em></span> attribute to include an additional stylesheet in
|
|
227
|
+
XHTML documents. For example, the command-line option <code class="literal">-a
|
|
228
|
+
stylesheet=newsletter.css</code> will use stylesheets <code class="literal">newsletter.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><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 class="link" href="#X8">block elements</a>
|
|
229
|
+
starting with an optional document Header, followed by an optional
|
|
230
|
+
Preamble, followed by zero or more document Sections.</p><p>Almost any combination of zero or more elements constitutes a valid
|
|
231
|
+
<span class="emphasis"><em>AsciiDoc</em></span> document: documents can range from a single sentence to a
|
|
232
|
+
multi-part book.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_block_elements"></a>5.1. Block Elements</h3></div></div></div><p>Block elements consist of one or more lines of text and may contain
|
|
233
|
+
other block elements.</p><p>The <span class="emphasis"><em>AsciiDoc</em></span> block structure can be informally summarized
|
|
234
|
+
<sup>[<a id="id2528525" href="#ftn.id2528525" class="footnote">1</a>]</sup> as follows:</p><pre class="literallayout">Document ::= (Header?,Preamble?,Section*)
|
|
235
|
+
Header ::= (Title,(AuthorLine,RevisionLine?)?)
|
|
236
|
+
AuthorLine ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
|
|
237
|
+
RevisionLine ::= (Revision?,Date)
|
|
238
|
+
Preamble ::= (SectionBody)
|
|
239
|
+
Section ::= (Title,SectionBody?,(Section)*)
|
|
240
|
+
SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
|
|
241
|
+
Block ::= (Paragraph|DelimitedBlock|List|Table)
|
|
242
|
+
List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
|
|
243
|
+
BulletedList ::= (ListItem)+
|
|
244
|
+
NumberedList ::= (ListItem)+
|
|
245
|
+
CalloutList ::= (ListItem)+
|
|
246
|
+
LabeledList ::= (ListEntry)+
|
|
247
|
+
ListEntry ::= (ListLabel,ListItem)
|
|
248
|
+
ListLabel ::= (ListTerm+)
|
|
249
|
+
ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)</pre><p>Where:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
250
|
+
<span class="emphasis"><em>?</em></span> implies zero or one occurrence, <span class="emphasis"><em>+</em></span> implies one or more
|
|
251
|
+
occurrences, <span class="emphasis"><em>*</em></span> implies zero or more occurrences.
|
|
252
|
+
</li><li>
|
|
253
|
+
All block elements are separated by line boundaries.
|
|
254
|
+
</li><li>
|
|
255
|
+
<code class="literal">BlockId</code>, <code class="literal">AttributeEntry</code> and <code class="literal">AttributeList</code> block elements (not
|
|
256
|
+
shown) can occur almost anywhere.
|
|
257
|
+
</li><li>
|
|
258
|
+
There are a number of document type and backend specific
|
|
259
|
+
restrictions imposed on the block syntax.
|
|
260
|
+
</li><li>
|
|
261
|
+
The following elements cannot contain blank lines: Header, Title,
|
|
262
|
+
Paragraph, ItemText.
|
|
263
|
+
</li><li>
|
|
264
|
+
A ListParagraph is a Paragraph with its <span class="emphasis"><em>listelement</em></span> option set.
|
|
265
|
+
</li><li>
|
|
266
|
+
A ListContinuation is a <a class="link" href="#X15" title="13.6. List Item Continuation">list continuation element</a>.
|
|
267
|
+
</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
|
|
268
|
+
document and must begin with a document <a class="link" href="#X17" title="8. Titles">title</a>. Optional Author
|
|
269
|
+
and Revision lines immediately follow the title. The header can be
|
|
270
|
+
preceded by a CommentBlock or comment lines.</p><p>The author line contains the author’s name optionally followed by the
|
|
271
|
+
author’s email address. The author’s name consists of a first name
|
|
272
|
+
followed by optional middle and last names separated by white space.
|
|
273
|
+
Multi-word first, middle and last names can be entered in the header
|
|
274
|
+
author line using the underscore as a word separator. The email
|
|
275
|
+
address comes last and must be enclosed in angle <> brackets. Author
|
|
276
|
+
names cannot contain angle <> bracket characters.</p><p>The optional document header revision line should immediately follow
|
|
277
|
+
the author line. The revision line can be one of two formats:</p><div class="orderedlist"><ol type="1"><li><p>
|
|
278
|
+
An alphanumeric document revision number followed by a date:
|
|
279
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
280
|
+
The revision number and date must be separated by a comma.
|
|
281
|
+
</li><li>
|
|
282
|
+
The revision number is optional but must contain at least one
|
|
283
|
+
numeric character.
|
|
284
|
+
</li><li>
|
|
285
|
+
Any non-numeric characters preceding the first numeric character
|
|
286
|
+
will be dropped.
|
|
287
|
+
</li></ul></div></li><li>
|
|
288
|
+
An RCS/CSV/SVN $Id$ marker.
|
|
289
|
+
</li></ol></div><p>The document heading is separated from the remainder of the document
|
|
290
|
+
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
|
|
291
|
+
====================================
|
|
292
|
+
Stuart Rackham <srackham@gmail.com>
|
|
293
|
+
v2.0, February 2003</pre><p>You can override or set header parameters by passing <span class="emphasis"><em>revision</em></span>,
|
|
294
|
+
<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
|
|
295
|
+
<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>)
|
|
296
|
+
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
|
|
297
|
+
header template with <a class="link" href="#X18" title="23. 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
|
|
298
|
+
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
|
|
299
|
+
documents are allowed to contain level 0 sections). Section levels are
|
|
300
|
+
delineated by the section <a class="link" href="#X17" title="8. Titles">titles</a>.</p><p>Sections are translated using configuration file markup templates. To
|
|
301
|
+
determine which configuration file template to use <span class="emphasis"><em>AsciiDoc</em></span> first
|
|
302
|
+
searches for special section titles in the <a class="link" href="#X16" title="5.4.1. Special Sections"><code class="literal">[specialsections]</code></a>
|
|
303
|
+
configuration entries, if not found it uses the <code class="literal">[sect<level>]</code>
|
|
304
|
+
template.</p><p>The <code class="literal">-n</code> (<code class="literal">--section-numbers</code>) command-line option auto-numbers HTML
|
|
305
|
+
outputs (DocBook line numbering is handled automatically by the
|
|
306
|
+
DocBook toolchain commands).</p><p>Section IDs are auto-generated from section titles if the <code class="literal">sectids</code>
|
|
307
|
+
attribute is defined (the default behavior). The primary purpose of
|
|
308
|
+
this feature is to ensure persistence of table of contents links:
|
|
309
|
+
missing section IDs are generated dynamically by the JavaScript TOC
|
|
310
|
+
generator <span class="strong"><strong>after</strong></span> the page is loaded. This means, for example, that if
|
|
311
|
+
you go to a bookmarked dynamically generated TOC address the page will
|
|
312
|
+
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>
|
|
313
|
+
Replace all non-alphanumeric title characters with underscores.
|
|
314
|
+
</li><li>
|
|
315
|
+
Strip leading or trailing underscores.
|
|
316
|
+
</li><li>
|
|
317
|
+
Convert to lowercase.
|
|
318
|
+
</li><li>
|
|
319
|
+
Prepend the <code class="literal">idprefix</code> attribute (so there’s no possibility of name
|
|
320
|
+
clashes with existing document IDs). Prepend an underscore if the
|
|
321
|
+
<code class="literal">idprefix</code> attribute is not defined.
|
|
322
|
+
</li><li>
|
|
323
|
+
A numbered suffix (<code class="literal">_2</code>, <code class="literal">_3</code> …) is added if a same named
|
|
324
|
+
auto-generated section ID exists.
|
|
325
|
+
</li></ul></div><p>For example the title <span class="emphasis"><em>Jim’s House</em></span> would generate the ID
|
|
326
|
+
<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
|
|
327
|
+
frontmatter and backmatter sections — for example: preface,
|
|
328
|
+
bibliography, table of contents, index.</p><p>The <span class="emphasis"><em>AsciiDoc</em></span> configuration file <code class="literal">[specialsections]</code> section specifies
|
|
329
|
+
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
|
|
330
|
+
a configuration file markup template section. If the <code class="literal"><pattern></code>
|
|
331
|
+
matches an <span class="emphasis"><em>AsciiDoc</em></span> document section title then the backend output is
|
|
332
|
+
marked up using the <code class="literal"><name></code> markup template (instead of the default
|
|
333
|
+
<code class="literal">sect<level></code> section template). The {title} attribute value is set
|
|
334
|
+
to the value of the matched regular expression group named <span class="emphasis"><em>title</em></span>, if
|
|
335
|
+
there is no <span class="emphasis"><em>title</em></span> group {title} defaults to the whole of the
|
|
336
|
+
<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
|
|
337
|
+
titles:</p><pre class="literallayout">Preface (book documents only)
|
|
338
|
+
Abstract (article documents only)
|
|
339
|
+
Dedication (book documents only)
|
|
340
|
+
Glossary
|
|
341
|
+
Bibliography|References
|
|
342
|
+
Colophon (book documents only)
|
|
343
|
+
Index
|
|
344
|
+
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 class="link" href="#X34">Inline document elements</a> are used to markup character
|
|
345
|
+
formatting and various types of text substitution. Inline elements and
|
|
346
|
+
inline element syntax is defined in the <code class="literal">asciidoc(1)</code> configuration
|
|
347
|
+
files.</p><p>Here is a list of <span class="emphasis"><em>AsciiDoc</em></span> inline elements in the (default) order in
|
|
348
|
+
which they are processed:</p><div class="variablelist"><dl><dt><span class="term">
|
|
349
|
+
Special characters
|
|
350
|
+
</span></dt><dd>
|
|
351
|
+
These character sequences escape special characters used by
|
|
352
|
+
the backend markup (typically "<", ">", and "&"). See
|
|
353
|
+
<code class="literal">[specialcharacters]</code> configuration file sections.
|
|
354
|
+
</dd><dt><span class="term">
|
|
355
|
+
Quotes
|
|
356
|
+
</span></dt><dd>
|
|
357
|
+
Characters that markup words and phrases; usually for
|
|
358
|
+
character formatting. See <code class="literal">[quotes]</code> configuration file
|
|
359
|
+
sections.
|
|
360
|
+
</dd><dt><span class="term">
|
|
361
|
+
Special Words
|
|
362
|
+
</span></dt><dd>
|
|
363
|
+
Word or word phrase patterns singled out for markup without
|
|
364
|
+
the need for further annotation. See <code class="literal">[specialwords]</code>
|
|
365
|
+
configuration file sections.
|
|
366
|
+
</dd><dt><span class="term">
|
|
367
|
+
Replacements
|
|
368
|
+
</span></dt><dd>
|
|
369
|
+
Each Replacement defines a word or word phrase pattern to
|
|
370
|
+
search for along with corresponding replacement text. See
|
|
371
|
+
<code class="literal">[replacements]</code> configuration file sections.
|
|
372
|
+
</dd><dt><span class="term">
|
|
373
|
+
Attributes
|
|
374
|
+
</span></dt><dd>
|
|
375
|
+
Document attribute names enclosed in braces (attribute
|
|
376
|
+
references) are replaced by the corresponding attribute value.
|
|
377
|
+
</dd><dt><span class="term">
|
|
378
|
+
Inline Macros
|
|
379
|
+
</span></dt><dd>
|
|
380
|
+
Inline macros are replaced by the contents of parametrized
|
|
381
|
+
configuration file sections.
|
|
382
|
+
</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>
|
|
383
|
+
The document <span class="emphasis"><em>Header</em></span> is parsed, header parameter values are
|
|
384
|
+
substituted into the configuration file <code class="literal">[header]</code> template section
|
|
385
|
+
which is then written to the output file.
|
|
386
|
+
</li><li>
|
|
387
|
+
Each document <span class="emphasis"><em>Section</em></span> is processed and its constituent elements
|
|
388
|
+
translated to the output file.
|
|
389
|
+
</li><li>
|
|
390
|
+
The configuration file <code class="literal">[footer]</code> template section is substituted
|
|
391
|
+
and written to the output file.
|
|
392
|
+
</li></ol></div><p>When a block element is encountered <code class="literal">asciidoc(1)</code> determines the type of
|
|
393
|
+
block by checking in the following order (first to last): (section)
|
|
394
|
+
Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
|
|
395
|
+
AttributeLists, BlockTitles, Paragraphs.</p><p>The default paragraph definition <code class="literal">[paradef-default]</code> is last element
|
|
396
|
+
to be checked.</p><p>Knowing the parsing order will help you devise unambiguous macro, list
|
|
397
|
+
and block syntax rules.</p><p>Inline substitutions within block elements are performed in the
|
|
398
|
+
following default order:</p><div class="orderedlist"><ol type="1"><li>
|
|
399
|
+
Special characters
|
|
400
|
+
</li><li>
|
|
401
|
+
Quotes
|
|
402
|
+
</li><li>
|
|
403
|
+
Special words
|
|
404
|
+
</li><li>
|
|
405
|
+
Replacements
|
|
406
|
+
</li><li>
|
|
407
|
+
Attributes
|
|
408
|
+
</li><li>
|
|
409
|
+
Inline Macros
|
|
410
|
+
</li><li>
|
|
411
|
+
Replacements2
|
|
412
|
+
</li></ol></div><p>The substitutions and substitution order performed on
|
|
413
|
+
Title, Paragraph and DelimitedBlock elements is determined by
|
|
414
|
+
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
|
|
415
|
+
quote characters:</p><div class="variablelist"><dl><dt><span class="term">
|
|
416
|
+
<span class="emphasis"><em>Emphasized text</em></span>
|
|
417
|
+
</span></dt><dd>
|
|
418
|
+
Word phrases 'enclosed in single quote characters' (acute
|
|
419
|
+
accents) or _underline characters_ are emphasized.
|
|
420
|
+
</dd><dt><span class="term">
|
|
421
|
+
<span class="strong"><strong>Strong text</strong></span>
|
|
422
|
+
</span></dt><dd>
|
|
423
|
+
Word phrases *enclosed in asterisk characters* are rendered
|
|
424
|
+
in a strong font (usually bold).
|
|
425
|
+
</dd><dt><span class="term">
|
|
426
|
+
<code class="literal">Monospaced text</code>
|
|
427
|
+
</span></dt><dd>
|
|
428
|
+
Word phrases `enclosed in backtick characters` (grave
|
|
429
|
+
accents) or +plus characters+ are rendered in a monospaced
|
|
430
|
+
font.
|
|
431
|
+
</dd><dt><span class="term">
|
|
432
|
+
‘Single quoted text’
|
|
433
|
+
</span></dt><dd>
|
|
434
|
+
Phrases enclosed with a `single grave accent to the left and
|
|
435
|
+
a single acute accent to the right' are rendered in single
|
|
436
|
+
quotation marks.
|
|
437
|
+
</dd><dt><span class="term">
|
|
438
|
+
“Double quoted text”
|
|
439
|
+
</span></dt><dd>
|
|
440
|
+
Phrases enclosed with ``two grave accents to the left and
|
|
441
|
+
two acute accents to the right'' are rendered in quotation
|
|
442
|
+
marks.
|
|
443
|
+
</dd><dt><span class="term">
|
|
444
|
+
Unquoted text
|
|
445
|
+
</span></dt><dd>
|
|
446
|
+
Placing #hashes around text# does nothing, it is a mechanism
|
|
447
|
+
to allow inline attributes to be applied to otherwise
|
|
448
|
+
unformatted text (see example below).
|
|
449
|
+
</dd></dl></div><p>The alternative underline and plus characters, while marginally less
|
|
450
|
+
readable, are arguably a better choice than the backtick and
|
|
451
|
+
apostrophe characters as they are not normally used for, and so not
|
|
452
|
+
confused with, punctuation.</p><p>Quoted text can be prefixed with an <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a>. Currently
|
|
453
|
+
the only use made of this feature is to allow the font color,
|
|
454
|
+
background color and size to be specified (XHTML/HTML only, not
|
|
455
|
+
DocBook) using the first three positional attribute arguments. The
|
|
456
|
+
first argument is the text color; the second the background color; the
|
|
457
|
+
third is the font size. Colors are valid CSS colors and the font size
|
|
458
|
+
is a number which treated as em units. Here are some examples:</p><pre class="screen">[red]#Red text#.
|
|
459
|
+
[,yellow]*bold text on a yellow background*.
|
|
460
|
+
[blue,#b0e0e6]+Monospaced blue text on a light blue background+
|
|
461
|
+
[,,2]#Double sized text#.</pre><p>New quotes can be defined by editing <code class="literal">asciidoc(1)</code> configuration files.
|
|
462
|
+
See the <a class="link" href="#X7" title="21. Configuration Files">Configuration Files</a> section for details.</p><div class="itemizedlist"><p class="title"><b>Quoted text behavior</b></p><ul type="disc"><li>
|
|
463
|
+
Quoting cannot be overlapped.
|
|
464
|
+
</li><li>
|
|
465
|
+
Different quoting types can be nested.
|
|
466
|
+
</li><li>
|
|
467
|
+
To suppress quoted text formatting place a backslash character
|
|
468
|
+
immediately in front of the leading quote character(s). In the case
|
|
469
|
+
of ambiguity between escaped and non-escaped text you will need to
|
|
470
|
+
escape both leading and trailing quotes, in the case of
|
|
471
|
+
multi-character quotes you may even need to escape individual
|
|
472
|
+
characters.
|
|
473
|
+
</li><li>
|
|
474
|
+
A configuration file <code class="literal">[quotes]</code> entry can be subsequently undefined
|
|
475
|
+
by setting it to a blank value.
|
|
476
|
+
</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
|
|
477
|
+
or a word. These are the most common type of quote and are the ones
|
|
478
|
+
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
|
|
479
|
+
anywhere within inline text. For consistency and to make them easier
|
|
480
|
+
to remember unconstrained quotes are double-ups of the <code class="literal">_</code>, <code class="literal">*</code>, <code class="literal">+</code>
|
|
481
|
+
and <code class="literal">#</code> constrained quotes:</p><pre class="literallayout">__unconstrained emphasized text__
|
|
482
|
+
**unconstrained strong text**
|
|
483
|
+
++unconstrained monospaced text++
|
|
484
|
+
##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
|
|
485
|
+
double-escaped (because of their similarity to the single character
|
|
486
|
+
constrained quotes) — here’s how to escape the previous example:</p><pre class="literallayout">\*\*F**ile Open...</pre></td></tr></table></div></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_superscripts_and_subscripts"></a>7.2. Superscripts and Subscripts</h3></div></div></div><p>Put ^carets on either^ side of the text to be superscripted, put
|
|
487
|
+
~tildes on either side~ of text to be subscripted. For example, the
|
|
488
|
+
following line:</p><pre class="literallayout">e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
|
|
489
|
+
and ~some sub text~</pre><p>Is rendered like:</p><p>e<sup>πi</sup>+1 = 0. H<sub>2</sub>O and x<sup>10</sup>. Some <sup>super text</sup>
|
|
490
|
+
and <sub>some sub text</sub></p><p>Superscripts and subscripts are implemented as <a class="link" href="#X52" title="7.1.1. Constrained and Unconstrained Quotes">unconstrained quotes</a> so they can be escaped with a leading backslash and prefixed
|
|
491
|
+
with with an attribute list.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_line_breaks"></a>7.3. Line Breaks</h3></div></div></div><p>A plus character preceded by at least one space character at the end
|
|
492
|
+
of a non-blank line forces a line break. It generates a line break
|
|
493
|
+
(<code class="literal">br</code>) tag for HTML outputs and a custom XML <code class="literal">asciidoc-br</code> processing
|
|
494
|
+
instruction for DocBook outputs. The <code class="literal">asciidoc-br</code> processing
|
|
495
|
+
instruction is handled by <a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> if you use FOP.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_page_breaks"></a>7.4. Page Breaks</h3></div></div></div><p>A line of three or more less-than (<code class="literal"><<<</code>) characters will generate a
|
|
496
|
+
hard page break in DocBook and printed HTML outputs. It uses the CSS
|
|
497
|
+
<code class="literal">page-break-after</code> property for HTML outputs and a custom XML
|
|
498
|
+
<code class="literal">asciidoc-pagebreak</code> processing instruction for DocBook outputs. The
|
|
499
|
+
<code class="literal">asciidoc-pagebreak</code> processing instruction is handled by
|
|
500
|
+
<a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> if you use FOP. Hard page breaks are sometimes handy
|
|
501
|
+
but as a general rule you should let your page processor generate page
|
|
502
|
+
breaks for you.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_rulers"></a>7.5. Rulers</h3></div></div></div><p>A line of three or more apostrophe characters will generate a ruler
|
|
503
|
+
line. It generates a ruler (<code class="literal">hr</code>) tag for HTML outputs and a custom XML
|
|
504
|
+
<code class="literal">asciidoc-hr</code> processing instruction for DocBook outputs. The
|
|
505
|
+
<code class="literal">asciidoc-hr</code> processing instruction is handled by <a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> if
|
|
506
|
+
you use FOP.</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
|
|
507
|
+
expansion is set with the <span class="emphasis"><em>tabsize</em></span> entry in the configuration file
|
|
508
|
+
<code class="literal">[miscellaneous]</code> section and can be overridden in included files by
|
|
509
|
+
setting a <span class="emphasis"><em>tabsize</em></span> attribute in the <code class="literal">include</code> macro’s attribute list.
|
|
510
|
+
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,
|
|
511
|
+
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>
|
|
512
|
+
configuration:</p><pre class="literallayout">(C) copyright, (TM) trademark, (R) registered trademark,
|
|
513
|
+
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
|
|
514
|
+
double arrow, <= left double arrow.</pre><p>Which are rendered as:</p><p>© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right
|
|
515
|
+
double arrow, ⇐ left double arrow.</p><p>You can also include arbitrary entity references in the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
516
|
+
source. Examples:</p><pre class="literallayout">&#x278a; &#182;</pre><p>renders:</p><p>➊ ¶</p><p>To render a replacement literally escape it with a leading back-slash.</p><p>The <a class="link" href="#X7" title="21. Configuration Files">Configuration Files</a> section explains how to configure your
|
|
517
|
+
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
|
|
518
|
+
automatically marked up without having to be explicitly notated.</p><p>The <a class="link" href="#X7" title="21. Configuration Files">Configuration Files</a> section explains how to add and replace
|
|
519
|
+
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
|
|
520
|
+
left margin, and an underline. Section underlines consist a repeated
|
|
521
|
+
character pairs spanning the width of the preceding title (give or
|
|
522
|
+
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): ======================
|
|
523
|
+
Level 1: ----------------------
|
|
524
|
+
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
|
|
525
|
+
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
|
|
526
|
+
Level 4 (bottom level): ++++++++++++++++++++++</pre><p>Examples:</p><pre class="literallayout">Level One Section Title
|
|
527
|
+
-----------------------</pre><pre class="literallayout">Level 2 Subsection Title
|
|
528
|
+
~~~~~~~~~~~~~~~~~~~~~~~~</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
|
|
529
|
+
one or more equals characters (the number of equals characters
|
|
530
|
+
corresponds to the section level minus one). Here are some examples
|
|
531
|
+
(levels 2 and 3 illustrate the optional trailing equals characters
|
|
532
|
+
syntax):</p><pre class="literallayout">= Document Title (level 0) =
|
|
533
|
+
== Section title (level 1) ==
|
|
534
|
+
=== Section title (level 2) ===
|
|
535
|
+
==== Section title (level 3) ====
|
|
536
|
+
===== Section title (level 4) =====</pre><div class="itemizedlist"><p class="title"><b>Note</b></p><ul type="disc"><li>
|
|
537
|
+
One or more spaces must fall between the title and the delimiters.
|
|
538
|
+
</li><li>
|
|
539
|
+
The trailing title delimiter is optional.
|
|
540
|
+
</li><li>
|
|
541
|
+
The one-line title syntax can be changed by editing the
|
|
542
|
+
configuration file <code class="literal">[titles]</code> section <code class="literal">sect0</code>…<code class="literal">sect4</code> entries.
|
|
543
|
+
</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
|
|
544
|
+
by a title. The title is applied to the next Paragraph,
|
|
545
|
+
DelimitedBlock, List, Table or BlockMacro. For example:</p><pre class="literallayout">.Notes
|
|
546
|
+
- Note 1.
|
|
547
|
+
- Note 2.</pre><p>is rendered as:</p><div class="itemizedlist"><p class="title"><b>Notes</b></p><ul type="disc"><li>
|
|
548
|
+
Note 1.
|
|
549
|
+
</li><li>
|
|
550
|
+
Note 2.
|
|
551
|
+
</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
|
|
552
|
+
identifier enclosed in double square brackets. It is used to assign an
|
|
553
|
+
identifier to the ensuing block element for use by referring links. For
|
|
554
|
+
example:</p><pre class="literallayout">[[chapter-titles]]
|
|
555
|
+
Chapter titles can be ...</pre><p>The preceding example identifies the following paragraph so it can be
|
|
556
|
+
linked from other location, for example with
|
|
557
|
+
<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,
|
|
558
|
+
DelimitedBlock, Table and BlockMacro elements. The BlockId element is
|
|
559
|
+
really just an AttributeList with a special syntax which sets the
|
|
560
|
+
<code class="literal">{id}</code> attribute for substitution in the subsequent block’s markup
|
|
561
|
+
template.</p><p>The <span class="emphasis"><em>BlockId</em></span> element has the same syntax and serves a similar
|
|
562
|
+
function to the <a class="link" 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
|
|
563
|
+
start of a DelimitedBlock.</p><p>Paragraph markup is specified by configuration file <code class="literal">[paradef*]</code>
|
|
564
|
+
sections. <span class="emphasis"><em>AsciiDoc</em></span> ships with the following predefined paragraph
|
|
565
|
+
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
|
|
566
|
+
non-blank lines of text. The first line must start hard against the
|
|
567
|
+
left margin (no intervening white space). The processing expectation
|
|
568
|
+
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 class="link" href="#X23" title="27.1. Styles">style</a> preserves line boundaries and is
|
|
569
|
+
useful for lyrics and poems. For example:</p><pre class="screen">[verse]
|
|
570
|
+
Consul *necessitatibus* per id,
|
|
571
|
+
consetetur, eu pro everti postulant
|
|
572
|
+
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 />
|
|
573
|
+
consetetur, eu pro everti postulant<br />
|
|
574
|
+
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
|
|
575
|
+
lines of text, where the first line is indented by one or more space
|
|
576
|
+
or tab characters. Literal paragraphs are rendered verbatim in a
|
|
577
|
+
monospaced font usually without any distinguishing background or
|
|
578
|
+
border. There is no text formatting or substitutions within Literal
|
|
579
|
+
paragraphs apart from Special Characters and Callouts. For example:</p><pre class="screen"> Consul *necessitatibus* per id,
|
|
580
|
+
consetetur, eu pro everti postulant
|
|
581
|
+
homero verear ea mea, qui.</pre><p>Renders:</p><pre class="literallayout">Consul *necessitatibus* per id,
|
|
582
|
+
consetetur, eu pro everti postulant
|
|
583
|
+
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 class="link" href="#X64" title="13. Lists">lists</a> can be indented it’s possible for your
|
|
584
|
+
Literal paragraph to be misinterpreted as a list — in situations like
|
|
585
|
+
this use a <a class="link" 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
|
|
586
|
+
definitions support the corresponding DocBook admonishment elements — just write a normal paragraph but place <code class="literal">NOTE:</code>, <code class="literal">TIP:</code>, <code class="literal">IMPORTANT:</code>,
|
|
587
|
+
<code class="literal">WARNING:</code> or <code class="literal">CAUTION:</code> as the first word of the paragraph. For
|
|
588
|
+
example:</p><pre class="literallayout">NOTE: This is an example note.</pre><p>or the alternative syntax:</p><pre class="literallayout">[NOTE]
|
|
589
|
+
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
|
|
590
|
+
<a class="link" 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
|
|
591
|
+
<code class="literal">caption</code> attributes does not apply when generating DocBook output. If
|
|
592
|
+
you are going the DocBook route then the <a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> <code class="literal">--no-icons</code>
|
|
593
|
+
and <code class="literal">--icons-dir</code> options can be used to set the appropriate XSL
|
|
594
|
+
Stylesheets parameters.</p></td></tr></table></div><p>By default the <code class="literal">asciidoc(1)</code> <code class="literal">xhtml11</code> and <code class="literal">html4</code> backends generate
|
|
595
|
+
text captions instead of icon image links. To generate links to icon
|
|
596
|
+
images define the <a class="link" href="#"><code class="literal">icons</code></a> attribute, for example using the <code class="literal">-a
|
|
597
|
+
icons</code> command-line option.</p><p>The <a class="link" href="#X44" title="Note"><code class="literal">iconsdir</code></a> attribute sets the location of linked icon
|
|
598
|
+
images.</p><p>You can override the default icon image using the <code class="literal">icon</code> attribute to
|
|
599
|
+
specify the path of the linked image. For example:</p><pre class="literallayout">[icon="./images/icons/wink.png"]
|
|
600
|
+
NOTE: What lovely war.</pre><p>Use the <code class="literal">caption</code> attribute to customize the admonition captions (not
|
|
601
|
+
applicable to <code class="literal">docbook</code> backend). The following example suppresses the
|
|
602
|
+
icon image and customizes the caption of a NOTE admonition (undefining
|
|
603
|
+
the <code class="literal">icons</code> attribute with <code class="literal">icons=None</code> is only necessary if
|
|
604
|
+
<a class="link" href="#">admonition icons</a> have been enabled):</p><pre class="literallayout">[icons=None, caption="My Special Note"]
|
|
605
|
+
NOTE: This is my special note.</pre><p>This subsection also applies to <a class="link" href="#X22" title="12.9. Admonition Blocks">Admonition Blocks</a>.</p></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_delimited_blocks"></a>12. Delimited Blocks</h2></div></div></div><p>Delimited blocks are blocks of text enveloped by leading and trailing
|
|
606
|
+
delimiter lines (normally a series of four or more repeated
|
|
607
|
+
characters). The behavior of Delimited Blocks is specified by entries
|
|
608
|
+
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
|
|
609
|
+
<code class="literal">asciidoc.conf</code> configuration file in the <code class="literal">asciidoc(1)</code> program
|
|
610
|
+
directory):</p><p>Predefined delimited block underlines:</p><pre class="literallayout">CommentBlock: //////////////////////////
|
|
611
|
+
PassthroughBlock: ++++++++++++++++++++++++++
|
|
612
|
+
ListingBlock: --------------------------
|
|
613
|
+
LiteralBlock: ..........................
|
|
614
|
+
SidebarBlock: **************************
|
|
615
|
+
QuoteBlock: __________________________
|
|
616
|
+
ExampleBlock: ==========================
|
|
617
|
+
Filter blocks: ~~~~~~~~~~~~~~~~~~~~~~~~~~</pre><p>The <a class="link" href="#X56" title="28.3. Code Filter">code</a>, <a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">source</a> and <a class="link" href="#X58" title="28.5. Music Filter">music</a> filter blocks are
|
|
618
|
+
detailed in the <a class="link" href="#X59" title="28. Filters">Filters</a> section.</p><div class="table"><a id="id2531046"></a><p class="title"><b>Table 1. Default DelimitedBlock substitutions</b></p><div class="table-contents"><table summary="Default DelimitedBlock substitutions" cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"> </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Passthrough </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Listing </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Literal </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Sidebar </th><th style="border-bottom: 1px solid ; " align="center" valign="top">Quote</th></tr></thead><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Callouts</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Attributes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Inline Macros</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Quotes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Replacements</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Special chars</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="border-bottom: 1px solid ; " align="center" valign="top"><p>Yes</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>Special words</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>No</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>Yes</p></td><td style="" align="center" valign="top"><p>Yes</p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_listing_blocks"></a>12.2. Listing Blocks</h3></div></div></div><p>ListingBlocks are rendered verbatim in a monospaced font, they retain
|
|
619
|
+
line and whitespace formatting and often distinguished by a background
|
|
620
|
+
or border. There is no text formatting or substitutions within Listing
|
|
621
|
+
blocks apart from Special Characters and Callouts. Listing blocks are
|
|
622
|
+
often used for code and file listings.</p><p>Here’s an example:</p><pre class="screen">--------------------------------------
|
|
623
|
+
#include <stdio.h>
|
|
624
|
+
|
|
625
|
+
int main() {
|
|
626
|
+
printf("Hello World!\n");
|
|
627
|
+
exit(0);
|
|
628
|
+
}
|
|
629
|
+
--------------------------------------</pre><p>Which will be rendered like:</p><pre class="screen">#include <stdio.h>
|
|
630
|
+
|
|
631
|
+
int main() {
|
|
632
|
+
printf("Hello World!\n");
|
|
633
|
+
exit(0);
|
|
634
|
+
}</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
|
|
635
|
+
to indent the contents.</p><p>LiteralBlocks can be used to resolve list ambiguity. If the following
|
|
636
|
+
list was just indented it would be processed as an ordered list (not
|
|
637
|
+
an indented paragraph):</p><pre class="screen">....................
|
|
638
|
+
1. Item 1
|
|
639
|
+
2. Item 2
|
|
640
|
+
....................</pre><p>Renders:</p><pre class="literallayout">1. Item 1
|
|
641
|
+
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
|
|
642
|
+
flow of the main text. The sidebar is normally presented inside a
|
|
643
|
+
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
|
|
644
|
+
************************************************
|
|
645
|
+
Any AsciiDoc SectionBody element (apart from
|
|
646
|
+
SidebarBlocks) can be placed inside a sidebar.
|
|
647
|
+
************************************************</pre><p>Which will be rendered like:</p><div class="sidebar"><p class="title"><b>An Example Sidebar</b></p><p>Any <span class="emphasis"><em>AsciiDoc</em></span> SectionBody element (apart from
|
|
648
|
+
SidebarBlocks) can be placed inside a sidebar.</p></div><p>Apply the <span class="emphasis"><em>abstract</em></span> style to generate an abstract, for example:</p><pre class="screen">[abstract]
|
|
649
|
+
************************************************
|
|
650
|
+
In this paper we will attempt to...
|
|
651
|
+
************************************************</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X26"></a>12.5. Comment Blocks</h3></div></div></div><p>The contents of CommentBlocks are not processed; they are useful for
|
|
652
|
+
annotations and for excluding new or outdated content that you don’t
|
|
653
|
+
want displayed. Here’s and example:</p><pre class="screen">//////////////////////////////////////////
|
|
654
|
+
CommentBlock contents are not processed by
|
|
655
|
+
asciidoc(1).
|
|
656
|
+
//////////////////////////////////////////</pre><p>See also <a class="link" href="#X25" title="17.2.3. Comment Lines">Comment Lines</a>.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>System macros are executed inside comment blocks.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X76"></a>12.6. Passthrough Blocks</h3></div></div></div><p>By default the block contents is subject to attribute and macro
|
|
657
|
+
substitution, no other markup is generated. PassthroughBlock content
|
|
658
|
+
will often be backend specific. Here’s an example:</p><pre class="screen">++++++++++++++++++++++++++++++++++++++
|
|
659
|
+
<table border="1"><tr>
|
|
660
|
+
<td>Cell 1</td>
|
|
661
|
+
<td>Cell 2</td>
|
|
662
|
+
</tr></table>
|
|
663
|
+
++++++++++++++++++++++++++++++++++++++</pre><p>Use and explicit <span class="emphasis"><em>subs</em></span> attribute to control substitution. The
|
|
664
|
+
following styles can be applied to passthrough blocks:</p><div class="variablelist"><dl><dt><span class="term">
|
|
665
|
+
pass
|
|
666
|
+
</span></dt><dd>
|
|
667
|
+
By default no substitutions are performed.
|
|
668
|
+
</dd><dt><span class="term">
|
|
669
|
+
asciimath, latexmath
|
|
670
|
+
</span></dt><dd>
|
|
671
|
+
By default no substitutions are performed, the contents are rendered
|
|
672
|
+
as <a class="link" href="#X78" title="20. Mathematical Formulas">mathematical formulas</a>.
|
|
673
|
+
</dd></dl></div></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
|
|
674
|
+
styles: <span class="emphasis"><em>quote</em></span> and <span class="emphasis"><em>verse</em></span> (the first positional attribute). The
|
|
675
|
+
<span class="emphasis"><em>attribution</em></span> and <span class="emphasis"><em>citetitle</em></span> attributes (positional attributes 2 and
|
|
676
|
+
3) specify the content author and source. If no attributes are
|
|
677
|
+
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)]
|
|
678
|
+
____________________________________________________________________
|
|
679
|
+
A good notation has subtlety and suggestiveness which at times makes
|
|
680
|
+
it almost seem like a live teacher.
|
|
681
|
+
____________________________________________________________________</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
|
|
682
|
+
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">
|
|
683
|
+
Bertrand Russell
|
|
684
|
+
<em class="citetitle">The World of Mathematics (1956)</em>
|
|
685
|
+
</span></td></tr></table></div><p>The <span class="emphasis"><em>verse</em></span> style
|
|
686
|
+
retains the content’s line breaks, for example:</p><pre class="screen">[verse, William Blake, from Auguries of Innocence]
|
|
687
|
+
__________________________________________________
|
|
688
|
+
To see a world in a grain of sand,
|
|
689
|
+
And a heaven in a wild flower,
|
|
690
|
+
Hold infinity in the palm of your hand,
|
|
691
|
+
And eternity in an hour.
|
|
692
|
+
__________________________________________________</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 />
|
|
693
|
+
And a heaven in a wild flower,<br />
|
|
694
|
+
Hold infinity in the palm of your hand,<br />
|
|
695
|
+
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">
|
|
696
|
+
William Blake
|
|
697
|
+
<em class="citetitle">from Auguries of Innocence</em>
|
|
698
|
+
</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
|
|
699
|
+
for, well, examples. Example blocks can be titled by preceding them
|
|
700
|
+
with a <span class="emphasis"><em>BlockTitle</em></span>. DocBook toolchains normally number examples and
|
|
701
|
+
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
|
|
702
|
+
put any block elements apart from Titles, BlockTitles and Sidebars)
|
|
703
|
+
inside an example block. For example:</p><pre class="screen">.An example
|
|
704
|
+
=====================================================================
|
|
705
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
706
|
+
adolescens.
|
|
707
|
+
=====================================================================</pre><p>Renders:</p><div class="example"><a id="id2531785"></a><p class="title"><b>Example 1. An example</b></p><div class="example-contents"><p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
708
|
+
adolescens.</p></div></div><br class="example-break" /><p>A title prefix that can be inserted with the <code class="literal">caption</code> attribute
|
|
709
|
+
(<code class="literal">xhtml11</code> and <code class="literal">html4</code> backends). For example:</p><pre class="screen">[caption="Example 1: "]
|
|
710
|
+
.An example with a custom caption
|
|
711
|
+
=====================================================================
|
|
712
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
713
|
+
adolescens.
|
|
714
|
+
=====================================================================</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
|
|
715
|
+
<a class="link" href="#X23" title="27.1. Styles">styles</a> (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating
|
|
716
|
+
admonition blocks (admonitions containing more than just a
|
|
717
|
+
<a class="link" href="#X28" title="11.3. Admonition Paragraphs">simple paragraph</a>). Just precede the ExampleBlock with an
|
|
718
|
+
attribute list containing the admonition style name. For example:</p><pre class="screen">[NOTE]
|
|
719
|
+
.A NOTE block
|
|
720
|
+
=====================================================================
|
|
721
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
722
|
+
adolescens.
|
|
723
|
+
|
|
724
|
+
. Fusce euismod commodo velit.
|
|
725
|
+
. Vivamus fringilla mi eu lacus.
|
|
726
|
+
.. Fusce euismod commodo velit.
|
|
727
|
+
.. Vivamus fringilla mi eu lacus.
|
|
728
|
+
. Donec eget arcu bibendum
|
|
729
|
+
nunc consequat lobortis.
|
|
730
|
+
=====================================================================</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
|
|
731
|
+
adolescens.</p><div class="orderedlist"><ol type="1"><li>
|
|
732
|
+
Fusce euismod commodo velit.
|
|
733
|
+
</li><li><p>
|
|
734
|
+
Vivamus fringilla mi eu lacus.
|
|
735
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
736
|
+
Fusce euismod commodo velit.
|
|
737
|
+
</li><li>
|
|
738
|
+
Vivamus fringilla mi eu lacus.
|
|
739
|
+
</li></ol></div></li><li>
|
|
740
|
+
Donec eget arcu bibendum
|
|
741
|
+
nunc consequat lobortis.
|
|
742
|
+
</li></ol></div></td></tr></table></div><p>See also <a class="link" 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>
|
|
743
|
+
Bulleted lists. Also known as itemized or unordered lists.
|
|
744
|
+
</li><li>
|
|
745
|
+
Numbered lists. Also called ordered lists.
|
|
746
|
+
</li><li>
|
|
747
|
+
Labeled lists. Sometimes called variable or definition lists.
|
|
748
|
+
</li><li>
|
|
749
|
+
Callout lists (a list of callout annotations).
|
|
750
|
+
</li></ul></div><div class="itemizedlist"><p class="title"><b>List behavior</b></p><ul type="disc"><li>
|
|
751
|
+
List item indentation is optional and does not determine nesting,
|
|
752
|
+
indentation does however make the source more readable.
|
|
753
|
+
</li><li>
|
|
754
|
+
A nested list must use a different syntax from its parent so that
|
|
755
|
+
<code class="literal">asciidoc(1)</code> can distinguish the start of a nested list.
|
|
756
|
+
</li><li>
|
|
757
|
+
By default lists of the same type can only be nested two deep; this
|
|
758
|
+
could be increased by defining new list definitions.
|
|
759
|
+
</li><li>
|
|
760
|
+
In addition to nested lists a list item will include immediately
|
|
761
|
+
following Literal paragraphs.
|
|
762
|
+
</li><li>
|
|
763
|
+
Use <a class="link" href="#X15" title="13.6. List Item Continuation">List Item Continuation</a> to append other block elements
|
|
764
|
+
to a list item.
|
|
765
|
+
</li><li>
|
|
766
|
+
The <code class="literal">listindex</code> <a class="link" href="#X60" title="26. Intrinsic Attributes">intrinsic attribute</a> is the current list item
|
|
767
|
+
index (1..). If this attribute is not inside a list then it’s value
|
|
768
|
+
is the number of items in the most recently closed list. Useful for
|
|
769
|
+
displaying the number of items in a list.
|
|
770
|
+
</li><li>
|
|
771
|
+
You need to use <a class="link" href="#X15" title="13.6. List Item Continuation">list item continuation</a> if a nested list is
|
|
772
|
+
accompanied by an <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a>.
|
|
773
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_bulleted_and_numbered_lists"></a>13.1. Bulleted and Numbered Lists</h3></div></div></div><p>Bulleted list items start with a dash or an asterisk followed by a
|
|
774
|
+
space or tab character. Bulleted list syntaxes are:</p><pre class="literallayout">- List item.
|
|
775
|
+
* List item.</pre><p>There are two numbered list item syntaxes:</p><div class="orderedlist"><ol type="1"><li>
|
|
776
|
+
List items beginning with a single period followed by a space. The
|
|
777
|
+
period can be preceded by an optional decimal number. The default
|
|
778
|
+
numbering style is arabic (decimal).
|
|
779
|
+
</li><li><p>
|
|
780
|
+
List items beginning with two periods followed by a space. An alpha
|
|
781
|
+
character or a roman number (upper or lower case) can optionally be
|
|
782
|
+
used in place of the first period:
|
|
783
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
784
|
+
An attempt is made to set the number style based on number style
|
|
785
|
+
of the first list item.
|
|
786
|
+
</li><li>
|
|
787
|
+
The default numbering style is lowercase alpha.
|
|
788
|
+
</li></ul></div></li></ol></div><p>You can use the <span class="emphasis"><em>style</em></span> attribute to specify an alternative numbering
|
|
789
|
+
style. The numbered list style can be set to one of the following
|
|
790
|
+
values: <span class="emphasis"><em>arabic</em></span>, <span class="emphasis"><em>loweralpha</em></span>, <span class="emphasis"><em>upperalpha</em></span>, <span class="emphasis"><em>lowerroman</em></span>,
|
|
791
|
+
<span class="emphasis"><em>upperroman</em></span>.</p><p>Examples of numbered list items:</p><pre class="literallayout">. Arabic (decimal) numbered list item.
|
|
792
|
+
1. Arabic (decimal) numbered list item.
|
|
793
|
+
.. Lower case letter numbered list item.
|
|
794
|
+
a. Lower case letter numbered list item.
|
|
795
|
+
A. Upper case letter numbered list item.
|
|
796
|
+
iii. Lower case roman numbered list item.
|
|
797
|
+
IX. Upper case roman numbered list item.</pre><p>Here are some examples of bulleted and numbered lists:</p><pre class="screen">- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
798
|
+
* Fusce euismod commodo velit.
|
|
799
|
+
* Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
800
|
+
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
801
|
+
vel.
|
|
802
|
+
* Vivamus fringilla mi eu lacus.
|
|
803
|
+
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
804
|
+
- Nulla porttitor vulputate libero.
|
|
805
|
+
. Fusce euismod commodo velit.
|
|
806
|
+
. Vivamus fringilla mi eu lacus.
|
|
807
|
+
[upperroman]
|
|
808
|
+
.. Fusce euismod commodo velit.
|
|
809
|
+
.. Vivamus fringilla mi eu lacus.
|
|
810
|
+
. Donec eget arcu bibendum nunc consequat lobortis.
|
|
811
|
+
- Praesent eget purus quis magna eleifend eleifend.
|
|
812
|
+
1. Fusce euismod commodo velit.
|
|
813
|
+
a. Fusce euismod commodo velit.
|
|
814
|
+
b. Vivamus fringilla mi eu lacus.
|
|
815
|
+
c. Donec eget arcu bibendum nunc consequat lobortis.
|
|
816
|
+
2. Vivamus fringilla mi eu lacus.
|
|
817
|
+
.. Fusce euismod commodo velit.
|
|
818
|
+
.. Vivamus fringilla mi eu lacus.
|
|
819
|
+
3. Donec eget arcu bibendum nunc consequat lobortis.
|
|
820
|
+
4. Nam fermentum mattis ante.</pre><p>Which render as:</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
821
|
+
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
822
|
+
</p><div class="itemizedlist"><ul type="circle"><li>
|
|
823
|
+
Fusce euismod commodo velit.
|
|
824
|
+
</li><li>
|
|
825
|
+
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
|
|
826
|
+
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
|
|
827
|
+
vel.
|
|
828
|
+
</li><li>
|
|
829
|
+
Vivamus fringilla mi eu lacus.
|
|
830
|
+
</li><li>
|
|
831
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
832
|
+
</li></ul></div></li><li><p>
|
|
833
|
+
Nulla porttitor vulputate libero.
|
|
834
|
+
</p><div class="orderedlist"><ol type="1"><li>
|
|
835
|
+
Fusce euismod commodo velit.
|
|
836
|
+
</li><li><p>
|
|
837
|
+
Vivamus fringilla mi eu lacus.
|
|
838
|
+
</p><div class="orderedlist"><ol type="I"><li>
|
|
839
|
+
Fusce euismod commodo velit.
|
|
840
|
+
</li><li>
|
|
841
|
+
Vivamus fringilla mi eu lacus.
|
|
842
|
+
</li></ol></div></li><li>
|
|
843
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
844
|
+
</li></ol></div></li><li><p>
|
|
845
|
+
Praesent eget purus quis magna eleifend eleifend.
|
|
846
|
+
</p><div class="orderedlist"><ol type="1"><li><p>
|
|
847
|
+
Fusce euismod commodo velit.
|
|
848
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
849
|
+
Fusce euismod commodo velit.
|
|
850
|
+
</li><li>
|
|
851
|
+
Vivamus fringilla mi eu lacus.
|
|
852
|
+
</li><li>
|
|
853
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
854
|
+
</li></ol></div></li><li><p>
|
|
855
|
+
Vivamus fringilla mi eu lacus.
|
|
856
|
+
</p><div class="orderedlist"><ol type="a"><li>
|
|
857
|
+
Fusce euismod commodo velit.
|
|
858
|
+
</li><li>
|
|
859
|
+
Vivamus fringilla mi eu lacus.
|
|
860
|
+
</li></ol></div></li><li>
|
|
861
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
862
|
+
</li><li>
|
|
863
|
+
Nam fermentum mattis ante.
|
|
864
|
+
</li></ol></div></li></ul></div><p>A predefined <span class="emphasis"><em>compact</em></span> option is available to bulleted and numbered
|
|
865
|
+
lists — this translates to the DocBook <span class="emphasis"><em>spacing="compact"</em></span> lists
|
|
866
|
+
attribute which may or may not be processed by the DocBook toolchain.
|
|
867
|
+
Example:</p><pre class="literallayout">[options="compact"]
|
|
868
|
+
- Compact list item.
|
|
869
|
+
- Another compact list item.</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>To apply the <span class="emphasis"><em>compact</em></span> option globally define a document-wide
|
|
870
|
+
<span class="emphasis"><em>compact-option</em></span> attribute, e.g. using the <code class="literal">-a compact-option</code>
|
|
871
|
+
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="_labeled_lists"></a>13.2. Labeled Lists</h3></div></div></div><p>Labeled list items consist of one or more text labels followed the
|
|
872
|
+
text of the list item.</p><p>An item label begins a line with an alphanumeric character hard
|
|
873
|
+
against the left margin and ends with a double colon <code class="literal">::</code> or
|
|
874
|
+
semi-colon <code class="literal">;;</code>. A list item can have multiple labels, one per line.</p><p>The list item text consists of one or more lines of text starting
|
|
875
|
+
after the last label (either on the same line or a new line) and can
|
|
876
|
+
be followed by nested List or ListParagraph elements. Item text can be
|
|
877
|
+
optionally indented.</p><p>Here are some examples:</p><pre class="screen">In::
|
|
878
|
+
Lorem::
|
|
879
|
+
Fusce euismod commodo velit.
|
|
880
|
+
|
|
881
|
+
Fusce euismod commodo velit.
|
|
882
|
+
|
|
883
|
+
Ipsum:: Vivamus fringilla mi eu lacus.
|
|
884
|
+
* Vivamus fringilla mi eu lacus.
|
|
885
|
+
* Donec eget arcu bibendum nunc consequat lobortis.
|
|
886
|
+
Dolor::
|
|
887
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
888
|
+
Suspendisse;;
|
|
889
|
+
A massa id sem aliquam auctor.
|
|
890
|
+
Morbi;;
|
|
891
|
+
Pretium nulla vel lorem.
|
|
892
|
+
In;;
|
|
893
|
+
Dictum mauris in urna.</pre><p>Which render as:</p><div class="variablelist"><dl><dt><span class="term">
|
|
894
|
+
In
|
|
895
|
+
, </span><span class="term">
|
|
896
|
+
Lorem
|
|
897
|
+
</span></dt><dd><p>
|
|
898
|
+
Fusce euismod commodo velit.
|
|
899
|
+
</p><pre class="literallayout">Fusce euismod commodo velit.</pre></dd><dt><span class="term">
|
|
900
|
+
Ipsum
|
|
901
|
+
</span></dt><dd><p>
|
|
902
|
+
Vivamus fringilla mi eu lacus.
|
|
903
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
904
|
+
Vivamus fringilla mi eu lacus.
|
|
905
|
+
</li><li>
|
|
906
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
907
|
+
</li></ul></div></dd><dt><span class="term">
|
|
908
|
+
Dolor
|
|
909
|
+
</span></dt><dd><p>
|
|
910
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
911
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
912
|
+
Suspendisse
|
|
913
|
+
</span></dt><dd>
|
|
914
|
+
A massa id sem aliquam auctor.
|
|
915
|
+
</dd><dt><span class="term">
|
|
916
|
+
Morbi
|
|
917
|
+
</span></dt><dd>
|
|
918
|
+
Pretium nulla vel lorem.
|
|
919
|
+
</dd><dt><span class="term">
|
|
920
|
+
In
|
|
921
|
+
</span></dt><dd>
|
|
922
|
+
Dictum mauris in urna.
|
|
923
|
+
</dd></dl></div></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_horizontal_labeled_list_style"></a>13.2.1. Horizontal labeled list style</h4></div></div></div><p>The <span class="emphasis"><em>horizontal</em></span> labeled list style places the list text side-by-side
|
|
924
|
+
with the label instead of under the label. Here is an example:</p><pre class="screen">[horizontal]
|
|
925
|
+
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
|
|
926
|
+
labitur dolorum an. Est ne magna primis adolescens.
|
|
927
|
+
|
|
928
|
+
Fusce euismod commodo velit.
|
|
929
|
+
|
|
930
|
+
*Ipsum*:: Vivamus fringilla mi eu lacus.
|
|
931
|
+
- Vivamus fringilla mi eu lacus.
|
|
932
|
+
- Donec eget arcu bibendum nunc consequat lobortis.
|
|
933
|
+
|
|
934
|
+
*Dolor*::
|
|
935
|
+
- Vivamus fringilla mi eu lacus.
|
|
936
|
+
- Donec eget arcu bibendum nunc consequat lobortis.</pre><p>Which render as:</p><div class="horizontal"><table cellpadding="4px" style="border: none;"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td style="" valign="top">
|
|
937
|
+
<p>
|
|
938
|
+
<span class="strong"><strong>Lorem</strong></span>
|
|
939
|
+
</p>
|
|
940
|
+
</td><td style="" valign="top">
|
|
941
|
+
<p>
|
|
942
|
+
Fusce euismod commodo velit. Qui in magna commodo, est
|
|
943
|
+
labitur dolorum an. Est ne magna primis adolescens.
|
|
944
|
+
</p>
|
|
945
|
+
<pre class="literallayout">Fusce euismod commodo velit.</pre>
|
|
946
|
+
</td></tr><tr><td style="" valign="top">
|
|
947
|
+
<p>
|
|
948
|
+
<span class="strong"><strong>Ipsum</strong></span>
|
|
949
|
+
</p>
|
|
950
|
+
</td><td style="" valign="top">
|
|
951
|
+
<p>
|
|
952
|
+
Vivamus fringilla mi eu lacus.
|
|
953
|
+
</p>
|
|
954
|
+
<div class="itemizedlist"><ul type="disc"><li>
|
|
955
|
+
Vivamus fringilla mi eu lacus.
|
|
956
|
+
</li><li>
|
|
957
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
958
|
+
</li></ul></div>
|
|
959
|
+
</td></tr><tr><td style="" valign="top">
|
|
960
|
+
<p>
|
|
961
|
+
<span class="strong"><strong>Dolor</strong></span>
|
|
962
|
+
</p>
|
|
963
|
+
</td><td style="" valign="top">
|
|
964
|
+
<div class="itemizedlist"><ul type="disc"><li>
|
|
965
|
+
Vivamus fringilla mi eu lacus.
|
|
966
|
+
</li><li>
|
|
967
|
+
Donec eget arcu bibendum nunc consequat lobortis.
|
|
968
|
+
</li></ul></div>
|
|
969
|
+
</td></tr></tbody></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"><div class="itemizedlist"><ul type="disc"><li>
|
|
970
|
+
Current PDF toolchains do not make a good job of determining
|
|
971
|
+
the relative column widths for horizontal labeled lists.
|
|
972
|
+
</li><li>
|
|
973
|
+
If you are generating DocBook markup then horizontal labeled lists
|
|
974
|
+
should not be nested because the <span class="emphasis"><em>DocBook XML V4.2</em></span> DTD does not
|
|
975
|
+
permit nested informal tables (although <a class="link" href="#">DocBook XSL Stylesheets</a> and <a class="link" href="#">dblatex</a> process them correctly).
|
|
976
|
+
</li><li>
|
|
977
|
+
The label width can be set as a percentage of the total width by
|
|
978
|
+
setting the <span class="emphasis"><em>width</em></span> attribute e.g. <code class="literal">width="10%"</code>
|
|
979
|
+
</li></ul></div></td></tr></table></div></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.3. Question and Answer Lists</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes pre-configured with a <span class="emphasis"><em>qanda</em></span> style labeled list for generating
|
|
980
|
+
DocBook question and answer (Q&A) lists. Example:</p><pre class="screen">[qanda]
|
|
981
|
+
Question one::
|
|
982
|
+
Answer one.
|
|
983
|
+
Question two::
|
|
984
|
+
Answer two.</pre><p>Renders:</p><div class="qandaset"><dl><dt>13.3.1. <a href="#id2532998">
|
|
985
|
+
Question one
|
|
986
|
+
</a></dt><dt>13.3.2. <a href="#id2533015">
|
|
987
|
+
Question two
|
|
988
|
+
</a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%" /><tbody><tr class="question"><td align="left" valign="top"><a id="id2532998"></a><a id="id2533000"></a><p><b>13.3.1.</b></p></td><td align="left" valign="top"><p>
|
|
989
|
+
Question one
|
|
990
|
+
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
|
|
991
|
+
Answer one.
|
|
992
|
+
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="id2533015"></a><a id="id2533017"></a><p><b>13.3.2.</b></p></td><td align="left" valign="top"><p>
|
|
993
|
+
Question two
|
|
994
|
+
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
|
|
995
|
+
Answer two.
|
|
996
|
+
</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.4. Glossary Lists</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes pre-configured with a <span class="emphasis"><em>glossary</em></span> style labeled list for
|
|
997
|
+
generating DocBook glossary lists. Example:</p><pre class="screen">[glossary]
|
|
998
|
+
A glossary term::
|
|
999
|
+
The corresponding definition.
|
|
1000
|
+
A second glossary term::
|
|
1001
|
+
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
|
|
1002
|
+
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
|
|
1003
|
+
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.5. Bibliography Lists</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes with a predefined <span class="emphasis"><em>bibliography</em></span> bulleted list style
|
|
1004
|
+
generating DocBook bibliography entries. Example:</p><pre class="screen">[bibliography]
|
|
1005
|
+
- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
|
|
1006
|
+
Programming'. Addison-Wesley. ISBN 0-13-142901-9.
|
|
1007
|
+
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
|
|
1008
|
+
'DocBook - The Definitive Guide'. O'Reilly & Associates.
|
|
1009
|
+
1999. ISBN 1-56592-580-7.</pre><p>The <code class="literal">[[[<reference>]]]</code> syntax is a bibliography entry anchor, it
|
|
1010
|
+
generates an anchor named <code class="literal"><reference></code> and additionally displays
|
|
1011
|
+
<code class="literal">[<reference>]</code> at the anchor position. For example <code class="literal">[[[taoup]]]</code>
|
|
1012
|
+
generates an anchor named <code class="literal">taoup</code> that displays <code class="literal">[taoup]</code> at the
|
|
1013
|
+
anchor position. Cite the reference from elsewhere your document using
|
|
1014
|
+
<code class="literal"><<taoup>></code>, this displays a hyperlink (<code class="literal">[taoup]</code>) to the
|
|
1015
|
+
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
|
|
1016
|
+
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
|
|
1017
|
+
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.6. List Item Continuation</h3></div></div></div><p>To include subsequent block elements in list items (in addition to
|
|
1018
|
+
implicitly included nested lists and Literal paragraphs) place a
|
|
1019
|
+
separator line containing a single plus character between the list
|
|
1020
|
+
item and the ensuing list continuation element. Multiple block
|
|
1021
|
+
elements (excluding section Titles and BlockTitles) may be included in
|
|
1022
|
+
a list item using this technique. Note that the continued items must
|
|
1023
|
+
be indented as they normally would be outside of the list.</p><p>You also need to use list item continuation if a nested list is
|
|
1024
|
+
accompanied by an <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a>.</p><p>Here’s an example of list item continuation:</p><pre class="screen">1. List item one.
|
|
1025
|
+
+
|
|
1026
|
+
List item one continued with a second paragraph followed by an
|
|
1027
|
+
Indented block.
|
|
1028
|
+
+
|
|
1029
|
+
.................
|
|
1030
|
+
$ ls *.sh
|
|
1031
|
+
$ mv *.sh ~/tmp
|
|
1032
|
+
.................
|
|
1033
|
+
+
|
|
1034
|
+
List item one continued with a third paragraph.
|
|
1035
|
+
|
|
1036
|
+
2. List item two.
|
|
1037
|
+
|
|
1038
|
+
List item two literal paragraph (no continuation required).
|
|
1039
|
+
|
|
1040
|
+
- Nested list (item one).
|
|
1041
|
+
|
|
1042
|
+
Nested list literal paragraph (no continuation required).
|
|
1043
|
+
+
|
|
1044
|
+
Nested list appended list item one paragraph
|
|
1045
|
+
|
|
1046
|
+
- Nested list item two.</pre><p>Renders:</p><div class="orderedlist"><ol type="1"><li><p>
|
|
1047
|
+
List item one.
|
|
1048
|
+
</p><p>List item one continued with a second paragraph followed by a Listing
|
|
1049
|
+
block.</p><pre class="literallayout">$ ls *.sh
|
|
1050
|
+
$ mv *.sh ~/tmp</pre><p>List item one continued with a third paragraph.</p></li><li><p>
|
|
1051
|
+
List item two.
|
|
1052
|
+
</p><pre class="literallayout">List item two literal paragraph (no continuation required).</pre><div class="itemizedlist"><ul type="disc"><li><p>
|
|
1053
|
+
Nested list (item one).
|
|
1054
|
+
</p><pre class="literallayout">Nested list literal paragraph (no continuation required).</pre><p>Nested list appended list item one paragraph</p></li><li>
|
|
1055
|
+
Nested list item two.
|
|
1056
|
+
</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.7. 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>
|
|
1057
|
+
All elements between in the List Block are part of the preceding
|
|
1058
|
+
list item. In this respect the List block behaves like <a class="link" href="#X15" title="13.6. List Item Continuation">List Item Continuation</a> except that list items contained within the
|
|
1059
|
+
block do not require explicit <code class="literal">+</code> list item continuation lines:
|
|
1060
|
+
</li><li>
|
|
1061
|
+
The block delimiter is a single line containing two dashes.
|
|
1062
|
+
</li><li>
|
|
1063
|
+
Any block title or attributes are passed to the first element inside
|
|
1064
|
+
the block.
|
|
1065
|
+
</li></ul></div><p>The List Block is useful for:</p><div class="orderedlist"><ol type="1"><li>
|
|
1066
|
+
Lists with long multi-element list items.
|
|
1067
|
+
</li><li>
|
|
1068
|
+
Nesting a list within a parent list item (by default nested lists
|
|
1069
|
+
follow the preceding list item).
|
|
1070
|
+
</li></ol></div><p>Here’s an example of a nested list block:</p><pre class="screen">.Nested List Block
|
|
1071
|
+
1. List item one.
|
|
1072
|
+
+
|
|
1073
|
+
This paragraph is part of the preceding list item
|
|
1074
|
+
+
|
|
1075
|
+
--
|
|
1076
|
+
a. This list is nested and does not require explicit item continuation.
|
|
1077
|
+
|
|
1078
|
+
This paragraph is part of the preceding list item
|
|
1079
|
+
|
|
1080
|
+
b. List item b.
|
|
1081
|
+
|
|
1082
|
+
This paragraph belongs to list item b.
|
|
1083
|
+
--
|
|
1084
|
+
+
|
|
1085
|
+
This paragraph belongs to item 1.
|
|
1086
|
+
|
|
1087
|
+
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>
|
|
1088
|
+
List item one.
|
|
1089
|
+
</p><p>This paragraph is part of the preceding list item</p><div class="orderedlist"><ol type="a"><li><p>
|
|
1090
|
+
This list is nested and does not require explicit item continuation.
|
|
1091
|
+
</p><p>This paragraph is part of the preceding list item</p></li><li><p>
|
|
1092
|
+
List item b.
|
|
1093
|
+
</p><p>This paragraph belongs to list item b.</p></li></ol></div><p>This paragraph belongs to item 1.</p></li><li>
|
|
1094
|
+
Item 2 of the outer list.
|
|
1095
|
+
</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>
|
|
1096
|
+
and <code class="literal">footnoteref:[<id>,<text>]</code> inline macros for generating
|
|
1097
|
+
footnotes:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1098
|
+
The <code class="literal">footnote</code> macro generates a footnote.
|
|
1099
|
+
</li><li>
|
|
1100
|
+
The <code class="literal">footnoteref</code> macro has two forms: if the text is supplied a
|
|
1101
|
+
foot note with an ID is generated; if the text is omitted a
|
|
1102
|
+
reference to the footnote with the specified ID is generated.
|
|
1103
|
+
</li><li>
|
|
1104
|
+
The footnote text can span multiple lines.
|
|
1105
|
+
</li></ul></div><p>Example footnote:</p><pre class="literallayout">A footnote footnote:[An example footnote.];
|
|
1106
|
+
a second footnote with a reference ID footnoteref:[note2,Second footnote.];
|
|
1107
|
+
finally a reference to the second footnote footnoteref:[note2].</pre><p>Which renders:</p><p>A footnote <sup>[<a id="id2533619" href="#ftn.id2533619" class="footnote">2</a>]</sup>;
|
|
1108
|
+
a second footnote with a reference ID <sup>[<a id="note2" href="#ftn.note2" class="footnote">3</a>]</sup>;
|
|
1109
|
+
finally a reference to the second footnote <sup>[<a href="#ftn.note2" class="footnoteref">3</a>]</sup>.</p><p>Footnotes are primarily useful when generating DocBook output — DocBook conversion programs render footnote outside the primary text
|
|
1110
|
+
flow.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_indexes"></a>15. Indexes</h2></div></div></div><p>The shipped <span class="emphasis"><em>AsciiDoc</em></span> configuration includes the inline macros for
|
|
1111
|
+
generating document index entries.</p><div class="variablelist"><dl><dt><span class="term">
|
|
1112
|
+
<code class="literal">indexterm:[<primary>,<secondary>,<tertiary>]</code>
|
|
1113
|
+
, </span><span class="term">
|
|
1114
|
+
<code class="literal">(((<primary>,<secondary>,<tertiary>)))</code>
|
|
1115
|
+
</span></dt><dd>
|
|
1116
|
+
This inline macro generates an index term (the <secondary> and
|
|
1117
|
+
<tertiary> attributes are optional). For example
|
|
1118
|
+
<code class="literal">indexterm:[Tigers,Big cats]</code> (or, using the alternative syntax
|
|
1119
|
+
<code class="literal">(((Tigers,Big cats)))</code>. Index terms that have secondary and
|
|
1120
|
+
tertiary entries also generate separate index terms for the
|
|
1121
|
+
secondary and tertiary entries. The index terms appear in the
|
|
1122
|
+
index, not the primary text flow.
|
|
1123
|
+
</dd><dt><span class="term">
|
|
1124
|
+
<code class="literal">\indexterm2:[<primary>]</code>
|
|
1125
|
+
, </span><span class="term">
|
|
1126
|
+
<code class="literal">((<primary>))</code>
|
|
1127
|
+
</span></dt><dd>
|
|
1128
|
+
This inline macro generates an index term that appears in both the
|
|
1129
|
+
index and the primary text flow. The <code class="literal"><primary></code> should not be
|
|
1130
|
+
padded to the left or right with white space characters.
|
|
1131
|
+
</dd></dl></div><p>For working examples see the <code class="literal">article.txt</code> and <code class="literal">book.txt</code> documents in
|
|
1132
|
+
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
|
|
1133
|
+
DocBook markup — DocBook conversion programs automatically generate
|
|
1134
|
+
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,
|
|
1135
|
+
computer output and user input for example). Callout markers are
|
|
1136
|
+
placed inside the annotated text while the actual annotations are
|
|
1137
|
+
presented in a callout list after the annotated text. Here’s an
|
|
1138
|
+
example:</p><pre class="screen"> .MS-DOS directory listing
|
|
1139
|
+
-----------------------------------------------------
|
|
1140
|
+
10/17/97 9:04 <DIR> bin
|
|
1141
|
+
10/16/97 14:11 <DIR> DOS <1>
|
|
1142
|
+
10/16/97 14:40 <DIR> Program Files
|
|
1143
|
+
10/16/97 14:46 <DIR> TEMP
|
|
1144
|
+
10/17/97 9:04 <DIR> tmp
|
|
1145
|
+
10/16/97 14:37 <DIR> WINNT
|
|
1146
|
+
10/16/97 14:25 119 AUTOEXEC.BAT <2>
|
|
1147
|
+
2/13/94 6:21 54,619 COMMAND.COM <2>
|
|
1148
|
+
10/16/97 14:25 115 CONFIG.SYS <2>
|
|
1149
|
+
11/16/97 17:17 61,865,984 pagefile.sys
|
|
1150
|
+
2/13/94 6:21 9,349 WINA20.386 <3>
|
|
1151
|
+
-----------------------------------------------------
|
|
1152
|
+
|
|
1153
|
+
<1> This directory holds MS-DOS.
|
|
1154
|
+
<2> System startup code for DOS.
|
|
1155
|
+
<3> Some sort of Windows 3.1 hack.</pre><p>Which renders:</p><div class="example"><a id="id2533843"></a><p class="title"><b>Example 2. MS-DOS directory listing</b></p><div class="example-contents"><pre class="screen">10/17/97 9:04 <DIR> bin
|
|
1156
|
+
10/16/97 14:11 <DIR> DOS <a id="CO1-1"></a><img src="./images/icons/callouts/1.png" alt="1" border="0" />
|
|
1157
|
+
10/16/97 14:40 <DIR> Program Files
|
|
1158
|
+
10/16/97 14:46 <DIR> TEMP
|
|
1159
|
+
10/17/97 9:04 <DIR> tmp
|
|
1160
|
+
10/16/97 14:37 <DIR> WINNT
|
|
1161
|
+
10/16/97 14:25 119 AUTOEXEC.BAT <a id="CO1-2"></a><img src="./images/icons/callouts/2.png" alt="2" border="0" />
|
|
1162
|
+
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" />
|
|
1163
|
+
10/16/97 14:25 115 CONFIG.SYS <a id="CO1-4"></a><img src="./images/icons/callouts/4.png" alt="4" border="0" />
|
|
1164
|
+
11/16/97 17:17 61,865,984 pagefile.sys
|
|
1165
|
+
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">
|
|
1166
|
+
This directory holds MS-DOS.
|
|
1167
|
+
</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">
|
|
1168
|
+
System startup code for DOS.
|
|
1169
|
+
</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">
|
|
1170
|
+
Some sort of Windows 3.1 hack.
|
|
1171
|
+
</td></tr></table></div><div class="itemizedlist"><p class="title"><b>Explanation</b></p><ul type="disc"><li>
|
|
1172
|
+
The callout marks are whole numbers enclosed in angle brackets that
|
|
1173
|
+
refer to an item index in the following callout list.
|
|
1174
|
+
</li><li>
|
|
1175
|
+
By default callout marks are confined to LiteralParagraphs,
|
|
1176
|
+
LiteralBlocks and ListingBlocks (although this is a configuration
|
|
1177
|
+
file option and can be changed).
|
|
1178
|
+
</li><li>
|
|
1179
|
+
Callout list item numbering is fairly relaxed — list items can
|
|
1180
|
+
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
|
|
1181
|
+
number (in the latter case list items starting with a single <code class="literal">></code>
|
|
1182
|
+
character are implicitly numbered starting at one).
|
|
1183
|
+
</li><li>
|
|
1184
|
+
Callout lists should not be nested — start list items hard against
|
|
1185
|
+
the left margin.
|
|
1186
|
+
</li><li>
|
|
1187
|
+
If you want to present a number inside angle brackets you’ll need to
|
|
1188
|
+
escape it with a backslash to prevent it being interpreted as a
|
|
1189
|
+
callout mark.
|
|
1190
|
+
</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
|
|
1191
|
+
<a class="link" href="#X43" title="29.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
|
|
1192
|
+
callout lists are generated using the <span class="emphasis"><em>callout</em></span> list definition. The
|
|
1193
|
+
<span class="emphasis"><em>callout</em></span> macro and <span class="emphasis"><em>callout</em></span> list are special in that they work
|
|
1194
|
+
together. The <span class="emphasis"><em>callout</em></span> inline macro is not enabled by the normal
|
|
1195
|
+
<span class="emphasis"><em>macros</em></span> substitutions option, instead it has its own <span class="emphasis"><em>callouts</em></span>
|
|
1196
|
+
substitution option.</p><p>The following attributes are available during inline callout macro
|
|
1197
|
+
substitution:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1198
|
+
<code class="literal">{index}</code>
|
|
1199
|
+
</span></dt><dd>
|
|
1200
|
+
The callout list item index inside the angle brackets.
|
|
1201
|
+
</dd><dt><span class="term">
|
|
1202
|
+
<code class="literal">{coid}</code>
|
|
1203
|
+
</span></dt><dd>
|
|
1204
|
+
An identifier formatted like <code class="literal">CO<listnumber>-<index></code> that
|
|
1205
|
+
uniquely identifies the callout mark. For example <code class="literal">CO2-4</code>
|
|
1206
|
+
identifies the fourth callout mark in the second set of callout
|
|
1207
|
+
marks.
|
|
1208
|
+
</dd></dl></div><p>The <code class="literal">{coids}</code> attribute can be used during callout list item
|
|
1209
|
+
substitution — it is a space delimited list of callout IDs that refer
|
|
1210
|
+
to the explanatory list item.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_including_callouts_in_included_code"></a>16.2. Including callouts in included code</h3></div></div></div><p>You can annotate working code examples with callouts — just remember
|
|
1211
|
+
to put the callouts inside source code comments. This example displays
|
|
1212
|
+
the <code class="literal">test.py</code> source file (containing a single callout) using the
|
|
1213
|
+
<a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>:</p><div class="example"><a id="id2534180"></a><p class="title"><b>Example 3. AsciiDoc source</b></p><div class="example-contents"><pre class="screen">[source,python]
|
|
1214
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1215
|
+
include::test.py[]
|
|
1216
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
1217
|
+
|
|
1218
|
+
<1> Print statement.</pre></div></div><br class="example-break" /><div class="example"><a id="id2534196"></a><p class="title"><b>Example 4. Included <code class="literal">test.py</code> source</b></p><div class="example-contents"><pre class="screen">print 'Hello World!' # <1></pre></div></div><br class="example-break" /></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_macros"></a>17. Macros</h2></div></div></div><p>Macros are a mechanism for substituting parametrized text into output
|
|
1219
|
+
documents.</p><p>Macros have a <span class="emphasis"><em>name</em></span>, a single <span class="emphasis"><em>target</em></span> argument and an <span class="emphasis"><em>attribute
|
|
1220
|
+
list</em></span>. The usual syntax is <code class="literal"><name>:<target>[<attrlist>]</code> (for
|
|
1221
|
+
inline macros) and <code class="literal"><name>::<target>[<attrlist>]</code> (for block
|
|
1222
|
+
macros). Here are some examples:</p><pre class="literallayout">http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
|
|
1223
|
+
include::chapt1.txt[tabsize=2]
|
|
1224
|
+
mailto:srackham@gmail.com[]</pre><div class="itemizedlist"><p class="title"><b>Macro behavior</b></p><ul type="disc"><li>
|
|
1225
|
+
<code class="literal"><name></code> is the macro name. It can only contain letters, digits or
|
|
1226
|
+
dash characters and cannot start with a dash.
|
|
1227
|
+
</li><li>
|
|
1228
|
+
The optional <code class="literal"><target></code> cannot contain white space characters.
|
|
1229
|
+
</li><li>
|
|
1230
|
+
<code class="literal"><attrlist></code> is a <a class="link" href="#X21" title="24. Attribute Lists">list of attributes</a> enclosed in square
|
|
1231
|
+
brackets.
|
|
1232
|
+
</li><li>
|
|
1233
|
+
<code class="literal">]</code> characters in attribute lists that are enclosed in <code class="literal">[]</code> brackets
|
|
1234
|
+
must be escaped with a backslash.
|
|
1235
|
+
</li><li>
|
|
1236
|
+
Expansion of non-system macro references can normally be escaped by
|
|
1237
|
+
prefixing a backslash character (see the <span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>FAQ</em></span> for examples
|
|
1238
|
+
of exceptions to this rule).
|
|
1239
|
+
</li><li>
|
|
1240
|
+
System macros cannot be escaped.
|
|
1241
|
+
</li><li>
|
|
1242
|
+
Attribute references in block macros are expanded.
|
|
1243
|
+
</li><li>
|
|
1244
|
+
The substitutions performed prior to Inline macro macro expansion
|
|
1245
|
+
are determined by the inline context.
|
|
1246
|
+
</li><li>
|
|
1247
|
+
Macros are processed in the order they appear in the configuration
|
|
1248
|
+
file(s).
|
|
1249
|
+
</li><li>
|
|
1250
|
+
Calls to inline macros can be nested inside different inline macros
|
|
1251
|
+
(an inline macro call cannot contain a nested call to itself).
|
|
1252
|
+
</li><li>
|
|
1253
|
+
In addition to <code class="literal"><name></code>, <code class="literal"><target></code> and <code class="literal"><attrlist></code> the
|
|
1254
|
+
<code class="literal"><passtext></code> and <code class="literal"><subslist></code> named groups are available to
|
|
1255
|
+
<a class="link" href="#X77" title="17.4. Passthrough macros">passthrough macros</a>.
|
|
1256
|
+
</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
|
|
1257
|
+
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
|
|
1258
|
+
rendered using predefined inline macros.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1259
|
+
If you don’t need a customized the link caption you can enter the
|
|
1260
|
+
<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
|
|
1261
|
+
special macro syntax.
|
|
1262
|
+
</li><li>
|
|
1263
|
+
If the <code class="literal"><attrlist></code> is empty the URL is displayed.
|
|
1264
|
+
</li></ul></div><p>Here are some examples:</p><pre class="literallayout">http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
|
|
1265
|
+
http://www.methods.co.nz/asciidoc/
|
|
1266
|
+
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
|
|
1267
|
+
joe.bloggs@foobar.com
|
|
1268
|
+
callto:joe.bloggs[]</pre><p>Which are rendered:</p><p><a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">The <span class="emphasis"><em>AsciiDoc</em></span> home page</a></p><p><a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">http://www.methods.co.nz/asciidoc/</a></p><p><a class="ulink" href="mailto:joe.bloggs@foobar.com" target="_top">email Joe Bloggs</a></p><p><a class="ulink" href="mailto:joe.bloggs@foobar.com" target="_top">joe.bloggs@foobar.com</a></p><p><a class="ulink" href="callto:joe.bloggs" target="_top">joe.bloggs</a></p><div class="itemizedlist"><ul type="disc"><li>
|
|
1269
|
+
If the <code class="literal"><target></code> necessitates space characters they should be
|
|
1270
|
+
replaced by <code class="literal">%20</code>. For example <code class="literal">large%20image.png</code>.
|
|
1271
|
+
</li><li>
|
|
1272
|
+
Define an attribute entry if you refer to the same URL more than
|
|
1273
|
+
once, this will make your document <a class="link" href="#X62" title="Attribute entries promote clarity and eliminate repetition">easier to maintain and easier to read</a>.
|
|
1274
|
+
</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
|
|
1275
|
+
within an <span class="emphasis"><em>AsciiDoc</em></span> document. You can use either the standard macro
|
|
1276
|
+
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>]]
|
|
1277
|
+
anchor:<id>[<xreflabel>]</pre><p>The <code class="literal"><id></code> is a unique identifier that must begin with a letter. The
|
|
1278
|
+
optional <code class="literal"><xreflabel></code> is the text to be displayed by captionless
|
|
1279
|
+
<span class="emphasis"><em>xref</em></span> macros that refer to this anchor. The optional <code class="literal"><xreflabel></code> is
|
|
1280
|
+
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
|
|
1281
|
+
same as that of the <a class="link" href="#X41" title="10. BlockId Element">BlockId block element</a>, this is no
|
|
1282
|
+
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>>>
|
|
1283
|
+
xref:<id>[<caption>]</pre><p>The <code class="literal"><id></code> refers to an existing anchor <code class="literal"><id></code>. The optional
|
|
1284
|
+
<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
|
|
1285
|
+
auto-generated:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1286
|
+
The <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">xhtml11</code> backend displays the <code class="literal"><id></code> enclosed in
|
|
1287
|
+
square brackets.
|
|
1288
|
+
</li><li>
|
|
1289
|
+
If DocBook is produced the DocBook toolchain is responsible for the
|
|
1290
|
+
displayed text which will normally be the referenced figure, table
|
|
1291
|
+
or section title number followed by the element’s title text.
|
|
1292
|
+
</li></ul></div><p>Here is an example:</p><pre class="screen">[[tiger_image]]
|
|
1293
|
+
.Tyger tyger
|
|
1294
|
+
image::tiger.png[]
|
|
1295
|
+
|
|
1296
|
+
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
|
|
1297
|
+
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
|
|
1298
|
+
the target file name (relative to the file system location of the
|
|
1299
|
+
referring document). The optional <code class="literal"><caption></code> is the link’s displayed
|
|
1300
|
+
text. If <code class="literal"><caption></code> is not specified then <code class="literal"><target></code> is displayed.
|
|
1301
|
+
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
|
|
1302
|
+
a target document but this usually only makes sense when targeting
|
|
1303
|
+
HTML documents.</p><p>Images can serve as hyperlinks using the <a class="link" 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>
|
|
1304
|
+
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
|
|
1305
|
+
image its file format must be supported by the target backend
|
|
1306
|
+
application. HTML and DocBook applications normally support PNG or JPG
|
|
1307
|
+
files.</p><p><code class="literal"><target></code> file name paths are relative to the location of the
|
|
1308
|
+
referring document.</p><div class="itemizedlist"><a id="X55"></a><p class="title"><b>Image macro attributes</b></p><ul type="disc"><li><p>
|
|
1309
|
+
The optional first positional attribute list entry specifies the
|
|
1310
|
+
alternative text which is displayed if the output application is
|
|
1311
|
+
unable to process the image file. For example:
|
|
1312
|
+
</p><pre class="literallayout">image:images/logo.png[Company Logo]</pre></li><li><p>
|
|
1313
|
+
The optional <code class="literal">width</code> and <code class="literal">height</code> attributes scale the image size
|
|
1314
|
+
and can be used in any combination. The units are pixels. The
|
|
1315
|
+
following example scales the previous example to a height of 32
|
|
1316
|
+
pixels:
|
|
1317
|
+
</p><pre class="literallayout">image:images/logo.png["Company Logo",height=32]</pre></li><li><p>
|
|
1318
|
+
The optional <code class="literal">link</code> attribute is used to link the image to an
|
|
1319
|
+
external document. The following example links a screenshot
|
|
1320
|
+
thumbnail to a full size version:
|
|
1321
|
+
</p><pre class="literallayout">image:screen-thumbnail.png[height=32,link="screen.png"]</pre></li><li><p>
|
|
1322
|
+
The optional <code class="literal">scaledwidth</code> attribute is only used in DocBook block
|
|
1323
|
+
images (specifically for PDF documents). The following example
|
|
1324
|
+
scales the images to 75% of the available print width:
|
|
1325
|
+
</p><pre class="literallayout">image::images/logo.png["Company Logo",scaledwidth="75%"]</pre></li><li><p>
|
|
1326
|
+
The optional <code class="literal">align</code> attribute is used for horizontal image
|
|
1327
|
+
alignment in DocBook block images (specifically for PDF documents).
|
|
1328
|
+
Allowed values are <code class="literal">center</code>, <code class="literal">left</code> and <code class="literal">right</code>. For example:
|
|
1329
|
+
</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
|
|
1330
|
+
either side by a blank line or a block delimiter.</p><p>Block macros behave just like Inline macros, with the following
|
|
1331
|
+
differences:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1332
|
+
They occur in a block context.
|
|
1333
|
+
</li><li>
|
|
1334
|
+
The default syntax is <code class="literal"><name>::<target>[<attrlist>]</code> (two
|
|
1335
|
+
colons, not one).
|
|
1336
|
+
</li><li>
|
|
1337
|
+
Markup template section names end in <code class="literal">-blockmacro</code> instead of
|
|
1338
|
+
<code class="literal">-inlinemacro</code>.
|
|
1339
|
+
</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
|
|
1340
|
+
syntax as the <a class="link" href="#X30" title="17.1.2.1. anchor">anchor inline macro</a> since it performs
|
|
1341
|
+
essentially the same function — block templates employ the <code class="literal">id</code>
|
|
1342
|
+
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
|
|
1343
|
+
<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 class="link" href="#X55" title="Image macro attributes">macro attributes</a> as its
|
|
1344
|
+
<a class="link" 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
|
|
1345
|
+
<span class="emphasis"><em>BlockTitle</em></span>. DocBook toolchains normally number examples and
|
|
1346
|
+
generate a <span class="emphasis"><em>List of Figures</em></span> backmatter section.</p><p>For example:</p><pre class="literallayout">.Main circuit board
|
|
1347
|
+
image::images/layout.png[J14P main circuit board]</pre><p>A title prefix that can be inserted with the <code class="literal">caption</code> attribute
|
|
1348
|
+
(<code class="literal">xhtml11</code> and <code class="literal">html4</code> backends). For example:</p><pre class="literallayout">.Main circuit board
|
|
1349
|
+
[caption="Figure 2:"]
|
|
1350
|
+
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
|
|
1351
|
+
<span class="emphasis"><em>image</em></span> macros will be embedded in XHTML outputs using the
|
|
1352
|
+
<a class="ulink" href="http://en.wikipedia.org/wiki/Data:_URI_scheme" target="_top">data: URI scheme</a>. You
|
|
1353
|
+
can use the <code class="literal">data-uri</code> attribute to produce single-file XHTML
|
|
1354
|
+
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>
|
|
1355
|
+
<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>,
|
|
1356
|
+
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
|
|
1357
|
+
left margin are treated as comments and are stripped from the output.
|
|
1358
|
+
Comment lines have been implemented as a block macro and are only
|
|
1359
|
+
valid in a block context — they are not treated as comments inside
|
|
1360
|
+
paragraphs or delimited blocks. Example comment line:</p><pre class="literallayout">// This is a comment.</pre><p>See also <a class="link" href="#X26" title="12.5. Comment Blocks">Comment Blocks</a>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_system_macros"></a>17.3. System Macros</h3></div></div></div><p>System macros are block macros that perform a predefined task and are
|
|
1361
|
+
hardwired into the <code class="literal">asciidoc(1)</code> program.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1362
|
+
You can escape system macros with a leading backslash character
|
|
1363
|
+
(as you can with other macros).
|
|
1364
|
+
</li><li>
|
|
1365
|
+
The syntax and tasks performed by system macros is built into
|
|
1366
|
+
<code class="literal">asciidoc(1)</code> so they don’t appear in configuration files. You can
|
|
1367
|
+
however customize the syntax by adding entries to a configuration
|
|
1368
|
+
file <code class="literal">[macros]</code> section.
|
|
1369
|
+
</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
|
|
1370
|
+
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
|
|
1371
|
+
document — tabs are expanded and system macros processed. The
|
|
1372
|
+
contents of <code class="literal">include1</code> files are not subject to tab expansion or
|
|
1373
|
+
system macro processing nor are attribute or lower priority
|
|
1374
|
+
substitutions performed. The <code class="literal">include1</code> macro’s main use is to include
|
|
1375
|
+
verbatim embedded CSS or scripts into configuration file headers.
|
|
1376
|
+
Example:</p><pre class="screen">include::chapter1.txt[tabsize=4]</pre><div class="itemizedlist"><p class="title"><b>Include macro behavior</b></p><ul type="disc"><li>
|
|
1377
|
+
If the included file name is specified with a relative path then the
|
|
1378
|
+
path is relative to the location of the referring document.
|
|
1379
|
+
</li><li>
|
|
1380
|
+
Include macros can appear inside configuration files.
|
|
1381
|
+
</li><li>
|
|
1382
|
+
Files included from within <span class="emphasis"><em>DelimitedBlocks</em></span> are read to completion
|
|
1383
|
+
to avoid false end-of-block underline termination.
|
|
1384
|
+
</li><li>
|
|
1385
|
+
Attribute references are expanded inside the include <span class="emphasis"><em>target</em></span>; if an
|
|
1386
|
+
attribute is undefined then the included file is silently skipped.
|
|
1387
|
+
</li><li>
|
|
1388
|
+
The <span class="emphasis"><em>tabsize</em></span> macro attribute sets the number of space characters to
|
|
1389
|
+
be used for tab expansion in the included file (not applicable to
|
|
1390
|
+
<code class="literal">include1</code> macro).
|
|
1391
|
+
</li><li>
|
|
1392
|
+
The <span class="emphasis"><em>depth</em></span> macro attribute sets the maximum permitted number of
|
|
1393
|
+
subsequent nested includes (not applicable to <code class="literal">include1</code> macro which
|
|
1394
|
+
does not process nested includes). Setting <span class="emphasis"><em>depth</em></span> to one disables
|
|
1395
|
+
nesting inside the included file. By default, nesting is limited to
|
|
1396
|
+
a depth of five.
|
|
1397
|
+
</li><li>
|
|
1398
|
+
Internally the <code class="literal">include1</code> macro is translated to the <code class="literal">include1</code>
|
|
1399
|
+
system attribute which means it must be evaluated in a region where
|
|
1400
|
+
attribute substitution is enabled. To inhibit nested substitution in
|
|
1401
|
+
included files it is preferable to use the <code class="literal">include</code> macro and set
|
|
1402
|
+
the attribute <code class="literal">depth=1</code>.
|
|
1403
|
+
</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
|
|
1404
|
+
excluded from processing based on the existence (or not) of a
|
|
1405
|
+
document attribute. There are two forms of conditional inclusion
|
|
1406
|
+
macro usage, the first includes document text between the <code class="literal">ifdef</code> and
|
|
1407
|
+
<code class="literal">endif</code> macros if a document attribute is defined:</p><pre class="literallayout">ifdef::<attribute>[]
|
|
1408
|
+
:
|
|
1409
|
+
endif::<attribute>[]</pre><p>The second for includes document text between the <code class="literal">ifndef</code> and <code class="literal">endif</code>
|
|
1410
|
+
macros if the attribute is not defined:</p><pre class="literallayout">ifndef::<attribute>[]
|
|
1411
|
+
:
|
|
1412
|
+
endif::<attribute>[]</pre><p><code class="literal"><attribute></code> is an attribute name which is optional in the trailing
|
|
1413
|
+
<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>
|
|
1414
|
+
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
|
|
1415
|
+
there is another type of conditional inclusion based on attribute
|
|
1416
|
+
references, the latter being evaluated when the output file is
|
|
1417
|
+
written.</p><p>These examples illustrate the two forms of conditional inclusion. The
|
|
1418
|
+
only difference between them is that the first is evaluated at program
|
|
1419
|
+
load time while the second is evaluated when the output is written:</p><pre class="literallayout">ifdef::world[]
|
|
1420
|
+
Hello World!
|
|
1421
|
+
endif::world[]</pre><pre class="literallayout">{world#}Hello World!</pre><p>In this example when the <code class="literal">{world#}</code> conditional attribute reference
|
|
1422
|
+
is evaluates to a zero length string if <code class="literal">world</code> is defined; if <code class="literal">world</code>
|
|
1423
|
+
is not defined the whole line is dropped.</p><p>The subtle difference between the two types of conditional inclusion
|
|
1424
|
+
has implications for <span class="emphasis"><em>AsciiDoc</em></span> configuration files: <span class="emphasis"><em>AsciiDoc</em></span> has to
|
|
1425
|
+
read the configuration files <span class="strong"><strong>before</strong></span> reading the source document,
|
|
1426
|
+
this is necessary because the <span class="emphasis"><em>AsciiDoc</em></span> source syntax is mostly defined
|
|
1427
|
+
by the configuration files. This means that any lines of markup
|
|
1428
|
+
enveloped by conditional inclusion macros will be included or excluded
|
|
1429
|
+
<span class="strong"><strong>before</strong></span> the attribute entries in the <span class="emphasis"><em>AsciiDoc</em></span> document header are
|
|
1430
|
+
read, so setting related attributes in the <span class="emphasis"><em>AsciiDoc</em></span> source document
|
|
1431
|
+
header will have no effect. If you need to control configuration file
|
|
1432
|
+
markup inclusion with attribute entries in the <span class="emphasis"><em>AsciiDoc</em></span> source file
|
|
1433
|
+
header you need to use attribute references to control inclusion
|
|
1434
|
+
instead of conditional inclusion macros (attribute references are
|
|
1435
|
+
substituted at the time the output is written rather than at program
|
|
1436
|
+
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
|
|
1437
|
+
<a class="link" href="#X24" title="25.3. System Attribute References">system attribute references</a>. The difference is that system
|
|
1438
|
+
macros occur in a block macro context whereas system attributes are
|
|
1439
|
+
confined to an inline context where attribute substitution is enabled.</p><p>The following example displays a long directory listing inside a
|
|
1440
|
+
literal block:</p><pre class="literallayout">------------------
|
|
1441
|
+
sys::[ls -l *.txt]
|
|
1442
|
+
------------------</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
|
|
1443
|
+
file template section within another. The following example includes
|
|
1444
|
+
the <code class="literal">[admonitionblock]</code> section in the <code class="literal">[admonitionparagraph]</code>
|
|
1445
|
+
section:</p><pre class="literallayout">[admonitionparagraph]
|
|
1446
|
+
template::[admonitionblock]</pre><div class="itemizedlist"><p class="title"><b>Template macro behavior</b></p><ul type="disc"><li>
|
|
1447
|
+
The <code class="literal">template::[]</code> macro is useful for factoring configuration file
|
|
1448
|
+
markup.
|
|
1449
|
+
</li><li>
|
|
1450
|
+
<code class="literal">template::[]</code> macros cannot be nested.
|
|
1451
|
+
</li><li>
|
|
1452
|
+
<code class="literal">template::[]</code> macro expansion is applied to all sections
|
|
1453
|
+
after all configuration files have been read.
|
|
1454
|
+
</li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X77"></a>17.4. Passthrough macros</h3></div></div></div><p>Passthrough macros are analogous to <a class="link" href="#X76" title="12.6. Passthrough Blocks">passthrough blocks</a> and are
|
|
1455
|
+
used to pass text directly to the output. The substitution performed
|
|
1456
|
+
on the text is determined by the macro definition but can be overridden
|
|
1457
|
+
by the <code class="literal"><subslist></code>. The usual syntax is
|
|
1458
|
+
<code class="literal"><name>:<subslist>[<passtext>]</code> (for inline macros) and
|
|
1459
|
+
<code class="literal"><name>::<subslist>[<passtext>]</code> (for block macros).</p><div class="variablelist"><dl><dt><span class="term">
|
|
1460
|
+
pass
|
|
1461
|
+
</span></dt><dd><p>
|
|
1462
|
+
Inline and block. Passes text unmodified apart from explicitly
|
|
1463
|
+
specified substitutions). Examples:
|
|
1464
|
+
</p><pre class="literallayout">pass:[<q>To be or not to be</q>]
|
|
1465
|
+
pass:attributes,quotes[<u>the '{author}'</u>]</pre></dd><dt><span class="term">
|
|
1466
|
+
asciimath, latexmath
|
|
1467
|
+
</span></dt><dd>
|
|
1468
|
+
Inline and block. Passes text unmodified. Used for
|
|
1469
|
+
<a class="link" href="#X78" title="20. Mathematical Formulas">mathematical formulas</a>.
|
|
1470
|
+
</dd><dt><span class="term">
|
|
1471
|
+
+++
|
|
1472
|
+
</span></dt><dd><p>
|
|
1473
|
+
Inline and block. The triple-plus passthrough is functionally
|
|
1474
|
+
identical to the <span class="emphasis"><em>pass</em></span> macro but you don’t have to escape <code class="literal">]</code>
|
|
1475
|
+
characters and you can prefix with quoted attributes in the inline
|
|
1476
|
+
version. Example:
|
|
1477
|
+
</p><pre class="literallayout">Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula</pre></dd><dt><span class="term">
|
|
1478
|
+
$$
|
|
1479
|
+
</span></dt><dd><p>
|
|
1480
|
+
Inline and block. The double-dollar passthrough is functionally
|
|
1481
|
+
identical with one exception: special characters are escaped.
|
|
1482
|
+
Example:
|
|
1483
|
+
</p><pre class="literallayout">$$`[[a,b],[c,d]]((n),(k))`$$</pre></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_macro_definitions"></a>17.5. Macro Definitions</h3></div></div></div><p>Each entry in the configuration <code class="literal">[macros]</code> section is a macro
|
|
1484
|
+
definition which can take one of the following forms:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1485
|
+
<code class="literal"><pattern>=<name>[<subslist]</code>
|
|
1486
|
+
</span></dt><dd>
|
|
1487
|
+
Inline macro definition.
|
|
1488
|
+
</dd><dt><span class="term">
|
|
1489
|
+
<code class="literal"><pattern>=#<name>[<subslist]</code>
|
|
1490
|
+
</span></dt><dd>
|
|
1491
|
+
Block macro definition.
|
|
1492
|
+
</dd><dt><span class="term">
|
|
1493
|
+
<code class="literal"><pattern>=+<name>[<subslist]</code>
|
|
1494
|
+
</span></dt><dd>
|
|
1495
|
+
System macro definition.
|
|
1496
|
+
</dd><dt><span class="term">
|
|
1497
|
+
<code class="literal"><pattern></code>
|
|
1498
|
+
</span></dt><dd>
|
|
1499
|
+
Delete the existing macro with this <code class="literal"><pattern></code>.
|
|
1500
|
+
</dd></dl></div><p><code class="literal"><pattern></code> is a Python regular expression and <code class="literal"><name></code> is the name of
|
|
1501
|
+
a markup template. If <code class="literal"><name></code> is omitted then it is the value of the
|
|
1502
|
+
regular expression match group named <span class="emphasis"><em>name</em></span>. The optional
|
|
1503
|
+
<code class="literal">[<subslist]</code> is a comma-separated list of substitution names enclosed
|
|
1504
|
+
in <code class="literal">[]</code> brackets, it sets the default substitutions for passthrough
|
|
1505
|
+
text, if omitted then no passthrough substitutions are performed.</p><p><b>Pattern named groups. </b>The following named groups can be used in macro <code class="literal"><pattern></code> regular
|
|
1506
|
+
expressions and are available as markup template attributes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1507
|
+
name
|
|
1508
|
+
</span></dt><dd>
|
|
1509
|
+
The macro name.
|
|
1510
|
+
</dd><dt><span class="term">
|
|
1511
|
+
target
|
|
1512
|
+
</span></dt><dd>
|
|
1513
|
+
The macro target.
|
|
1514
|
+
</dd><dt><span class="term">
|
|
1515
|
+
attrlist
|
|
1516
|
+
</span></dt><dd>
|
|
1517
|
+
The macro attribute list.
|
|
1518
|
+
</dd><dt><span class="term">
|
|
1519
|
+
passtext
|
|
1520
|
+
</span></dt><dd>
|
|
1521
|
+
Contents of this group are passed unmodified to the output subject
|
|
1522
|
+
only to <span class="emphasis"><em>subslist</em></span> substitutions.
|
|
1523
|
+
</dd><dt><span class="term">
|
|
1524
|
+
subslist
|
|
1525
|
+
</span></dt><dd>
|
|
1526
|
+
Processed as a comma-separated list of substitution names for
|
|
1527
|
+
<span class="emphasis"><em>passtext</em></span> substitution, overrides the the macro definition
|
|
1528
|
+
<span class="emphasis"><em>subslist</em></span>.
|
|
1529
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>Here’s what happens during macro substitution</b></p><ul type="disc"><li>
|
|
1530
|
+
Each contextually relevant macro <span class="emphasis"><em>pattern</em></span> from the <code class="literal">[macros]</code>
|
|
1531
|
+
section is matched against the input source line.
|
|
1532
|
+
</li><li>
|
|
1533
|
+
If a match is found the text to be substituted is loaded from a
|
|
1534
|
+
configuration markup template section named like
|
|
1535
|
+
<code class="literal"><name>-inlinemacro</code> or <code class="literal"><name>-blockmacro</code> (depending on the macro
|
|
1536
|
+
type).
|
|
1537
|
+
</li><li>
|
|
1538
|
+
Global and macro attribute list attributes are substituted in the
|
|
1539
|
+
macro’s markup template.
|
|
1540
|
+
</li><li>
|
|
1541
|
+
The substituted template replaces the macro reference in the output
|
|
1542
|
+
document.
|
|
1543
|
+
</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>The <span class="emphasis"><em>AsciiDoc</em></span> table syntax looks and behaves like other delimited block
|
|
1544
|
+
types and supports standard <a class="link" href="#X73" title="27. Block Element Definitions">block configuration entries</a>.
|
|
1545
|
+
Formatting is easy to read and, just as importantly, easy to enter.
|
|
1546
|
+
There are a wide variety of built-in customizable styles.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1547
|
+
All table meta-data is contained specified in the table’s attribute
|
|
1548
|
+
list, not in the the table data.
|
|
1549
|
+
</li><li>
|
|
1550
|
+
There is no provision for cells to span multiple columns.
|
|
1551
|
+
</li></ul></div><div class="sidebar"><p class="title"><b>Use tables sparingly</b></p><p>When technical users first start creating documents, tables (complete
|
|
1552
|
+
with column spanning and table nesting) are often considered very
|
|
1553
|
+
important. The reality is that tables are seldom used, even in
|
|
1554
|
+
technical documentation.</p><p>Try this exercise: thumb through your library of technical books,
|
|
1555
|
+
you’ll be surprised just how seldom tables are actually used, even
|
|
1556
|
+
less seldom are tables containing block elements such as paragraphs or
|
|
1557
|
+
lists. This is no accident, like figures, tables are outside the
|
|
1558
|
+
normal document flow — tables are for consulting not for reading.</p><p>Tables are designed for, and should normally only be used for,
|
|
1559
|
+
displaying column oriented tabular data.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_example_tables"></a>18.1. Example tables</h3></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_simple_table"></a>18.1.1. Simple table</h4></div></div></div><div class="informaltable"><table cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>1</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>2</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>A</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>3</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>4</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>B</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>5</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>6</p></td><td style="" align="left" valign="top"><p>C</p></td></tr></tbody></table></div><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">[width="15%"]
|
|
1560
|
+
|=======
|
|
1561
|
+
|1 |2 |A
|
|
1562
|
+
|3 |4 |B
|
|
1563
|
+
|5 |6 |C
|
|
1564
|
+
|=======</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_columns_formatted_with_strong_monospaced_and_emphasis_styles"></a>18.1.2. Columns formatted with strong, monospaced and emphasis styles</h4></div></div></div><div class="table"><a id="id2536713"></a><p class="title"><b>Table 2. An example table</b></p><div class="table-contents"><table summary="An example table" cellpadding="4px" style="border: none;"><colgroup><col align="right" /><col align="center" /><col align="left" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"> </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Column 2</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Column 3</th></tr></thead><tfoot valign="top"><tr><th style="border-right: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>footer 1</strong></span></p></th><th style="border-right: 1px solid ; " align="center" valign="top"><p><code class="literal">footer 2</code></p></th><th style="" align="left" valign="top"><p><span class="emphasis"><em>footer 3</em></span></p></th></tr></tfoot><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>1</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 1</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 1</em></span></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>2</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 2</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 2</em></span></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>3</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 3</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 3</em></span></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="right" valign="top"><p><span class="strong"><strong>4</strong></span></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p><code class="literal">Item 4</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><span class="emphasis"><em>Item 4</em></span></p></td></tr></tbody></table></div></div><br class="table-break" /><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">.An example table
|
|
1565
|
+
[width="50%",cols=">s,^m,e",frame="none",options="header,footer"]
|
|
1566
|
+
|==========================
|
|
1567
|
+
| |Column 2|Column 3
|
|
1568
|
+
|1 |Item 1 |Item 1
|
|
1569
|
+
|2 |Item 2 |Item 2
|
|
1570
|
+
|3 |Item 3 |Item 3
|
|
1571
|
+
|4 |Item 4 |Item 4
|
|
1572
|
+
|footer 1|footer 2|footer 3
|
|
1573
|
+
|==========================</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_horizontal_and_vertical_source_data"></a>18.1.3. Horizontal and vertical source data</h4></div></div></div><p>Short cells can be entered horizontally, longer cells vertically. The
|
|
1574
|
+
default behavior is to strip leading and trailing blank lines within a
|
|
1575
|
+
cell. These characteristics aid readability and data entry.</p><div class="table"><a id="id2536932"></a><p class="title"><b>Table 3. Windtrainer workouts</b></p><div class="table-contents"><table summary="Windtrainer workouts" cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="left" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Date </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Duration </th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Avg HR </th><th style="border-bottom: 1px solid ; " align="left" valign="top">Notes</th></tr></thead><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>22-Aug-08</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>10:24</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>157</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Worked out MSHR (max sustainable heart rate) by going hard
|
|
1576
|
+
for this interval.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>22-Aug-08</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>23:03</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>152</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Back-to-back with previous interval.</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>24-Aug-08</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>40:00</p></td><td style="border-right: 1px solid ; " align="center" valign="top"><p>145</p></td><td style="" align="left" valign="top"><p>Moderately hard interspersed with 3x 3min intervals (2min
|
|
1577
|
+
hard + 1min really hard taking the HR up to 160).</p></td></tr></tbody></table></div></div><br class="table-break" /><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">.Windtrainer workouts
|
|
1578
|
+
[width="80%",cols="3,^2,^2,10",options="header"]
|
|
1579
|
+
|=========================================================
|
|
1580
|
+
|Date |Duration |Avg HR |Notes
|
|
1581
|
+
|
|
1582
|
+
|22-Aug-08 |10:24 | 157 |
|
|
1583
|
+
Worked out MSHR (max sustainable heart rate) by going hard
|
|
1584
|
+
for this interval.
|
|
1585
|
+
|
|
1586
|
+
|22-Aug-08 |23:03 | 152 |
|
|
1587
|
+
Back-to-back with previous interval.
|
|
1588
|
+
|
|
1589
|
+
|24-Aug-08 |40:00 | 145 |
|
|
1590
|
+
Moderately hard interspersed with 3x 3min intervals (2min
|
|
1591
|
+
hard + 1min really hard taking the HR up to 160).
|
|
1592
|
+
|
|
1593
|
+
|=========================================================</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="_a_table_with_externally_sourced_csv_data"></a>18.1.4. A table with externally sourced CSV data</h4></div></div></div><div class="informaltable"><table cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="center" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">ID</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Customer Name</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Contact Name</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Customer Address</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Phone</th></tr></thead><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>AROUT</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Around the Horn</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Thomas Hardy</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>120 Hanover Sq.
|
|
1594
|
+
London</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>(171) 555-7788</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BERGS</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Berglunds snabbkop</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Christina Berglund</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Berguvsvagen 8
|
|
1595
|
+
Lulea</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>0921-12 34 65</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BLAUS</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Blauer See Delikatessen</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Hanna Moos</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Forsterstr. 57
|
|
1596
|
+
Mannheim</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>0621-08460</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BLONP</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Blondel pere et fils</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Frederique Citeaux</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>24, place Kleber
|
|
1597
|
+
Strasbourg</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>88.60.15.31</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BOLID</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Bolido Comidas preparadas</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Martin Sommer</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>C/ Araquil, 67
|
|
1598
|
+
Madrid</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>(91) 555 22 82</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BONAP</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Bon app'</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Laurence Lebihan</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>12, rue des Bouchers
|
|
1599
|
+
Marseille</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>91.24.45.40</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BOTTM</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Bottom-Dollar Markets</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Elizabeth Lincoln</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>23 Tsawassen Blvd.
|
|
1600
|
+
Tsawassen</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>(604) 555-4729</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top"><p>BSBEV</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>B’s Beverages</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Victoria Ashworth</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Fauntleroy Circus
|
|
1601
|
+
London</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>(171) 555-1212</p></td></tr><tr><td style="border-right: 1px solid ; " align="center" valign="top"><p>CACTU</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>Cactus Comidas para llevar</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>Patricio Simpson</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>Cerrito 333
|
|
1602
|
+
Buenos Aires</p></td><td style="" align="left" valign="top"><p>(1) 135-5555</p></td></tr></tbody></table></div><p><span class="emphasis"><em>AsciiDoc</em></span> source:</p><pre class="screen">[format="csv",cols="^1,4*2",options="header"]
|
|
1603
|
+
|===================================================
|
|
1604
|
+
ID,Customer Name,Contact Name,Customer Address,Phone
|
|
1605
|
+
include::customers.csv[]
|
|
1606
|
+
|===================================================</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X68"></a>18.2. Table input data formats</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> table data can be <span class="emphasis"><em>psv</em></span>, <span class="emphasis"><em>dsv</em></span> or <span class="emphasis"><em>csv</em></span> formatted. The
|
|
1607
|
+
default <span class="emphasis"><em>AsciiDoc</em></span> table format is <span class="emphasis"><em>psv</em></span>.</p><p><span class="emphasis"><em>csv</em></span> is the quasi-standard row oriented <span class="emphasis"><em>Comma Separated Values
|
|
1608
|
+
(CSV)</em></span> format commonly used to import and export spreadsheet and
|
|
1609
|
+
database data.</p><p><span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>psv</em></span> (<span class="emphasis"><em>Prefix Separated Values</em></span>) and <span class="emphasis"><em>dsv</em></span> (<span class="emphasis"><em>Delimiter
|
|
1610
|
+
Separated Values</em></span>) formats are cell oriented — the table is treated
|
|
1611
|
+
as a sequence of cells — there are no mandatory row separators.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1612
|
+
<span class="emphasis"><em>psv</em></span> prefixes each cell with a separator whereas <span class="emphasis"><em>dsv</em></span> delimits
|
|
1613
|
+
cells with a separator, that really the only difference (apart from
|
|
1614
|
+
different default separators).
|
|
1615
|
+
</li><li>
|
|
1616
|
+
<span class="emphasis"><em>psv</em></span> and <span class="emphasis"><em>dsv</em></span> separators are Python regular expressions.
|
|
1617
|
+
</li><li>
|
|
1618
|
+
The default <span class="emphasis"><em>psv</em></span> separator is <code class="literal">((?P<cellcount>\d+)\*)?\|</code> (a pipe
|
|
1619
|
+
character with optional cell multiplier prefix); the default <span class="emphasis"><em>dsv</em></span>
|
|
1620
|
+
separator is <code class="literal">:|\n</code> (a colon or a line break).
|
|
1621
|
+
</li><li>
|
|
1622
|
+
<span class="emphasis"><em>psv</em></span> and <span class="emphasis"><em>dsv</em></span> cell separators can be escaped by preceding them
|
|
1623
|
+
with a backslash character.
|
|
1624
|
+
</li><li>
|
|
1625
|
+
The <span class="emphasis"><em>psv</em></span> format allows cells to be stacked vertically, this makes
|
|
1626
|
+
it easy to enter large amounts of text per cell while still
|
|
1627
|
+
retaining readability.
|
|
1628
|
+
</li></ul></div><p>Here are four <span class="emphasis"><em>psv</em></span> cells (the second item is multiplied by two; the
|
|
1629
|
+
last contains an escaped separator):</p><pre class="literallayout">|One 2*|Two and three |A \| separator character</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X69"></a>18.3. Table attributes</h3></div></div></div><p>Individual tables are customized by an optional <a class="link" href="#X21" title="24. Attribute Lists">AttributeList</a>
|
|
1630
|
+
preceding the table. Specify attributes when you want to change the
|
|
1631
|
+
default table format:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1632
|
+
format
|
|
1633
|
+
</span></dt><dd>
|
|
1634
|
+
<span class="emphasis"><em>psv</em></span> (default), <span class="emphasis"><em>dsv</em></span> or <span class="emphasis"><em>csv</em></span> (See <a class="link" href="#X68" title="18.2. Table input data formats">Table Data Formats</a>).
|
|
1635
|
+
</dd><dt><span class="term">
|
|
1636
|
+
separator
|
|
1637
|
+
</span></dt><dd>
|
|
1638
|
+
The cell separator. A Python regular expression (<span class="emphasis"><em>psv</em></span> and <span class="emphasis"><em>dsv</em></span>
|
|
1639
|
+
formats) or a single character (<span class="emphasis"><em>csv</em></span> format).
|
|
1640
|
+
</dd><dt><span class="term">
|
|
1641
|
+
frame
|
|
1642
|
+
</span></dt><dd>
|
|
1643
|
+
Defines the table border and can take the following values: <span class="emphasis"><em>topbot</em></span>
|
|
1644
|
+
(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
|
|
1645
|
+
right sides). The default value is <span class="emphasis"><em>all</em></span>.
|
|
1646
|
+
</dd><dt><span class="term">
|
|
1647
|
+
grid
|
|
1648
|
+
</span></dt><dd>
|
|
1649
|
+
Defines which ruler lines are drawn between table rows and columns.
|
|
1650
|
+
The <span class="emphasis"><em>grid</em></span> attribute value can be any of the following values: <span class="emphasis"><em>none</em></span>,
|
|
1651
|
+
<span class="emphasis"><em>cols</em></span>, <span class="emphasis"><em>rows</em></span> and <span class="emphasis"><em>all</em></span>. The default value is <span class="emphasis"><em>all</em></span>.
|
|
1652
|
+
</dd><dt><span class="term">
|
|
1653
|
+
valign
|
|
1654
|
+
</span></dt><dd>
|
|
1655
|
+
Use the <span class="emphasis"><em>valign</em></span> attribute to vertically align all cells in a table.
|
|
1656
|
+
The following values are valid: <span class="emphasis"><em>top</em></span>, <span class="emphasis"><em>bottom</em></span>, and <span class="emphasis"><em>middle</em></span>
|
|
1657
|
+
(defaults to <span class="emphasis"><em>top</em></span>).
|
|
1658
|
+
</dd><dt><span class="term">
|
|
1659
|
+
options
|
|
1660
|
+
</span></dt><dd>
|
|
1661
|
+
The <span class="emphasis"><em>options</em></span> attribute can contain the following comma separated
|
|
1662
|
+
values: <span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>footer</em></span>. By default header and footer rows are
|
|
1663
|
+
omitted.
|
|
1664
|
+
</dd><dt><span class="term">
|
|
1665
|
+
cols
|
|
1666
|
+
</span></dt><dd><p>
|
|
1667
|
+
The <span class="emphasis"><em>cols</em></span> attribute is a comma separated list of <a class="link" href="#X70" title="18.4. Column Specifiers">column specifiers</a>. For example <code class="literal">cols="2<p,2*,4p,>"</code>.
|
|
1668
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1669
|
+
If <span class="emphasis"><em>cols</em></span> is present it must specify all columns.
|
|
1670
|
+
</li><li>
|
|
1671
|
+
If the <span class="emphasis"><em>cols</em></span> attribute is not specified the number of columns is
|
|
1672
|
+
calculated as the number of data items in the <span class="strong"><strong>first line</strong></span> of the
|
|
1673
|
+
table.
|
|
1674
|
+
</li><li>
|
|
1675
|
+
The degenerate form for the <span class="emphasis"><em>cols</em></span> attribute is an integer
|
|
1676
|
+
specifying the number of columns e.g. <code class="literal">cols=4</code>.
|
|
1677
|
+
</li></ul></div></dd><dt><span class="term">
|
|
1678
|
+
width
|
|
1679
|
+
</span></dt><dd>
|
|
1680
|
+
The <span class="emphasis"><em>width</em></span> attribute is expressed as a percentage value
|
|
1681
|
+
(<span class="emphasis"><em>"1%"</em></span>…<span class="emphasis"><em>"99%"</em></span>). The width specifies the table width relative to
|
|
1682
|
+
the available width. HTML outputs use this value directly. If width is
|
|
1683
|
+
specified DocBook uses the absolute widths (see calculated
|
|
1684
|
+
<a class="link" href="#X72" title="18.6. Markup attributes">markup attributes</a> ), if no width is specified all of the
|
|
1685
|
+
available width is used.
|
|
1686
|
+
</dd><dt><span class="term">
|
|
1687
|
+
filter
|
|
1688
|
+
</span></dt><dd>
|
|
1689
|
+
The <span class="emphasis"><em>filter</em></span> attribute defines an external shell command that is
|
|
1690
|
+
invoked for each cell. The built-in <span class="emphasis"><em>asciidoc</em></span> table style is
|
|
1691
|
+
implemented using a filter.
|
|
1692
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X70"></a>18.4. Column Specifiers</h3></div></div></div><p>Column specifiers define how columns are presented and are used in the
|
|
1693
|
+
table <a class="link" href="#X69" title="18.3. Table attributes">cols attribute</a>. A column specifier consists of an
|
|
1694
|
+
optional column multiplier followed by optional alignment, width and
|
|
1695
|
+
style values and is formatted like:</p><pre class="literallayout">[<multiplier>*][<align>][<width>][<style>]</pre><div class="itemizedlist"><ul type="disc"><li>
|
|
1696
|
+
All components are optional. The multiplier must be first and the
|
|
1697
|
+
style last. The order of <span class="emphasis"><em>align</em></span> or <span class="emphasis"><em>width</em></span> is not important.
|
|
1698
|
+
</li><li>
|
|
1699
|
+
Column <span class="emphasis"><em><width></em></span> can be either an integer proportional value (1…)
|
|
1700
|
+
or a percentage (1%…100%). The default value is 1. To ensure
|
|
1701
|
+
portability across different backends, there is no provision for
|
|
1702
|
+
absolute column widths (not to be confused with output column width
|
|
1703
|
+
<a class="link" href="#X72" title="18.6. Markup attributes">markup attributes</a> which are available in both percentage and
|
|
1704
|
+
absolute units).
|
|
1705
|
+
</li><li>
|
|
1706
|
+
The column <span class="emphasis"><em><align></em></span> character can be <span class="emphasis"><em><</em></span> (left), <span class="emphasis"><em>^</em></span> (center) or
|
|
1707
|
+
<span class="emphasis"><em>></em></span> (right). Cells are left aligned by default.
|
|
1708
|
+
</li><li>
|
|
1709
|
+
A <span class="emphasis"><em><multiplier></em></span> can be used to specify repeated columns e.g.
|
|
1710
|
+
<code class="literal">cols="4*<"</code> specifies four left-justified columns. Default value 1.
|
|
1711
|
+
</li><li>
|
|
1712
|
+
The <span class="emphasis"><em><style></em></span> name specifies a <a class="link" href="#X71" title="18.5. Table styles">table style</a> to used to markup
|
|
1713
|
+
column cells (you can use the full style names if you wish but the
|
|
1714
|
+
first letter is normally sufficient).
|
|
1715
|
+
</li><li>
|
|
1716
|
+
Column specific styles are not applied to <span class="emphasis"><em>header</em></span> row formatting.
|
|
1717
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X71"></a>18.5. Table styles</h3></div></div></div><p>Table styles can be applied to the entire table (by setting the
|
|
1718
|
+
<span class="emphasis"><em>style</em></span> attribute in the table’s attribute list) or on a per column
|
|
1719
|
+
basis (by specifying the style in the table’s <a class="link" href="#X69" title="18.3. Table attributes">cols attribute</a>).
|
|
1720
|
+
Tables come with the following predefined styles:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1721
|
+
default
|
|
1722
|
+
</span></dt><dd>
|
|
1723
|
+
The default style: <span class="emphasis"><em>AsciiDoc</em></span> inline text formatting; blank lines are
|
|
1724
|
+
treated as paragraph breaks.
|
|
1725
|
+
</dd><dt><span class="term">
|
|
1726
|
+
emphasis
|
|
1727
|
+
</span></dt><dd>
|
|
1728
|
+
Like default but all text is emphasised.
|
|
1729
|
+
</dd><dt><span class="term">
|
|
1730
|
+
monospaced
|
|
1731
|
+
</span></dt><dd>
|
|
1732
|
+
Like default but all text is in a monospaced font.
|
|
1733
|
+
</dd><dt><span class="term">
|
|
1734
|
+
strong
|
|
1735
|
+
</span></dt><dd>
|
|
1736
|
+
Like default but all text is bold.
|
|
1737
|
+
</dd><dt><span class="term">
|
|
1738
|
+
asciidoc
|
|
1739
|
+
</span></dt><dd>
|
|
1740
|
+
With this style table cells can contain any of the <span class="emphasis"><em>AsciiDoc</em></span> elements
|
|
1741
|
+
that are allowed inside document sections. This style runs <code class="literal">asciidoc(1)</code>
|
|
1742
|
+
as a filter to process cell contents.
|
|
1743
|
+
</dd><dt><span class="term">
|
|
1744
|
+
literal
|
|
1745
|
+
</span></dt><dd>
|
|
1746
|
+
No text formatting; monospaced font; all line breaks are retained
|
|
1747
|
+
(like <span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>LiteralBlock</em></span>).
|
|
1748
|
+
</dd><dt><span class="term">
|
|
1749
|
+
verse
|
|
1750
|
+
</span></dt><dd>
|
|
1751
|
+
Text formatting; all line breaks are retained (c.f. <span class="emphasis"><em>AsciiDoc</em></span> delimited
|
|
1752
|
+
block <span class="emphasis"><em>verse</em></span> style).
|
|
1753
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X72"></a>18.6. Markup attributes</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> makes a number of attributes available to table markup
|
|
1754
|
+
templates and tags. Both absolute and percentage width values are
|
|
1755
|
+
available. Column specific attributes are available when substituting
|
|
1756
|
+
the <span class="emphasis"><em>colspec</em></span> cell data tags.</p><div class="variablelist"><dl><dt><span class="term">
|
|
1757
|
+
pageunits
|
|
1758
|
+
</span></dt><dd>
|
|
1759
|
+
Only used by DocBook, defaults to <span class="emphasis"><em>pt</em></span>.
|
|
1760
|
+
</dd><dt><span class="term">
|
|
1761
|
+
pagewidth
|
|
1762
|
+
</span></dt><dd>
|
|
1763
|
+
The nominal output page width in <span class="emphasis"><em>pageunit</em></span> units. Used to calculate
|
|
1764
|
+
table and column widths. Only used by DocBook, defaults to <span class="emphasis"><em>425</em></span>.
|
|
1765
|
+
</dd><dt><span class="term">
|
|
1766
|
+
tableabswidth
|
|
1767
|
+
</span></dt><dd>
|
|
1768
|
+
Integer value calculated from <span class="emphasis"><em>width</em></span> and <span class="emphasis"><em>pagewidth</em></span> attributes.
|
|
1769
|
+
In <span class="emphasis"><em>pageunit</em></span> units.
|
|
1770
|
+
</dd><dt><span class="term">
|
|
1771
|
+
tablepcwidth
|
|
1772
|
+
</span></dt><dd>
|
|
1773
|
+
Table width expressed as a percentage of the available width. Integer
|
|
1774
|
+
value (0..100).
|
|
1775
|
+
</dd><dt><span class="term">
|
|
1776
|
+
colalign
|
|
1777
|
+
</span></dt><dd>
|
|
1778
|
+
<span class="emphasis"><em>left</em></span>, <span class="emphasis"><em>right</em></span> or <span class="emphasis"><em>center</em></span>.
|
|
1779
|
+
</dd><dt><span class="term">
|
|
1780
|
+
colabswidth
|
|
1781
|
+
</span></dt><dd>
|
|
1782
|
+
Integer value calculated from <span class="emphasis"><em>cols</em></span> column width, <span class="emphasis"><em>width</em></span> and
|
|
1783
|
+
<span class="emphasis"><em>pagewidth</em></span> attributes. In <span class="emphasis"><em>pageunit</em></span> units.
|
|
1784
|
+
</dd><dt><span class="term">
|
|
1785
|
+
colpcwidth
|
|
1786
|
+
</span></dt><dd>
|
|
1787
|
+
Column width expressed as a percentage of the table width. Integer
|
|
1788
|
+
value (0..100).
|
|
1789
|
+
</dd><dt><span class="term">
|
|
1790
|
+
colnumber
|
|
1791
|
+
</span></dt><dd>
|
|
1792
|
+
Integer value: <span class="emphasis"><em>1</em></span> for column 1, <span class="emphasis"><em>2</em></span> for column 2 …
|
|
1793
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_nested_tables"></a>18.7. Nested tables</h3></div></div></div><p>An alternative table syntax using a <span class="emphasis"><em>!</em></span> character instead of a <span class="emphasis"><em>|</em></span>
|
|
1794
|
+
character is provided to allow a single level of table nesting.
|
|
1795
|
+
Columns containing nested tables must use the <span class="emphasis"><em>asciidoc</em></span> style. An
|
|
1796
|
+
example can be found in <code class="literal">./examples/website/newtables.txt</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>When generating PDF nested tables using <code class="literal"><code class="literal">a2x(1)</code></code> you will need
|
|
1797
|
+
to use the <code class="literal">--no-xmllint</code> option. This is because the nested tables
|
|
1798
|
+
are not legal in DocBook (you have to use the DocBook 4 <span class="emphasis"><em>entrytbl</em></span>
|
|
1799
|
+
element). But both <span class="emphasis"><em>dblatex</em></span> (as of version 0.28) and <span class="emphasis"><em>FOP</em></span> (as of
|
|
1800
|
+
version 0.95beta) will process nested DocBook tables, but not
|
|
1801
|
+
<span class="emphasis"><em>entrytbl</em></span> elements.</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="X1"></a>19. Manpage Documents</h2></div></div></div><p>Sooner or later, if you program for a UNIX environment, you’re going
|
|
1802
|
+
to have to write a man page.</p><p>By observing a couple of additional conventions you can compose
|
|
1803
|
+
<span class="emphasis"><em>AsciiDoc</em></span> files that will translate to a DocBook refentry (man page)
|
|
1804
|
+
document. The resulting DocBook file can then be translated to the
|
|
1805
|
+
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
|
|
1806
|
+
<code class="literal">./doc</code> directory was used to generate both the
|
|
1807
|
+
<code class="literal">asciidoc.1.css-embedded.html</code> HTML file the <code class="literal">asciidoc.1</code> roff
|
|
1808
|
+
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
|
|
1809
|
+
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
|
|
1810
|
+
(<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
|
|
1811
|
+
name followed immediately by the manual section number in brackets,
|
|
1812
|
+
for example <span class="emphasis"><em>ASCIIDOC(1)</em></span>. The title name should not contain white
|
|
1813
|
+
space and the manual section number is a single digit optionally
|
|
1814
|
+
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
|
|
1815
|
+
contain a single paragraph (usually a single line) consisting of a
|
|
1816
|
+
list of one or more comma separated command name(s) separated from the
|
|
1817
|
+
command purpose by a dash character. The dash must have at least one
|
|
1818
|
+
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 class="link" href="#X60" title="26. Intrinsic Attributes">intrinsic attributes</a> you can assign DocBook
|
|
1819
|
+
<a class="ulink" href="http://www.docbook.org/tdg5/en/html/refmiscinfo.html" target="_top">refmiscinfo</a>
|
|
1820
|
+
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>
|
|
1821
|
+
<code class="literal">{mansource}</code>, <code class="literal">{manversion}</code> and <code class="literal">{manmanual}</code> attributes
|
|
1822
|
+
respectively. This example is from the <span class="emphasis"><em>AsciiDoc</em></span> header of a man page
|
|
1823
|
+
source file:</p><pre class="literallayout">:man source: AsciiDoc
|
|
1824
|
+
:man version: {revision}
|
|
1825
|
+
: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="X78"></a>20. Mathematical Formulas</h2></div></div></div><p>The <span class="emphasis"><em>asciimath</em></span> and <span class="emphasis"><em>latexmath</em></span> <a class="link" href="#X77" title="17.4. Passthrough macros">passthrough macros</a> along with
|
|
1826
|
+
<span class="emphasis"><em>asciimath</em></span> and <span class="emphasis"><em>latexmath</em></span> <a class="link" href="#X76" title="12.6. Passthrough Blocks">passthrough blocks</a> provide a
|
|
1827
|
+
(backend dependent) mechanism for rendering mathematical formulas. You
|
|
1828
|
+
can use the following math markups:</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>The <span class="emphasis"><em>latexmath</em></span> macro used to include <span class="emphasis"><em>LaTeX Math</em></span> in DocBook
|
|
1829
|
+
outputs is not the same as the <span class="emphasis"><em>latexmath</em></span> macro used to include
|
|
1830
|
+
<span class="emphasis"><em>LaTeX MathML</em></span> in XHTML outputs. <span class="emphasis"><em>LaTeX Math</em></span> applies to DocBook
|
|
1831
|
+
outputs that are processed by <a class="link" href="#">dblatex</a> and is normally used to
|
|
1832
|
+
generate PDF files. <span class="emphasis"><em>LaTeXMathML</em></span> is very much a subset of <span class="emphasis"><em>LaTeX
|
|
1833
|
+
Math</em></span> and applies to XHTML documents.</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_latex_math"></a>20.1. LaTeX Math</h3></div></div></div><p><a class="ulink" href="ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf" target="_top">LaTeX
|
|
1834
|
+
math</a> can be included in documents that are processed by
|
|
1835
|
+
<a class="link" href="#">dblatex(1)</a>. Example inline formula:</p><pre class="literallayout">latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]</pre><p>For more examples see the <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span>
|
|
1836
|
+
website</a> or the distributed <code class="literal">doc/latexmath.txt</code> file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_asciimathml"></a>20.2. ASCIIMathML</h3></div></div></div><p><a class="ulink" href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html" target="_top">ASCIIMathML</a>
|
|
1837
|
+
formulas can be included in XHTML documents generated using the
|
|
1838
|
+
<span class="emphasis"><em>xhtml11</em></span> backend. To enable ASCIIMathML support you must define the
|
|
1839
|
+
<span class="emphasis"><em>asciimath</em></span> attribute, for example using the <code class="literal">-a asciimath</code>
|
|
1840
|
+
command-line option. Example inline formula:</p><pre class="literallayout">asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]</pre><p>For more examples see the <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span>
|
|
1841
|
+
website</a> or the distributed <code class="literal">doc/asciimathml.txt</code> file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_latexmathml"></a>20.3. LaTeXMathML</h3></div></div></div><p><span class="emphasis"><em>LaTeXMathML</em></span> allows LaTeX Math style formulas to be included in XHTML
|
|
1842
|
+
documents generated using the <span class="emphasis"><em>AsciiDoc</em></span> <span class="emphasis"><em>xhtml11</em></span> backend. <span class="emphasis"><em>AsciiDoc</em></span>
|
|
1843
|
+
uses the
|
|
1844
|
+
<a class="ulink" href="http://www.maths.nottingham.ac.uk/personal/drw/lm.html" target="_top">original
|
|
1845
|
+
LaTeXMathML</a> by Douglas Woodall. <span class="emphasis"><em>LaTeXMathML</em></span> is derived from
|
|
1846
|
+
ASCIIMathML and is for users who are more familiar with or prefer
|
|
1847
|
+
using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
|
|
1848
|
+
differences are documented on the <span class="emphasis"><em>LaTeXMathML</em></span> web page). To enable
|
|
1849
|
+
LaTeXMathML support you must define the <span class="emphasis"><em>latexmath</em></span> attribute, for
|
|
1850
|
+
example using the <code class="literal">-a latexmath</code> command-line option. Example inline
|
|
1851
|
+
formula:</p><pre class="literallayout">latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]</pre><p>For more examples see the <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span>
|
|
1852
|
+
website</a> or the distributed <code class="literal">doc/latexmathml.txt</code> file.</p><p>There are more examples on the
|
|
1853
|
+
<a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span> website</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_mathml"></a>20.4. MathML</h3></div></div></div><p><a class="ulink" href="http://www.w3.org/Math/" target="_top">MathML</a> is a low level XML markup for
|
|
1854
|
+
mathematics. <span class="emphasis"><em>AsciiDoc</em></span> has no macros for MathML but users familiar with
|
|
1855
|
+
this markup could use passthrough macros and passthrough blocks to
|
|
1856
|
+
include MathML in output documents.</p></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>21. Configuration Files</h2></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> source file syntax and output file markup is largely
|
|
1857
|
+
controlled by a set of cascading, text based, configuration files. At
|
|
1858
|
+
runtime The <span class="emphasis"><em>AsciiDoc</em></span> default configuration files are combined with
|
|
1859
|
+
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>21.1. Configuration File Format</h3></div></div></div><p>Configuration files contain named sections. Each section begins with a
|
|
1860
|
+
section name in square brackets []. The section body consists of the
|
|
1861
|
+
lines of text between adjacent section headings.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
1862
|
+
Section names consist of one or more alphanumeric, underscore or
|
|
1863
|
+
dash characters and cannot begin or end with a dash.
|
|
1864
|
+
</li><li>
|
|
1865
|
+
Lines starting with a hash character "#" are treated as comments and
|
|
1866
|
+
ignored.
|
|
1867
|
+
</li><li>
|
|
1868
|
+
Same named sections and section entries override previously loaded
|
|
1869
|
+
sections and section entries (this is sometimes referred to as
|
|
1870
|
+
<span class="emphasis"><em>cascading</em></span>). Consequently, downstream configuration files need
|
|
1871
|
+
only contain those sections and section entries that need to be
|
|
1872
|
+
overridden.
|
|
1873
|
+
</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
|
|
1874
|
+
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
|
|
1875
|
+
default configuration files in the <span class="emphasis"><em>AsciiDoc</em></span> distribution in
|
|
1876
|
+
conjunction with <code class="literal">asciidoc(1)</code> output files. You can view configuration
|
|
1877
|
+
file load sequence by turning on the <code class="literal">asciidoc(1)</code> <code class="literal">-v</code> (<code class="literal">--verbose</code>)
|
|
1878
|
+
command-line option.</p></td></tr></table></div><p><span class="emphasis"><em>AsciiDoc</em></span> reserves the following section names for specific purposes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1879
|
+
miscellaneous
|
|
1880
|
+
</span></dt><dd>
|
|
1881
|
+
Configuration options that don’t belong anywhere else.
|
|
1882
|
+
</dd><dt><span class="term">
|
|
1883
|
+
attributes
|
|
1884
|
+
</span></dt><dd>
|
|
1885
|
+
Attribute name/value entries.
|
|
1886
|
+
</dd><dt><span class="term">
|
|
1887
|
+
specialcharacters
|
|
1888
|
+
</span></dt><dd>
|
|
1889
|
+
Special characters reserved by the backend markup.
|
|
1890
|
+
</dd><dt><span class="term">
|
|
1891
|
+
tags
|
|
1892
|
+
</span></dt><dd>
|
|
1893
|
+
Backend markup tags.
|
|
1894
|
+
</dd><dt><span class="term">
|
|
1895
|
+
quotes
|
|
1896
|
+
</span></dt><dd>
|
|
1897
|
+
Definitions for quoted inline character formatting.
|
|
1898
|
+
</dd><dt><span class="term">
|
|
1899
|
+
specialwords
|
|
1900
|
+
</span></dt><dd>
|
|
1901
|
+
Lists of words and phrases singled out for special markup.
|
|
1902
|
+
</dd><dt><span class="term">
|
|
1903
|
+
replacements, replacements2
|
|
1904
|
+
</span></dt><dd>
|
|
1905
|
+
Find and replace substitution definitions.
|
|
1906
|
+
</dd><dt><span class="term">
|
|
1907
|
+
specialsections
|
|
1908
|
+
</span></dt><dd>
|
|
1909
|
+
Used to single out special section names for specific markup.
|
|
1910
|
+
</dd><dt><span class="term">
|
|
1911
|
+
macros
|
|
1912
|
+
</span></dt><dd>
|
|
1913
|
+
Macro syntax definitions.
|
|
1914
|
+
</dd><dt><span class="term">
|
|
1915
|
+
titles
|
|
1916
|
+
</span></dt><dd>
|
|
1917
|
+
Heading, section and block title definitions.
|
|
1918
|
+
</dd><dt><span class="term">
|
|
1919
|
+
paradef-*
|
|
1920
|
+
</span></dt><dd>
|
|
1921
|
+
Paragraph element definitions.
|
|
1922
|
+
</dd><dt><span class="term">
|
|
1923
|
+
blockdef-*
|
|
1924
|
+
</span></dt><dd>
|
|
1925
|
+
DelimitedBlock element definitions.
|
|
1926
|
+
</dd><dt><span class="term">
|
|
1927
|
+
listdef-*
|
|
1928
|
+
</span></dt><dd>
|
|
1929
|
+
List element definitions.
|
|
1930
|
+
</dd><dt><span class="term">
|
|
1931
|
+
listtags-*
|
|
1932
|
+
</span></dt><dd>
|
|
1933
|
+
List element tag definitions.
|
|
1934
|
+
</dd><dt><span class="term">
|
|
1935
|
+
tabledef-*
|
|
1936
|
+
</span></dt><dd>
|
|
1937
|
+
Table element definitions.
|
|
1938
|
+
</dd><dt><span class="term">
|
|
1939
|
+
tabletags-*
|
|
1940
|
+
</span></dt><dd>
|
|
1941
|
+
Table element tag definitions.
|
|
1942
|
+
</dd></dl></div><p>Each line of text in these sections is a <span class="emphasis"><em>section entry</em></span>. Section
|
|
1943
|
+
entries share the following syntax:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1944
|
+
name=value
|
|
1945
|
+
</span></dt><dd>
|
|
1946
|
+
The entry value is set to value.
|
|
1947
|
+
</dd><dt><span class="term">
|
|
1948
|
+
name=
|
|
1949
|
+
</span></dt><dd>
|
|
1950
|
+
The entry value is set to a zero length string.
|
|
1951
|
+
</dd><dt><span class="term">
|
|
1952
|
+
name!
|
|
1953
|
+
</span></dt><dd>
|
|
1954
|
+
The entry is undefined (deleted from the configuration). This
|
|
1955
|
+
syntax only applies to <span class="emphasis"><em>attributes</em></span> and <span class="emphasis"><em>miscellaneous</em></span>
|
|
1956
|
+
sections.
|
|
1957
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>Section entry behavior</b></p><ul type="disc"><li>
|
|
1958
|
+
All equals characters inside the <code class="literal">name</code> must be escaped with a
|
|
1959
|
+
backslash character.
|
|
1960
|
+
</li><li>
|
|
1961
|
+
<code class="literal">name</code> and <code class="literal">value</code> are stripped of leading and trailing white space.
|
|
1962
|
+
</li><li>
|
|
1963
|
+
Attribute names, tag entry names and markup template section names
|
|
1964
|
+
consist of one or more alphanumeric, underscore or dash characters.
|
|
1965
|
+
Names should not begin or end with a dash.
|
|
1966
|
+
</li><li>
|
|
1967
|
+
A blank configuration file section (one without any entries) deletes
|
|
1968
|
+
any preceding section with the same name (applies to non-markup
|
|
1969
|
+
template sections).
|
|
1970
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_miscellaneous_section"></a>21.2. Miscellaneous section</h3></div></div></div><p>The optional <code class="literal">[miscellaneous]</code> section specifies the following
|
|
1971
|
+
<code class="literal">name=value</code> options:</p><div class="variablelist"><dl><dt><span class="term">
|
|
1972
|
+
newline
|
|
1973
|
+
</span></dt><dd><p>
|
|
1974
|
+
Output file line termination characters. Can include any
|
|
1975
|
+
valid Python string escape sequences. The default value is
|
|
1976
|
+
<code class="literal">\r\n</code> (carriage return, line feed). Should not be quoted or
|
|
1977
|
+
contain explicit spaces (use <code class="literal">\x20</code> instead). For example:
|
|
1978
|
+
</p><pre class="literallayout">$ asciidoc -a 'newline=\n' -b docbook mydoc.txt</pre></dd><dt><span class="term">
|
|
1979
|
+
outfilesuffix
|
|
1980
|
+
</span></dt><dd>
|
|
1981
|
+
The default extension for the output file, for example
|
|
1982
|
+
<code class="literal">outfilesuffix=.html</code>. Defaults to backend name.
|
|
1983
|
+
</dd><dt><span class="term">
|
|
1984
|
+
tabsize
|
|
1985
|
+
</span></dt><dd>
|
|
1986
|
+
The number of spaces to expand tab characters, for example
|
|
1987
|
+
<code class="literal">tabsize=4</code>. Defaults to 8. A <span class="emphasis"><em>tabsize</em></span> of zero suppresses tab
|
|
1988
|
+
expansion (useful when piping included files through block
|
|
1989
|
+
filters). Included files can override this option using the
|
|
1990
|
+
<span class="emphasis"><em>tabsize</em></span> attribute.
|
|
1991
|
+
</dd><dt><span class="term">
|
|
1992
|
+
pagewidth, pageunits
|
|
1993
|
+
</span></dt><dd>
|
|
1994
|
+
These global table related options are documented in the
|
|
1995
|
+
<a class="link" href="#X4">Table Configuration File Definitions</a> sub-section.
|
|
1996
|
+
</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
|
|
1997
|
+
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><h3 class="title"><a id="_titles_section"></a>21.3. Titles section</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
1998
|
+
sectiontitle
|
|
1999
|
+
</span></dt><dd>
|
|
2000
|
+
Two line section title pattern. The entry value is a Python
|
|
2001
|
+
regular expression containing the named group <span class="emphasis"><em>title</em></span>.
|
|
2002
|
+
</dd><dt><span class="term">
|
|
2003
|
+
underlines
|
|
2004
|
+
</span></dt><dd><p>
|
|
2005
|
+
A comma separated list of document and section title underline
|
|
2006
|
+
character pairs starting with the section level 0 and ending
|
|
2007
|
+
with section level 4 underline. The default setting is:
|
|
2008
|
+
</p><pre class="literallayout">underlines="==","--","~~","^^","++"</pre></dd><dt><span class="term">
|
|
2009
|
+
sect0…sect4
|
|
2010
|
+
</span></dt><dd>
|
|
2011
|
+
One line section title patterns. The entry value is a Python
|
|
2012
|
+
regular expression containing the named group <span class="emphasis"><em>title</em></span>.
|
|
2013
|
+
</dd><dt><span class="term">
|
|
2014
|
+
blocktitle
|
|
2015
|
+
</span></dt><dd>
|
|
2016
|
+
<a class="link" href="#X42" title="9. BlockTitles">BlockTitle element</a> pattern. The entry value is a
|
|
2017
|
+
Python regular expression containing the named group <span class="emphasis"><em>title</em></span>.
|
|
2018
|
+
</dd><dt><span class="term">
|
|
2019
|
+
subs
|
|
2020
|
+
</span></dt><dd>
|
|
2021
|
+
A comma separated list of substitutions that are performed on
|
|
2022
|
+
the document header and section titles. Defaults to <span class="emphasis"><em>normal</em></span>
|
|
2023
|
+
substitution.
|
|
2024
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_tags_section"></a>21.4. Tags section</h3></div></div></div><p>The <code class="literal">[tags]</code> section contains backend tag definitions (one per
|
|
2025
|
+
line). Tags are used to translate <span class="emphasis"><em>AsciiDoc</em></span> elements to backend
|
|
2026
|
+
markup.</p><p>An <span class="emphasis"><em>AsciiDoc</em></span> tag definition is formatted like
|
|
2027
|
+
<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
|
|
2028
|
+
emphasized text from the <span class="emphasis"><em>AsciiDoc</em></span> input file and writes the result to
|
|
2029
|
+
the output file.</p><p>Use the <code class="literal">{brvbar}</code> attribute reference if you need to include a | pipe
|
|
2030
|
+
character inside tag text.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_attributes_section"></a>21.5. Attributes section</h3></div></div></div><p>The optional <code class="literal">[attributes]</code> section contains predefined attributes.</p><p>If the attribute value requires leading or trailing spaces then the
|
|
2031
|
+
text text should be enclosed in quotation mark (") characters.</p><p>To delete a attribute insert a <code class="literal">name!</code> entry in a downstream
|
|
2032
|
+
configuration file or use the <code class="literal">asciidoc(1)</code> <code class="literal">--attribute name!</code>
|
|
2033
|
+
command-line option (an attribute name suffixed with a <code class="literal">!</code> character
|
|
2034
|
+
deletes the attribute)</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_special_characters_section"></a>21.6. Special Characters section</h3></div></div></div><p>The <code class="literal">[specialcharacters]</code> section specifies how to escape characters
|
|
2035
|
+
reserved by the backend markup. Each translation is specified on a
|
|
2036
|
+
single line formatted like:</p><pre class="literallayout">special_character=translated_characters</pre><p>Special characters are normally confined to those that resolve
|
|
2037
|
+
markup ambiguity (in the case of SGML/XML markups the ampersand, less
|
|
2038
|
+
than and greater than characters). The following example causes all
|
|
2039
|
+
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><h3 class="title"><a id="_quoted_text_section"></a>21.7. Quoted Text section</h3></div></div></div><p>Quoting is used primarily for text formatting. The <code class="literal">[quotes]</code> section
|
|
2040
|
+
defines <span class="emphasis"><em>AsciiDoc</em></span> quoting characters and their corresponding backend
|
|
2041
|
+
markup tags. Each section entry value is the name of a of a <code class="literal">[tags]</code>
|
|
2042
|
+
section entry. The entry name is the character (or characters) that
|
|
2043
|
+
quote the text. The following examples are taken from <span class="emphasis"><em>AsciiDoc</em></span>
|
|
2044
|
+
configuration files:</p><pre class="literallayout">[quotes]
|
|
2045
|
+
_=emphasis</pre><pre class="literallayout">[tags]
|
|
2046
|
+
emphasis=<em>|</em></pre><p>You can specify the left and right quote strings separately by
|
|
2047
|
+
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
|
|
2048
|
+
superscripts or subscripts put the following in a custom configuration
|
|
2049
|
+
file or edit the global <code class="literal">asciidoc.conf</code> configuration file:</p><pre class="literallayout">[quotes]
|
|
2050
|
+
^=
|
|
2051
|
+
~=</pre><p><a class="link" href="#X52" title="7.1.1. Constrained and Unconstrained Quotes">Unconstrained quotes</a> are differentiated by prefixing the tag
|
|
2052
|
+
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>
|
|
2053
|
+
Quote characters must be non-alphanumeric.
|
|
2054
|
+
</li><li>
|
|
2055
|
+
To minimize quoting ambiguity try not to use the same quote
|
|
2056
|
+
characters in different quote types.
|
|
2057
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_special_words_section"></a>21.8. Special Words section</h3></div></div></div><p>The <code class="literal">[specialwords]</code> section is used to single out words and phrases
|
|
2058
|
+
that you want to consistently format in some way throughout your
|
|
2059
|
+
document without having to repeatedly specify the markup. The name of
|
|
2060
|
+
each entry corresponds to a markup template section and the entry
|
|
2061
|
+
value consists of a list of words and phrases to be marked up. For
|
|
2062
|
+
example:</p><pre class="literallayout">[specialwords]
|
|
2063
|
+
strongwords=NOTE: IMPORTANT:</pre><pre class="literallayout">[strongwords]
|
|
2064
|
+
<strong>{words}</strong></pre><p>The examples specifies that any occurrence of <code class="literal">NOTE:</code> or <code class="literal">IMPORTANT:</code>
|
|
2065
|
+
should appear in a bold font.</p><p>Words and word phrases are treated as Python regular expressions: for
|
|
2066
|
+
example, the word <code class="literal">^NOTE:</code> would only match <code class="literal">NOTE:</code> if appeared at
|
|
2067
|
+
the start of a line.</p><p><span class="emphasis"><em>AsciiDoc</em></span> comes with three built-in Special Word types:
|
|
2068
|
+
<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
|
|
2069
|
+
corresponding (backend specific) markup template section. Edit the
|
|
2070
|
+
configuration files to customize existing Special Words and to add new
|
|
2071
|
+
ones.</p><div class="itemizedlist"><p class="title"><b>Special word behavior</b></p><ul type="disc"><li>
|
|
2072
|
+
Word list entries must be separated by space characters.
|
|
2073
|
+
</li><li>
|
|
2074
|
+
Word list entries with embedded spaces should be enclosed in quotation (")
|
|
2075
|
+
characters.
|
|
2076
|
+
</li><li>
|
|
2077
|
+
A <code class="literal">[specialwords]</code> section entry of the form
|
|
2078
|
+
<code class="literal">name=word1 [word2…]</code> adds words to existing <code class="literal">name</code> entries.
|
|
2079
|
+
</li><li>
|
|
2080
|
+
A <code class="literal">[specialwords]</code> section entry of the form <code class="literal">name</code> undefines
|
|
2081
|
+
(deletes) all existing <code class="literal">name</code> words.
|
|
2082
|
+
</li><li>
|
|
2083
|
+
Since word list entries are processed as Python regular expressions
|
|
2084
|
+
you need to be careful to escape regular expression special
|
|
2085
|
+
characters.
|
|
2086
|
+
</li><li>
|
|
2087
|
+
By default Special Words are substituted before Inline Macros, this
|
|
2088
|
+
may lead to undesirable consequences. For example the special word
|
|
2089
|
+
<code class="literal">foobar</code> would be expanded inside the macro call
|
|
2090
|
+
<code class="literal">http://www.foobar.com[]</code>. A possible solution is to emphasize
|
|
2091
|
+
whole words only by defining the word using regular expression
|
|
2092
|
+
characters, for example <code class="literal">\bfoobar\b</code>.
|
|
2093
|
+
</li><li>
|
|
2094
|
+
If the first matched character of a special word is a backslash then
|
|
2095
|
+
the remaining characters are output without markup i.e. the
|
|
2096
|
+
backslash can be used to escape special word markup. For example
|
|
2097
|
+
the special word <code class="literal">\\?\b[Tt]en\b</code> will mark up the words <code class="literal">Ten</code> and
|
|
2098
|
+
<code class="literal">ten</code> only if they are not preceded by a backslash.
|
|
2099
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X10"></a>21.9. Replacements section</h3></div></div></div><p><code class="literal">[replacements]</code> and <code class="literal">[replacements2]</code> configuration file entries
|
|
2100
|
+
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
|
|
2101
|
+
contain Python regular expression group references.</p><p>Use Replacement shortcuts for often used macro references, for
|
|
2102
|
+
example (the second replacement allows us to backslash escape the
|
|
2103
|
+
macro name):</p><pre class="literallayout">NEW!=image:./images/smallnew.png[New!]
|
|
2104
|
+
\\NEW!=NEW!</pre><div class="itemizedlist"><p class="title"><b>Replacement behavior</b></p><ul type="disc"><li>
|
|
2105
|
+
The built-in replacements can be escaped with a backslash.
|
|
2106
|
+
</li><li>
|
|
2107
|
+
If the find or replace text has leading or trailing spaces then the
|
|
2108
|
+
text should be enclosed in quotation (") characters.
|
|
2109
|
+
</li><li>
|
|
2110
|
+
Since the find text is processed as a regular expression you need to
|
|
2111
|
+
be careful to escape regular expression special characters.
|
|
2112
|
+
</li><li>
|
|
2113
|
+
Replacements are performed in the same order they appear in the
|
|
2114
|
+
configuration file replacements section.
|
|
2115
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_markup_template_sections"></a>21.10. Markup Template Sections</h3></div></div></div><p>Markup template sections supply backend markup for translating
|
|
2116
|
+
<span class="emphasis"><em>AsciiDoc</em></span> elements. Since the text is normally backend dependent
|
|
2117
|
+
you’ll find these sections in the backend specific configuration
|
|
2118
|
+
files. Template sections differ from other sections in that they
|
|
2119
|
+
contain a single block of text instead of per line <span class="emphasis"><em>name=value</em></span>
|
|
2120
|
+
entries. A markup template section body can contain:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2121
|
+
Attribute references
|
|
2122
|
+
</li><li>
|
|
2123
|
+
System macro calls.
|
|
2124
|
+
</li><li>
|
|
2125
|
+
A document content placeholder
|
|
2126
|
+
</li></ul></div><p>The document content placeholder is a single | character and is
|
|
2127
|
+
replaced by text from the source element. Use the <code class="literal">{brvbar}</code>
|
|
2128
|
+
attribute reference if you need a literal | character in the template.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X27"></a>21.11. Configuration File Names and Locations</h3></div></div></div><p>Configuration files have a <code class="literal">.conf</code> file name extension; they are
|
|
2129
|
+
loaded implicitly (using predefined file names and locations) or
|
|
2130
|
+
explicitly (using the <code class="literal">asciidoc(1)</code> <code class="literal">-f</code> (<code class="literal">--conf-file</code>) command-line
|
|
2131
|
+
option).</p><p>Implicit configuration files are loaded from the following directories
|
|
2132
|
+
in the following order:</p><div class="orderedlist"><ol type="1"><li>
|
|
2133
|
+
The global configuration directory (normally <code class="literal">/etc/asciidoc</code> or
|
|
2134
|
+
<code class="literal">/usr/local/etc/asciidoc</code>) if it exists.
|
|
2135
|
+
</li><li>
|
|
2136
|
+
The directory containing the asciidoc executable.
|
|
2137
|
+
</li><li>
|
|
2138
|
+
The user’s <code class="literal">$HOME/.asciidoc</code> directory (if it exists).
|
|
2139
|
+
</li><li>
|
|
2140
|
+
The directory containing the <span class="emphasis"><em>AsciiDoc</em></span> source file.
|
|
2141
|
+
</li></ol></div><p>The following implicit configuration files from each of the above
|
|
2142
|
+
locations are loaded in the following order:</p><div class="orderedlist"><ol type="1"><li>
|
|
2143
|
+
<code class="literal">asciidoc.conf</code>
|
|
2144
|
+
</li><li>
|
|
2145
|
+
<code class="literal"><backend>.conf</code>
|
|
2146
|
+
</li><li>
|
|
2147
|
+
<code class="literal"><backend>-<doctype>.conf</code>
|
|
2148
|
+
</li><li>
|
|
2149
|
+
<code class="literal">lang-<lang>.conf</code>
|
|
2150
|
+
</li></ol></div><p>Where <code class="literal"><backend></code> and <code class="literal"><doctype></code> are values specified by the
|
|
2151
|
+
<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
|
|
2152
|
+
options. <code class="literal"><lang></code> is the value of the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">lang</code> attribute
|
|
2153
|
+
(defaults to <code class="literal">en</code> (English)).</p><p>Finally, configuration files named like the source file will be
|
|
2154
|
+
automatically loaded if they are found in the source file directory.
|
|
2155
|
+
For example if the source file is <code class="literal">mydoc.txt</code> and the
|
|
2156
|
+
<code class="literal">--backend=html4</code> option is used then <code class="literal">asciidoc(1)</code> will look for
|
|
2157
|
+
<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
|
|
2158
|
+
skipped.</p><p>The user can explicitly specify additional configuration files using
|
|
2159
|
+
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>
|
|
2160
|
+
option can be specified multiple times, in which case configuration
|
|
2161
|
+
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
|
|
2162
|
+
order:</p><div class="orderedlist"><ol type="1"><li><p>
|
|
2163
|
+
First default global configuration files from the asciidoc program
|
|
2164
|
+
directory are loaded:
|
|
2165
|
+
</p><pre class="literallayout">asciidoc.conf
|
|
2166
|
+
xhtml11.conf</pre></li><li><p>
|
|
2167
|
+
Then, from the users home <code class="literal">~/.asciidoc</code> directory. This is were
|
|
2168
|
+
you put customization specific to your own asciidoc documents:
|
|
2169
|
+
</p><pre class="literallayout">asciidoc.conf
|
|
2170
|
+
xhtml11.conf
|
|
2171
|
+
xhtml11-article.conf</pre></li><li><p>
|
|
2172
|
+
Next from the source document project directory (the first three
|
|
2173
|
+
apply to all documents in the directory, the last two are specific
|
|
2174
|
+
to the mydoc.txt document):
|
|
2175
|
+
</p><pre class="literallayout">asciidoc.conf
|
|
2176
|
+
xhtml11.conf
|
|
2177
|
+
xhtml11-article.conf
|
|
2178
|
+
mydoc.conf
|
|
2179
|
+
mydoc-xhtml11.conf</pre></li><li><p>
|
|
2180
|
+
Finally the file specified by the <code class="literal">-f</code> command-line option is
|
|
2181
|
+
loaded:
|
|
2182
|
+
</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
|
|
2183
|
+
which configuration files are loaded and the order in which they are
|
|
2184
|
+
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>22. 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>
|
|
2185
|
+
and is used for textual substitution in <span class="emphasis"><em>AsciiDoc</em></span> documents and
|
|
2186
|
+
configuration files. An attribute reference (an attribute name
|
|
2187
|
+
enclosed in braces) is replaced by its corresponding attribute
|
|
2188
|
+
value.</p><p>There are four sources of document attributes (from highest to lowest
|
|
2189
|
+
precedence):</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2190
|
+
Command-line attributes.
|
|
2191
|
+
</li><li>
|
|
2192
|
+
AttributeEntry, AttributeList, Macro and BlockId elements.
|
|
2193
|
+
</li><li>
|
|
2194
|
+
Configuration file <code class="literal">[attributes]</code> sections.
|
|
2195
|
+
</li><li>
|
|
2196
|
+
Intrinsic attributes.
|
|
2197
|
+
</li></ul></div><p>Within each of these divisions the last processed entry takes
|
|
2198
|
+
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
|
|
2199
|
+
attribute reference is dropped. This property is used extensively in
|
|
2200
|
+
<span class="emphasis"><em>AsciiDoc</em></span> configuration files to facilitate conditional markup
|
|
2201
|
+
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>23. Attribute Entries</h2></div></div></div><p>The <code class="literal">AttributeEntry</code> block element allows document attributes to be
|
|
2202
|
+
assigned within an <span class="emphasis"><em>AsciiDoc</em></span> document. Attribute entries are added to
|
|
2203
|
+
the global document attributes dictionary. The attribute name/value
|
|
2204
|
+
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
|
|
2205
|
+
<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 behavior</b></p><ul type="disc"><li>
|
|
2206
|
+
The attribute entry line begins with colon — no white space allowed
|
|
2207
|
+
in left margin.
|
|
2208
|
+
</li><li>
|
|
2209
|
+
<span class="emphasis"><em>AsciiDoc</em></span> converts the <code class="literal"><name></code> to a legal attribute name (lower
|
|
2210
|
+
case, alphanumeric and dash characters only — all other characters
|
|
2211
|
+
deleted). This allows more reader friendly text to be used.
|
|
2212
|
+
</li><li>
|
|
2213
|
+
Leading and trailing white space is stripped from the <code class="literal"><value></code>.
|
|
2214
|
+
</li><li>
|
|
2215
|
+
If the <code class="literal"><value></code> is blank then the corresponding attribute value is
|
|
2216
|
+
set to an empty string.
|
|
2217
|
+
</li><li>
|
|
2218
|
+
Special characters in the entry <code class="literal"><value></code> are substituted. You can
|
|
2219
|
+
enter special characters using character entity values, for example
|
|
2220
|
+
<code class="literal">&amp;</code>.
|
|
2221
|
+
</li><li>
|
|
2222
|
+
Attribute references contained in the entry <code class="literal"><value></code> will be
|
|
2223
|
+
expanded.
|
|
2224
|
+
</li><li>
|
|
2225
|
+
By default AttributeEntry values are substituted for
|
|
2226
|
+
<code class="literal">specialcharacters</code> and <code class="literal">attributes</code> (see above), if you want a
|
|
2227
|
+
different AttributeEntry substitution set the <code class="literal">attributeentry-subs</code>
|
|
2228
|
+
attribute.
|
|
2229
|
+
</li><li>
|
|
2230
|
+
Attribute entries in the document Header are available for header
|
|
2231
|
+
markup template substitution.
|
|
2232
|
+
</li><li>
|
|
2233
|
+
Attribute elements override configuration file and intrinsic
|
|
2234
|
+
attributes but do not override command-line attributes.
|
|
2235
|
+
Here are some more attribute entry examples:
|
|
2236
|
+
</li></ul></div><pre class="screen">AsciiDoc User Manual
|
|
2237
|
+
====================
|
|
2238
|
+
:Author: Stuart Rackham
|
|
2239
|
+
:Email: srackham@gmail.com
|
|
2240
|
+
:Date: April 23, 2004
|
|
2241
|
+
:Revision: 5.1.1
|
|
2242
|
+
:Key words: linux, ralink, debian, wireless
|
|
2243
|
+
:Revision history:</pre><p>Which creates these attributes:</p><pre class="literallayout">{author}, {firstname}, {lastname}, {authorinitials}, {email},
|
|
2244
|
+
{date}, {revision}, {keywords}, {revisionhistory}</pre><p>The preceding example is equivalent to the standard <span class="emphasis"><em>AsciiDoc</em></span> two line
|
|
2245
|
+
document header. Actually it’s a little bit different with the
|
|
2246
|
+
addition of the <code class="literal">{keywords}</code> and <code class="literal">{revisionhistory}</code> attributes
|
|
2247
|
+
<sup>[<a id="id2541424" href="#ftn.id2541424" class="footnote">4</a>]</sup>.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_setting_configuration_entries"></a>23.1. Setting configuration entries</h3></div></div></div><p>A variant of the Attribute Entry syntax allows configuration file
|
|
2248
|
+
entries to be set from within an <span class="emphasis"><em>AsciiDoc</em></span> document:</p><pre class="literallayout">:<section_name>.<entry_name>: <entry_value></pre><p>Where <code class="literal"><section_name></code> is the configuration section name,
|
|
2249
|
+
<code class="literal"><entry_name></code> is the name of the entry and <code class="literal"><entry_value></code> is the
|
|
2250
|
+
optional entry value. This example sets the default labeled list style
|
|
2251
|
+
to <span class="emphasis"><em>horizontal</em></span>:</p><pre class="literallayout">:listdef-labeled.style: horizontal</pre><p>It is exactly equivalent to a configuration file containing:</p><pre class="literallayout">[listdef-labeled]
|
|
2252
|
+
style=horizontal</pre><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
|
|
2253
|
+
break paragraph flow and readability suffers. The problem is
|
|
2254
|
+
compounded by redundancy if the same name is used repeatedly.
|
|
2255
|
+
Attribute entries can be used to make your documents easier to read
|
|
2256
|
+
and write, here are some examples:</p><pre class="literallayout">:1: http://freshmeat.net/projects/asciidoc/
|
|
2257
|
+
:homepage: http://hg.sharesource.org/asciidoc/[AsciiDoc home page]
|
|
2258
|
+
:new: image:./images/smallnew.png[]
|
|
2259
|
+
:footnote1: footnote:[A meaningless latin term]</pre><pre class="literallayout">Using previously defined attributes: See the {1}[Freshmeat summary]
|
|
2260
|
+
or the {homepage} for something new {new}. Lorem ispum {footnote1}.</pre><div class="itemizedlist"><p class="title"><b>Note</b></p><ul type="disc"><li>
|
|
2261
|
+
The attribute entry definition must precede it’s usage.
|
|
2262
|
+
</li><li>
|
|
2263
|
+
You are not limited to URLs or file names, entire macro calls or
|
|
2264
|
+
arbitrary lines of text can be abbreviated.
|
|
2265
|
+
</li><li>
|
|
2266
|
+
Shared attributes entries could be grouped into a separate file and
|
|
2267
|
+
<a class="link" href="#X63" title="17.3.1. Include Macros">included</a> in multiple documents.
|
|
2268
|
+
</li></ul></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="X21"></a>24. Attribute Lists</h2></div></div></div><p>An attribute list is a comma separated list of attribute values. The
|
|
2269
|
+
entire list is enclosed in square brackets. Attribute lists are used
|
|
2270
|
+
to pass parameters to macros, blocks and inline quotes:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2271
|
+
The list consists of zero or more positional attribute values
|
|
2272
|
+
followed by zero or more named attribute values.
|
|
2273
|
+
</li><li>
|
|
2274
|
+
Attribute values are enclosed in quotation mark (") characters.
|
|
2275
|
+
</li><li>
|
|
2276
|
+
If the attribute list only contains positional attribute values and
|
|
2277
|
+
the values contain no commas then quoting is unnecessary.
|
|
2278
|
+
</li></ul></div><p>Here are three examples (a single unquoted positional attribute; three
|
|
2279
|
+
unquoted attribute values; one positional attribute followed by two
|
|
2280
|
+
named attributes):</p><pre class="literallayout">[Hello]
|
|
2281
|
+
[quote, Bertrand Russell, The World of Mathematics (1956)]
|
|
2282
|
+
["22 times", backcolor="#0e0e0e", options="noborders,wide"]</pre><div class="itemizedlist"><p class="title"><b>Attribute list behavior</b></p><ul type="disc"><li>
|
|
2283
|
+
If one or more attribute values contains a comma the all values must
|
|
2284
|
+
be quoted (enclosed in quotation characters).
|
|
2285
|
+
</li><li>
|
|
2286
|
+
If the list contains any named or quoted attributes then all string
|
|
2287
|
+
attribute values must be quoted.
|
|
2288
|
+
</li><li>
|
|
2289
|
+
To include a quotation mark (") character in a quoted attribute
|
|
2290
|
+
value the the quotation mark must be escaped with a backslash.
|
|
2291
|
+
</li><li>
|
|
2292
|
+
List attributes take precedence over existing attributes.
|
|
2293
|
+
</li><li>
|
|
2294
|
+
List attributes can only be referenced in configuration file markup
|
|
2295
|
+
templates and tags, they are not available inside the document.
|
|
2296
|
+
</li><li>
|
|
2297
|
+
Attribute references are allowed inside attribute lists — this is
|
|
2298
|
+
the only substitution performed on attribute lists.
|
|
2299
|
+
</li><li>
|
|
2300
|
+
Setting a named attribute to <code class="literal">None</code> undefines the attribute.
|
|
2301
|
+
</li><li>
|
|
2302
|
+
Positional attributes are referred to as <code class="literal">{1}</code>,<code class="literal">{2}</code>,<code class="literal">{3}</code>,…
|
|
2303
|
+
</li><li>
|
|
2304
|
+
Attribute <code class="literal">{0}</code> refers to the entire list (excluding the enclosing
|
|
2305
|
+
square brackets).
|
|
2306
|
+
</li><li>
|
|
2307
|
+
Attribute lists are evaluated as a list of Python function
|
|
2308
|
+
arguments. If this fails or any of the items do not evaluate to a
|
|
2309
|
+
string, a number or None then all list items are treated as string
|
|
2310
|
+
literals.
|
|
2311
|
+
</li></ul></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X75"></a>24.1. Options attribute</h3></div></div></div><p>If the attribute list contains an attribute named <code class="literal">options</code> it is
|
|
2312
|
+
processed as a comma separated list of option names:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2313
|
+
Each name generates an attribute named like <code class="literal"><option>-option</code> (where
|
|
2314
|
+
<code class="literal"><option></code> is the option name) with an empty string value. For
|
|
2315
|
+
example <code class="literal">[options="opt1,opt2,opt3"]</code> is equivalent to setting the
|
|
2316
|
+
following three attributes
|
|
2317
|
+
<code class="literal">[opt1-option="",opt2-option="",opt2-option=""]</code>.
|
|
2318
|
+
</li><li>
|
|
2319
|
+
If you define a an option attribute globally (for example with an
|
|
2320
|
+
<a class="link" href="#X18" title="23. Attribute Entries">attribute entry</a>) then it will apply to all elements in the
|
|
2321
|
+
document.
|
|
2322
|
+
</li><li>
|
|
2323
|
+
<span class="emphasis"><em>AsciiDoc</em></span> implements a number of predefined options which are listed
|
|
2324
|
+
in the <a class="link" href="#X74" title="F. Attribute Options">Attribute Options appendix</a>.
|
|
2325
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_macro_attribute_lists"></a>24.2. Macro Attribute lists</h3></div></div></div><p>Macros calls are suffixed with an attribute list. The list may be
|
|
2326
|
+
empty but it cannot be omitted. List entries are used to pass
|
|
2327
|
+
attribute values to macro markup templates.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_attributelist_element"></a>24.3. AttributeList Element</h3></div></div></div><p>An <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a> on a line by itself constitutes an
|
|
2328
|
+
<span class="emphasis"><em>AttributeList</em></span> block element, its attributes apply to the following
|
|
2329
|
+
block element. The list attributes are passed to the next block
|
|
2330
|
+
element for markup template substitution. Often the first list
|
|
2331
|
+
parameter is used to specify the element’s <a class="link" href="#X23" title="27.1. Styles">style</a>.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_attribute_references"></a>25. Attribute References</h2></div></div></div><p>An attribute references is an attribute name (possibly followed by an
|
|
2332
|
+
additional parameters) enclosed in braces. When an attribute
|
|
2333
|
+
reference is encountered it is evaluated and replaced by its
|
|
2334
|
+
corresponding text value. If the attribute is undefined the line
|
|
2335
|
+
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>
|
|
2336
|
+
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>
|
|
2337
|
+
You can suppress attribute reference expansion by placing a
|
|
2338
|
+
backslash character immediately in front of the opening brace
|
|
2339
|
+
character.
|
|
2340
|
+
</li><li>
|
|
2341
|
+
By default attribute references are not expanded in
|
|
2342
|
+
LiteralParagraphs, ListingBlocks or LiteralBlocks.
|
|
2343
|
+
</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>25.1. Simple Attributes References</h3></div></div></div><p>Simple attribute references take the form <code class="literal">{<name>}</code>. If the
|
|
2344
|
+
attribute name is defined its text value is substituted otherwise the
|
|
2345
|
+
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>25.2. Conditional Attribute References</h3></div></div></div><p>Additional parameters are used in conjunction with the attribute name
|
|
2346
|
+
to calculate a substitution value. Conditional attribute references
|
|
2347
|
+
take the following forms:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2348
|
+
<code class="literal">{<name>=<value>}</code>
|
|
2349
|
+
</span></dt><dd>
|
|
2350
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is
|
|
2351
|
+
undefined otherwise its value is substituted. <code class="literal"><value></code> can
|
|
2352
|
+
contain simple attribute references.
|
|
2353
|
+
</dd><dt><span class="term">
|
|
2354
|
+
<code class="literal">{<name>?<value>}</code>
|
|
2355
|
+
</span></dt><dd>
|
|
2356
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is defined
|
|
2357
|
+
otherwise an empty string is substituted. <code class="literal"><value></code> can
|
|
2358
|
+
contain simple attribute references.
|
|
2359
|
+
</dd><dt><span class="term">
|
|
2360
|
+
<code class="literal">{<name>!<value>}</code>
|
|
2361
|
+
</span></dt><dd>
|
|
2362
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is
|
|
2363
|
+
undefined otherwise an empty string is substituted. <code class="literal"><value></code>
|
|
2364
|
+
can contain simple attribute references.
|
|
2365
|
+
</dd><dt><span class="term">
|
|
2366
|
+
<code class="literal">{<name>#<value>}</code>
|
|
2367
|
+
</span></dt><dd>
|
|
2368
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is defined
|
|
2369
|
+
otherwise the undefined attribute entry causes the containing
|
|
2370
|
+
line to be dropped. <code class="literal"><value></code> can contain simple attribute
|
|
2371
|
+
references.
|
|
2372
|
+
</dd><dt><span class="term">
|
|
2373
|
+
<code class="literal">{<name>%<value>}</code>
|
|
2374
|
+
</span></dt><dd>
|
|
2375
|
+
<code class="literal"><value></code> is substituted if the attribute <code class="literal"><name></code> is not
|
|
2376
|
+
defined otherwise the containing line is dropped. <code class="literal"><value></code>
|
|
2377
|
+
can contain simple attribute references.
|
|
2378
|
+
</dd><dt><span class="term">
|
|
2379
|
+
<code class="literal">{<name>@<regexp>:<value1>[:<value2>]}</code>
|
|
2380
|
+
</span></dt><dd>
|
|
2381
|
+
<code class="literal"><value1></code> is substituted if the value of attribute <code class="literal"><name></code>
|
|
2382
|
+
matches the regular expression <code class="literal"><regexp></code> otherwise <code class="literal"><value2></code>
|
|
2383
|
+
is substituted. If attribute <code class="literal"><name></code> is not defined the
|
|
2384
|
+
containing line is dropped. If <code class="literal"><value2></code> is omitted an empty
|
|
2385
|
+
string is assumed. The values and the regular expression can
|
|
2386
|
+
contain simple attribute references. To embed colons in the
|
|
2387
|
+
values or the regular expression escape them with backslashes.
|
|
2388
|
+
</dd><dt><span class="term">
|
|
2389
|
+
<code class="literal">{<name>$<regexp>:<value1>[:<value2>]}</code>
|
|
2390
|
+
</span></dt><dd><p>
|
|
2391
|
+
Same behavior as the previous ternary attribute except for
|
|
2392
|
+
the following cases:
|
|
2393
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
2394
|
+
<code class="literal">{<name>$<regexp>:<value>}</code>
|
|
2395
|
+
</span></dt><dd>
|
|
2396
|
+
Substitutes <code class="literal"><value></code> if <code class="literal"><name></code> matches <code class="literal"><regexp></code>
|
|
2397
|
+
otherwise the result is undefined and the containing
|
|
2398
|
+
line is dropped.
|
|
2399
|
+
</dd><dt><span class="term">
|
|
2400
|
+
<code class="literal">{<name>$<regexp>::<value>}</code>
|
|
2401
|
+
</span></dt><dd>
|
|
2402
|
+
Substitutes <code class="literal"><value></code> if <code class="literal"><name></code> does not match
|
|
2403
|
+
<code class="literal"><regexp></code> otherwise the result is undefined and the
|
|
2404
|
+
containing line is dropped.
|
|
2405
|
+
</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>25.2.1. Conditional attribute examples</h4></div></div></div><p>Conditional attributes are mainly used in <span class="emphasis"><em>AsciiDoc</em></span> configuration
|
|
2406
|
+
files — see the distribution <code class="literal">.conf</code> files for examples.</p><div class="variablelist"><dl><dt><span class="term">
|
|
2407
|
+
Attribute equality test
|
|
2408
|
+
</span></dt><dd><p>
|
|
2409
|
+
If <code class="literal">{backend}</code> is <code class="literal">docbook</code> or <code class="literal">xhtml11</code> the example evaluates to
|
|
2410
|
+
“DocBook or XHTML backend” otherwise it evaluates to “some other
|
|
2411
|
+
backend”:
|
|
2412
|
+
</p><pre class="literallayout">{backend@docbook|xhtml11:DocBook or XHTML backend:some other backend}</pre></dd><dt><span class="term">
|
|
2413
|
+
Attribute value map
|
|
2414
|
+
</span></dt><dd><p>
|
|
2415
|
+
This example maps the <code class="literal">frame</code> attribute values [<code class="literal">topbot</code>, <code class="literal">all</code>,
|
|
2416
|
+
<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>]:
|
|
2417
|
+
</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>25.3. System Attribute References</h3></div></div></div><p>System attribute references generate the attribute text value by
|
|
2418
|
+
executing a predefined action that is parametrized by a single
|
|
2419
|
+
argument. The syntax is <code class="literal">{<action>:<argument>}</code>.</p><div class="variablelist"><dl><dt><span class="term">
|
|
2420
|
+
<code class="literal">{eval:<expression>}</code>
|
|
2421
|
+
</span></dt><dd>
|
|
2422
|
+
Substitutes the result of the Python <code class="literal"><expression></code>. If
|
|
2423
|
+
<code class="literal"><expression></code> evaluates to <code class="literal">None</code> or <code class="literal">False</code> the reference is
|
|
2424
|
+
deemed undefined and the line containing the reference is
|
|
2425
|
+
dropped from the output. If the expression evaluates to
|
|
2426
|
+
<code class="literal">True</code> the attribute evaluates to an empty string. In all
|
|
2427
|
+
remaining cases the attribute evaluates to a string
|
|
2428
|
+
representation of the <code class="literal"><expression></code> result.
|
|
2429
|
+
</dd><dt><span class="term">
|
|
2430
|
+
<code class="literal">{include:<filename>}</code>
|
|
2431
|
+
</span></dt><dd><p>
|
|
2432
|
+
Substitutes contents of the file named <code class="literal"><filename></code>.
|
|
2433
|
+
</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2434
|
+
The included file is read at the time of attribute
|
|
2435
|
+
substitution.
|
|
2436
|
+
</li><li>
|
|
2437
|
+
If the file does not exist a warning is emitted and the line
|
|
2438
|
+
containing the reference is dropped from the output file.
|
|
2439
|
+
</li><li>
|
|
2440
|
+
Tabs are expanded based on the current <span class="emphasis"><em>tabsize</em></span> attribute
|
|
2441
|
+
value.
|
|
2442
|
+
</li></ul></div></dd><dt><span class="term">
|
|
2443
|
+
<code class="literal">{sys:<command>}</code>
|
|
2444
|
+
</span></dt><dd>
|
|
2445
|
+
Substitutes the stdout generated by the execution of the shell
|
|
2446
|
+
<code class="literal"><command></code>.
|
|
2447
|
+
</dd><dt><span class="term">
|
|
2448
|
+
<code class="literal">{sys2:<command>}</code>
|
|
2449
|
+
</span></dt><dd>
|
|
2450
|
+
Substitutes the stdout and stderr generated by the execution
|
|
2451
|
+
of the shell <code class="literal"><command></code>.
|
|
2452
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>System reference behavior</b></p><ul type="disc"><li>
|
|
2453
|
+
System attribute arguments can contain non-system attribute
|
|
2454
|
+
references.
|
|
2455
|
+
</li><li>
|
|
2456
|
+
Closing brace characters inside system attribute arguments must be
|
|
2457
|
+
escaped them with a backslash.
|
|
2458
|
+
</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>26. Intrinsic Attributes</h2></div></div></div><p>Intrinsic attributes are simple attributes that are created
|
|
2459
|
+
automatically from <span class="emphasis"><em>AsciiDoc</em></span> document header parameters, <code class="literal">asciidoc(1)</code>
|
|
2460
|
+
command-line arguments, execution parameters along with attributes
|
|
2461
|
+
defined in the default configuration files. Here’s the list of
|
|
2462
|
+
predefined intrinsic attributes:</p><pre class="literallayout">{amp} ampersand (&) character
|
|
2463
|
+
{asciidoc-dir} the asciidoc(1) application directory
|
|
2464
|
+
{asciidoc-file} the full path name of the asciidoc(1) script
|
|
2465
|
+
{asciidoc-version} the version of asciidoc(1)
|
|
2466
|
+
{author} author's full name
|
|
2467
|
+
{authored} empty string '' if {author} or {email} defined,
|
|
2468
|
+
{authorinitials} author initials (from document header)
|
|
2469
|
+
{backend-<backend>} empty string ''
|
|
2470
|
+
{<backend>-<doctype>} empty string ''
|
|
2471
|
+
{backend} document backend specified by `-b` option
|
|
2472
|
+
{backslash} backslash character
|
|
2473
|
+
{basebackend-<base>} empty string ''
|
|
2474
|
+
{basebackend} html or docbook
|
|
2475
|
+
{brvbar} broken vertical bar (|) character
|
|
2476
|
+
{date} document date (from document header)
|
|
2477
|
+
{docname} document file name without extension
|
|
2478
|
+
{doctitle} document title (from document header)
|
|
2479
|
+
{doctype-<doctype>} empty string ''
|
|
2480
|
+
{doctype} document type specified by `-d` option
|
|
2481
|
+
{email} author's email address (from document header)
|
|
2482
|
+
{empty} empty string ''
|
|
2483
|
+
{encoding} specifies input and output encoding
|
|
2484
|
+
{filetype-<fileext>} empty string ''
|
|
2485
|
+
{filetype} output file name file extension
|
|
2486
|
+
{firstname} author first name (from document header)
|
|
2487
|
+
{gt} greater than (>) character
|
|
2488
|
+
{id} running block id generated by BlockId elements
|
|
2489
|
+
{indir} document input directory name (note 1)
|
|
2490
|
+
{infile} input file name (note 1)
|
|
2491
|
+
{lastname} author last name (from document header)
|
|
2492
|
+
{listindex} the list index (1..) of the most recent list item
|
|
2493
|
+
{localdate} the current date
|
|
2494
|
+
{localtime} the current time
|
|
2495
|
+
{lt} less than (<) character
|
|
2496
|
+
{manname} manpage name (defined in NAME section)
|
|
2497
|
+
{manpurpose} manpage (defined in NAME section)
|
|
2498
|
+
{mantitle} document title minus the manpage volume number
|
|
2499
|
+
{manvolnum} manpage volume number (1..8) (from document header)
|
|
2500
|
+
{middlename} author middle name (from document header)
|
|
2501
|
+
{nbsp} Non-breaking space entity
|
|
2502
|
+
{outdir} document output directory name (note 1)
|
|
2503
|
+
{outfile} output file name (note 1)
|
|
2504
|
+
{revision} document revision number (from document header)
|
|
2505
|
+
{sectnum} section number (in section titles)
|
|
2506
|
+
{title} section title (in titled elements)
|
|
2507
|
+
{two_colons} Two colon characters.
|
|
2508
|
+
{two_semicolons} Two semicolon characters.
|
|
2509
|
+
{user-dir} the ~/.asciidoc directory (if it exists)
|
|
2510
|
+
{verbose} defined as '' if --verbose command option specified</pre><div class="orderedlist"><p class="title"><b>NOTES</b></p><ol type="1"><li>
|
|
2511
|
+
Intrinsic attributes are global so avoid defining custom attributes
|
|
2512
|
+
with the same names.
|
|
2513
|
+
</li><li>
|
|
2514
|
+
<code class="literal">{infile}</code>, <code class="literal">{outdir}</code>, <code class="literal">{infile}</code>, <code class="literal">{indir}</code> attributes are
|
|
2515
|
+
effectively read-only (you can set them but it won’t affect the
|
|
2516
|
+
input or output file paths).
|
|
2517
|
+
</li><li>
|
|
2518
|
+
See also the <a class="link" href="#X33" title="4.2. xhtml11">xhtml11</a> subsection for attributes that relate
|
|
2519
|
+
to <span class="emphasis"><em>AsciiDoc</em></span> XHTML file generation.
|
|
2520
|
+
</li><li>
|
|
2521
|
+
The entries that translate to blank strings are designed to be used
|
|
2522
|
+
for conditional text inclusion. You can also use the <code class="literal">ifdef</code>,
|
|
2523
|
+
<code class="literal">ifndef</code> and <code class="literal">endif</code> System macros for conditional inclusion.
|
|
2524
|
+
<sup>[<a id="id2543097" href="#ftn.id2543097" class="footnote">5</a>]</sup>
|
|
2525
|
+
</li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X73"></a>27. Block Element Definitions</h2></div></div></div><p>The syntax and behavior of Paragraph, DelimitedBlock, List and Table
|
|
2526
|
+
block elements is determined by block definitions contained in
|
|
2527
|
+
<a class="link" href="#X7" title="21. Configuration Files"><span class="emphasis"><em>AsciiDoc</em></span> configuration file</a> sections.</p><p>Each definition consists of a section title followed by one or more
|
|
2528
|
+
section entries. Each entry defines a block parameter controlling some
|
|
2529
|
+
aspect of the block’s behavior. Here’s an example:</p><pre class="screen">[blockdef-listing]
|
|
2530
|
+
delimiter=^-{4,}$
|
|
2531
|
+
template=listingblock
|
|
2532
|
+
presubs=specialcharacters,callouts</pre><p><span class="emphasis"><em>AsciiDoc</em></span> Paragraph, DelimitedBlock, List and Table block elements
|
|
2533
|
+
share a common subset of configuration file parameters:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2534
|
+
delimiter
|
|
2535
|
+
</span></dt><dd>
|
|
2536
|
+
A Python regular expression that matches the first line of a block
|
|
2537
|
+
element — in the case of DelimitedBlocks it also matches the last
|
|
2538
|
+
line. Table elements don’t have an explicit delimiter — they
|
|
2539
|
+
synthesize their delimiters at runtime.
|
|
2540
|
+
</dd><dt><span class="term">
|
|
2541
|
+
template
|
|
2542
|
+
</span></dt><dd>
|
|
2543
|
+
The name of the configuration file markup template section that will
|
|
2544
|
+
envelope the block contents. The pipe | character is substituted for
|
|
2545
|
+
the block contents. List elements use a set of (list specific) tag
|
|
2546
|
+
parameters instead of a single template.
|
|
2547
|
+
</dd><dt><span class="term">
|
|
2548
|
+
options
|
|
2549
|
+
</span></dt><dd>
|
|
2550
|
+
A comma delimited list of element specific option names. In addition
|
|
2551
|
+
to being used internally, options are available during markup tag
|
|
2552
|
+
and template substitution as attributes with an empty string value
|
|
2553
|
+
named like <code class="literal"><option>-option</code> (where <code class="literal"><option></code> is the option name).
|
|
2554
|
+
</dd><dt><span class="term">
|
|
2555
|
+
subs, presubs, postsubs
|
|
2556
|
+
</span></dt><dd><div class="itemizedlist"><ul type="disc"><li>
|
|
2557
|
+
<span class="emphasis"><em>presubs</em></span> and <span class="emphasis"><em>postsubs</em></span> are lists of comma separated substitutions that are
|
|
2558
|
+
performed on the block contents. <span class="emphasis"><em>presubs</em></span> is applied first,
|
|
2559
|
+
<span class="emphasis"><em>postsubs</em></span> (if specified) second.
|
|
2560
|
+
</li><li>
|
|
2561
|
+
<span class="emphasis"><em>subs</em></span> is an alias for <span class="emphasis"><em>presubs</em></span>.
|
|
2562
|
+
</li><li>
|
|
2563
|
+
If a <span class="emphasis"><em>filter</em></span> is allowed (Paragraphs, DelimitedBlocks and Tables)
|
|
2564
|
+
and has been specified then <span class="emphasis"><em>presubs</em></span> and <span class="emphasis"><em>postsubs</em></span> substitutions
|
|
2565
|
+
are performed before and after the filter is run respectively.
|
|
2566
|
+
</li><li>
|
|
2567
|
+
Allowed values: <span class="emphasis"><em>specialcharacters</em></span>, <span class="emphasis"><em>quotes</em></span>, <span class="emphasis"><em>specialwords</em></span>,
|
|
2568
|
+
<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>.
|
|
2569
|
+
</li><li><p>
|
|
2570
|
+
The following composite values are also allowed:
|
|
2571
|
+
</p><div class="variablelist"><dl><dt><span class="term">
|
|
2572
|
+
<span class="emphasis"><em>none</em></span>
|
|
2573
|
+
</span></dt><dd>
|
|
2574
|
+
No substitutions.
|
|
2575
|
+
</dd><dt><span class="term">
|
|
2576
|
+
<span class="emphasis"><em>normal</em></span>
|
|
2577
|
+
</span></dt><dd>
|
|
2578
|
+
The following substitutions:
|
|
2579
|
+
<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>,
|
|
2580
|
+
<span class="emphasis"><em>replacements</em></span>,<span class="emphasis"><em>macros</em></span>.
|
|
2581
|
+
</dd><dt><span class="term">
|
|
2582
|
+
<span class="emphasis"><em>verbatim</em></span>
|
|
2583
|
+
</span></dt><dd>
|
|
2584
|
+
<span class="emphasis"><em>specialcharacters</em></span> and <span class="emphasis"><em>callouts</em></span> substitutions.
|
|
2585
|
+
</dd></dl></div></li><li>
|
|
2586
|
+
<span class="emphasis"><em>normal</em></span> and <span class="emphasis"><em>verbatim</em></span> substitutions can be redefined by with
|
|
2587
|
+
<code class="literal">subsnormal</code> and <code class="literal">subsverbatim</code> entries in a configuration file
|
|
2588
|
+
<code class="literal">[miscellaneous]</code> section.
|
|
2589
|
+
</li><li>
|
|
2590
|
+
The substitutions are processed in the order in which they are
|
|
2591
|
+
listed and can appear more than once.
|
|
2592
|
+
</li></ul></div></dd><dt><span class="term">
|
|
2593
|
+
filter
|
|
2594
|
+
</span></dt><dd>
|
|
2595
|
+
This optional entry specifies an executable shell command for
|
|
2596
|
+
processing block content (Paragraphs, DelimitedBlocks and Tables).
|
|
2597
|
+
The filter command can contain attribute references.
|
|
2598
|
+
</dd><dt><span class="term">
|
|
2599
|
+
posattrs
|
|
2600
|
+
</span></dt><dd><p>
|
|
2601
|
+
Optional comma separated list of positional attribute names. This
|
|
2602
|
+
list maps positional attributes (in the block’s <a class="link" href="#X21" title="24. Attribute Lists">attribute list</a>) to named block attributes. The following example, from the
|
|
2603
|
+
QuoteBlock definition, maps the first and section positional
|
|
2604
|
+
attributes:
|
|
2605
|
+
</p><pre class="literallayout">posattrs=attribution,citetitle</pre></dd><dt><span class="term">
|
|
2606
|
+
style
|
|
2607
|
+
</span></dt><dd>
|
|
2608
|
+
This optional parameter specifies the default style name.
|
|
2609
|
+
</dd><dt><span class="term">
|
|
2610
|
+
<stylename>-style
|
|
2611
|
+
</span></dt><dd>
|
|
2612
|
+
Optional style definition (see <a class="link" href="#X23" title="27.1. Styles">Styles</a> below).
|
|
2613
|
+
</dd></dl></div><p>The following block parameters behave like document attributes and can
|
|
2614
|
+
be set in block attribute lists and style definitions: <span class="emphasis"><em>template</em></span>,
|
|
2615
|
+
<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>27.1. Styles</h3></div></div></div><p>A style is a set of block attributes bundled as a single named
|
|
2616
|
+
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"</pre><div class="itemizedlist"><ul type="disc"><li>
|
|
2617
|
+
All style parameter names must be suffixed with <code class="literal">-style</code> and the
|
|
2618
|
+
style parameter value is in the form of a list of <a class="link" href="#X21" title="24. Attribute Lists">named attributes</a>.
|
|
2619
|
+
</li><li>
|
|
2620
|
+
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>)
|
|
2621
|
+
must be specified using Python tuple syntax rather than a simple
|
|
2622
|
+
list of values as they in separate entries e.g.
|
|
2623
|
+
<code class="literal">postsubs=("callouts",)</code> not <code class="literal">postsubs="callouts"</code>.
|
|
2624
|
+
</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>27.2. Paragraphs</h3></div></div></div><p>Paragraph translation is controlled by <code class="literal">[paradef*]</code> configuration file
|
|
2625
|
+
section entries. Users can define new types of paragraphs and modify
|
|
2626
|
+
the behavior of existing types by editing <span class="emphasis"><em>AsciiDoc</em></span> configuration
|
|
2627
|
+
files.</p><p>Here is the shipped Default paragraph definition:</p><pre class="screen">[paradef-default]
|
|
2628
|
+
delimiter=(?P<text>\S.*)
|
|
2629
|
+
template=paragraph</pre><p>The Default paragraph definition has a couple of special properties:</p><div class="orderedlist"><ol type="1"><li>
|
|
2630
|
+
It must exist and be defined in a configuration file section named
|
|
2631
|
+
<code class="literal">[paradef-default]</code>.
|
|
2632
|
+
</li><li>
|
|
2633
|
+
Irrespective of its position in the configuration files default
|
|
2634
|
+
paragraph document matches are attempted only after trying all
|
|
2635
|
+
other paragraph types.
|
|
2636
|
+
</li></ol></div><p>Paragraph specific block parameter notes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2637
|
+
delimiter
|
|
2638
|
+
</span></dt><dd>
|
|
2639
|
+
This regular expression must contain the named group <span class="emphasis"><em>text</em></span> which
|
|
2640
|
+
matches the text on the first line. Paragraphs are terminated by a
|
|
2641
|
+
blank line, the end of file, or the start of a DelimitedBlock.
|
|
2642
|
+
</dd><dt><span class="term">
|
|
2643
|
+
options
|
|
2644
|
+
</span></dt><dd>
|
|
2645
|
+
The <span class="emphasis"><em>listelement</em></span> option specifies that paragraphs of this type will
|
|
2646
|
+
automatically be considered part of immediately preceding list
|
|
2647
|
+
items.
|
|
2648
|
+
</dd></dl></div><div class="orderedlist"><p class="title"><b>Paragraph processing proceeds as follows:</b></p><ol type="1"><li>
|
|
2649
|
+
The paragraph text is aligned to the left margin.
|
|
2650
|
+
</li><li>
|
|
2651
|
+
Optional <span class="emphasis"><em>presubs</em></span> inline substitutions are performed on the
|
|
2652
|
+
paragraph text.
|
|
2653
|
+
</li><li>
|
|
2654
|
+
If a filter command is specified it is executed and the paragraph
|
|
2655
|
+
text piped to its standard input; the filter output replaces the
|
|
2656
|
+
paragraph text.
|
|
2657
|
+
</li><li>
|
|
2658
|
+
Optional <span class="emphasis"><em>postsubs</em></span> inline substitutions are performed on the
|
|
2659
|
+
paragraph text.
|
|
2660
|
+
</li><li>
|
|
2661
|
+
The paragraph text is enveloped by the paragraph’s markup template
|
|
2662
|
+
and written to the output file.
|
|
2663
|
+
</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>27.3. Delimited Blocks</h3></div></div></div><p>DelimitedBlock <span class="emphasis"><em>options</em></span> values are:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2664
|
+
sectionbody
|
|
2665
|
+
</span></dt><dd>
|
|
2666
|
+
The block contents are processed as a SectionBody.
|
|
2667
|
+
</dd><dt><span class="term">
|
|
2668
|
+
skip
|
|
2669
|
+
</span></dt><dd>
|
|
2670
|
+
The block is treated as a comment (see <a class="link" href="#X26" title="12.5. Comment Blocks">CommentBlocks</a>).
|
|
2671
|
+
</dd><dt><span class="term">
|
|
2672
|
+
list
|
|
2673
|
+
</span></dt><dd>
|
|
2674
|
+
The block is a <a class="link" href="#X29" title="13.7. List Block">list block</a>.
|
|
2675
|
+
</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
|
|
2676
|
+
<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>
|
|
2677
|
+
Optional <span class="emphasis"><em>presubs</em></span> substitutions are performed on the block
|
|
2678
|
+
contents.
|
|
2679
|
+
</li><li>
|
|
2680
|
+
If a filter is specified it is executed and the block’s contents
|
|
2681
|
+
piped to its standard input. The filter output replaces the block
|
|
2682
|
+
contents.
|
|
2683
|
+
</li><li>
|
|
2684
|
+
Optional <span class="emphasis"><em>postsubs</em></span> substitutions are performed on the block
|
|
2685
|
+
contents.
|
|
2686
|
+
</li><li>
|
|
2687
|
+
The block contents is enveloped by the block’s markup template and
|
|
2688
|
+
written to the output file.
|
|
2689
|
+
</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
|
|
2690
|
+
before it is executed, this is useful for passing arguments to the
|
|
2691
|
+
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>27.4. Lists</h3></div></div></div><p>List behavior and syntax is determined by <code class="literal">[listdef*]</code> configuration
|
|
2692
|
+
file sections. The user can change existing list behavior and add new
|
|
2693
|
+
list types by editing configuration files.</p><p>List specific block definition notes:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2694
|
+
type
|
|
2695
|
+
</span></dt><dd>
|
|
2696
|
+
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>.
|
|
2697
|
+
</dd><dt><span class="term">
|
|
2698
|
+
delimiter
|
|
2699
|
+
</span></dt><dd>
|
|
2700
|
+
A Python regular expression that matches the first line of a
|
|
2701
|
+
list element entry. This expression can contain the named groups
|
|
2702
|
+
<span class="emphasis"><em>text</em></span> (bulleted groups), <span class="emphasis"><em>index</em></span> and <span class="emphasis"><em>text</em></span> (numbered lists),
|
|
2703
|
+
<span class="emphasis"><em>label</em></span> and <span class="emphasis"><em>text</em></span> (labeled lists).
|
|
2704
|
+
</dd><dt><span class="term">
|
|
2705
|
+
tags
|
|
2706
|
+
</span></dt><dd>
|
|
2707
|
+
The <code class="literal"><name></code> of the <code class="literal">[listtags-<name>]</code> configuration file section
|
|
2708
|
+
containing list markup tag definitions. The tag entries (<span class="emphasis"><em>list</em></span>,
|
|
2709
|
+
<span class="emphasis"><em>entry</em></span>, <span class="emphasis"><em>label</em></span>, <span class="emphasis"><em>term</em></span>, <span class="emphasis"><em>text</em></span>) map the <span class="emphasis"><em>AsciiDoc</em></span> list structure to
|
|
2710
|
+
backend markup; see the <span class="emphasis"><em>listtags</em></span> sections in the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
2711
|
+
distributed backend <code class="literal">.conf</code> configuration files for examples.
|
|
2712
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_tables_2"></a>27.5. Tables</h3></div></div></div><p>Table behavior and syntax is determined by <code class="literal">[tabledef*]</code> and
|
|
2713
|
+
<code class="literal">[tabletags*]</code> configuration file sections. The user can change
|
|
2714
|
+
existing table behavior and add new table types by editing
|
|
2715
|
+
configuration files. The following <code class="literal">[tabledef*]</code> section entries
|
|
2716
|
+
generate table output markup elements:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2717
|
+
comspec
|
|
2718
|
+
</span></dt><dd>
|
|
2719
|
+
The table <span class="emphasis"><em>comspec</em></span> tag definition.
|
|
2720
|
+
</dd><dt><span class="term">
|
|
2721
|
+
headrow, footrow, bodyrow
|
|
2722
|
+
</span></dt><dd>
|
|
2723
|
+
Table header, footer and body row tag definitions. <span class="emphasis"><em>headrow</em></span> and
|
|
2724
|
+
<span class="emphasis"><em>footrow</em></span> table definition entries default to <span class="emphasis"><em>bodyrow</em></span> if
|
|
2725
|
+
they are undefined.
|
|
2726
|
+
</dd><dt><span class="term">
|
|
2727
|
+
headdata, footdata, bodydata
|
|
2728
|
+
</span></dt><dd>
|
|
2729
|
+
Table header, footer and body data tag definitions. <span class="emphasis"><em>headdata</em></span> and
|
|
2730
|
+
<span class="emphasis"><em>footdata</em></span> table definition entries default to <span class="emphasis"><em>bodydata</em></span> if they
|
|
2731
|
+
are undefined.
|
|
2732
|
+
</dd><dt><span class="term">
|
|
2733
|
+
paragraph
|
|
2734
|
+
</span></dt><dd>
|
|
2735
|
+
If the <span class="emphasis"><em>paragraph</em></span> tag is specified then blank lines in the cell
|
|
2736
|
+
data are treated as paragraph delimiters and marked up using this
|
|
2737
|
+
tag.
|
|
2738
|
+
</dd></dl></div><p><a id="X4"></a>Table behavior is also influenced by the following <code class="literal">[miscellaneous]</code>
|
|
2739
|
+
configuration file entries:</p><div class="variablelist"><dl><dt><span class="term">
|
|
2740
|
+
pagewidth
|
|
2741
|
+
</span></dt><dd>
|
|
2742
|
+
This integer value is the printable width of the output media. See
|
|
2743
|
+
<a class="link" href="#X69" title="18.3. Table attributes">table attributes</a>.
|
|
2744
|
+
</dd><dt><span class="term">
|
|
2745
|
+
pageunits
|
|
2746
|
+
</span></dt><dd>
|
|
2747
|
+
The units of width in output markup width attribute values.
|
|
2748
|
+
</dd></dl></div><div class="itemizedlist"><p class="title"><b>Table definition behavior</b></p><ul type="disc"><li>
|
|
2749
|
+
The output markup generation is specifically designed to work with
|
|
2750
|
+
the HTML and CALS (DocBook) table models, but should be adaptable to
|
|
2751
|
+
most XML table schema.
|
|
2752
|
+
</li><li>
|
|
2753
|
+
Table definitions can be “mixed in” from multiple cascading
|
|
2754
|
+
configuration files.
|
|
2755
|
+
</li><li>
|
|
2756
|
+
New table definitions inherit the default table and table tags
|
|
2757
|
+
definitions (<code class="literal">[tabledef-default]</code> and <code class="literal">[tabletags-default]</code>) so you
|
|
2758
|
+
only need to override those conf file entries that require
|
|
2759
|
+
modification.
|
|
2760
|
+
</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>28. Filters</h2></div></div></div><p>Filters are external shell commands used to process Paragraph and
|
|
2761
|
+
DelimitedBlock content; they are specified in configuration file
|
|
2762
|
+
Paragraph and DelimitedBlock definitions.</p><p>There’s nothing special about the filters, they’re just standard UNIX
|
|
2763
|
+
filters: they read text from the standard input, process it, and write
|
|
2764
|
+
to the standard output.</p><p>Attribute substitution is performed on the filter command prior to
|
|
2765
|
+
execution — attributes can be used to pass parameters from the
|
|
2766
|
+
<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
|
|
2767
|
+
installing a filter you should verify that it can’t be coerced into
|
|
2768
|
+
generating malicious output or exposing sensitive information.</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>28.1. Filter Search Paths</h3></div></div></div><p>If the filter command does not specify a directory path then
|
|
2769
|
+
<code class="literal">asciidoc(1)</code> searches for the command:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2770
|
+
First it looks in the user’s <code class="literal">$HOME/.asciidoc/filters</code> directory.
|
|
2771
|
+
</li><li>
|
|
2772
|
+
Next the <code class="literal">/etc/asciidoc/filters</code> directory is searched.
|
|
2773
|
+
</li><li>
|
|
2774
|
+
Then it looks in the <code class="literal">asciidoc(1)</code> <code class="literal">./filters</code> directory.
|
|
2775
|
+
</li><li>
|
|
2776
|
+
Finally it relies on the executing shell to search the environment
|
|
2777
|
+
search path (<code class="literal">$PATH</code>).
|
|
2778
|
+
</li></ul></div><p>Sub-directories are also included in the searches — standard practice
|
|
2779
|
+
is to install each filter in it’s own sub-directory with the same name
|
|
2780
|
+
as the filter’s style definition. For example the music filter’s style
|
|
2781
|
+
name is <span class="emphasis"><em>music</em></span> so it’s configuration and filter files are stored in
|
|
2782
|
+
the <code class="literal">filters/music</code> directory.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_filter_configuration_files"></a>28.2. Filter Configuration Files</h3></div></div></div><p>Filters are normally accompanied by a configuration file containing a
|
|
2783
|
+
Paragraph or DelimitedBlock definition along with corresponding markup
|
|
2784
|
+
templates.</p><p>While it is possible to create new Paragraph or DelimitedBlock
|
|
2785
|
+
definitions the preferred way to implement a filter is to add a
|
|
2786
|
+
<a class="link" href="#X23" title="27.1. Styles">style</a> to an existing Paragraph or DelimitedBlock definition
|
|
2787
|
+
(all filters shipped with <span class="emphasis"><em>AsciiDoc</em></span> use this technique). The filter is
|
|
2788
|
+
applied to the paragraph or delimited block by preceding it with an
|
|
2789
|
+
attribute list: the first positional attribute is the style name,
|
|
2790
|
+
remaining attributes are normally filter specific parameters.</p><p><code class="literal">asciidoc(1)</code> auto-loads all <code class="literal">.conf</code> files found in the filter search
|
|
2791
|
+
paths (see previous section).</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X56"></a>28.3. Code Filter</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> comes with a toy filter for highlighting source code keywords
|
|
2792
|
+
and comments. See also the <code class="literal">./filters/code/code-filter-readme.txt</code>
|
|
2793
|
+
file.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="./images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>This filter primarily to demonstrate how to write a filter — it’s much to simplistic to be passed off as a code syntax highlighter.
|
|
2794
|
+
If you want a full featured multi-language highlighter use the
|
|
2795
|
+
<a class="link" href="#X57" title="28.4. Source Code Highlighter Filter">Source Code Highlighter Filter</a>.</p></td></tr></table></div><pre class="screen">.Code filter example
|
|
2796
|
+
[code,python]
|
|
2797
|
+
----------------------------------------------
|
|
2798
|
+
''' A multi-line
|
|
2799
|
+
comment.'''
|
|
2800
|
+
def sub_word(mo):
|
|
2801
|
+
''' Single line comment.'''
|
|
2802
|
+
word = mo.group('word') # Inline comment
|
|
2803
|
+
if word in keywords[language]:
|
|
2804
|
+
return quote + word + quote
|
|
2805
|
+
else:
|
|
2806
|
+
return word
|
|
2807
|
+
----------------------------------------------</pre><p>Outputs:</p><div class="example"><a id="id2544749"></a><p class="title"><b>Example 5. Code filter example</b></p><div class="example-contents"><pre class="screen"><span class="emphasis"><em>''' A multi-line</em></span>
|
|
2808
|
+
<span class="emphasis"><em> comment.'''</em></span>
|
|
2809
|
+
<span class="strong"><strong>def</strong></span> sub_word(mo):
|
|
2810
|
+
<span class="emphasis"><em> ''' Single line comment.'''</em></span>
|
|
2811
|
+
word = mo.group('word') <span class="emphasis"><em># Inline comment</em></span>
|
|
2812
|
+
<span class="strong"><strong>if</strong></span> word <span class="strong"><strong>in</strong></span> keywords[language]:
|
|
2813
|
+
<span class="strong"><strong>return</strong></span> quote + word + quote
|
|
2814
|
+
<span class="strong"><strong>else</strong></span>:
|
|
2815
|
+
<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>28.4. Source Code Highlighter Filter</h3></div></div></div><p>A
|
|
2816
|
+
<a class="ulink" href="http://www.methods.co.nz/asciidoc/source-highlight-filter.html" target="_top">source
|
|
2817
|
+
code highlighter filter</a> can be found in the <span class="emphasis"><em>AsciiDoc</em></span> distribution
|
|
2818
|
+
<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>28.5. Music Filter</h3></div></div></div><p>A <a class="ulink" href="http://www.methods.co.nz/asciidoc/music-filter.html" target="_top">music filter</a> is
|
|
2819
|
+
included in the distribution <code class="literal">./filters</code> directory. It translates
|
|
2820
|
+
music in <a class="ulink" href="http://lilypond.org/" target="_top">LilyPond</a> or
|
|
2821
|
+
<a class="ulink" href="http://abcnotation.org.uk/" target="_top">ABC</a> notation to standard Western classical
|
|
2822
|
+
notation in the form of a trimmed PNG image which is automatically
|
|
2823
|
+
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>29. Converting DocBook to other file formats</h2></div></div></div><p>DocBook files are validated, parsed and translated by a combination of
|
|
2824
|
+
applications collectively called a DocBook <span class="emphasis"><em>tool chain</em></span>. The function
|
|
2825
|
+
of a tool chain is to read the DocBook markup (produced by <span class="emphasis"><em>AsciiDoc</em></span>)
|
|
2826
|
+
and transform it to a presentation format (for example HTML, PDF, HTML
|
|
2827
|
+
Help, DVI, PostScript, LaTeX).</p><p>A wide range of user output format requirements coupled with a choice
|
|
2828
|
+
of available tools and stylesheets results in many valid tool chain
|
|
2829
|
+
combinations.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X43"></a>29.1. a2x Toolchain Wrapper</h3></div></div></div><p>One of the biggest hurdles for new users is installing, configuring
|
|
2830
|
+
and using a DocBook XML toolchain. <code class="literal"><code class="literal">a2x(1)</code></code> can help — it’s a
|
|
2831
|
+
toolchain wrapper command that will generate XHTML (chunked and
|
|
2832
|
+
unchunked), PDF, DVI, PS, LaTeX, man page, HTML Help and text file
|
|
2833
|
+
outputs from an <span class="emphasis"><em>AsciiDoc</em></span> text file. <code class="literal">a2x(1)</code> does all the grunt work
|
|
2834
|
+
associated with generating and sequencing the toolchain commands and
|
|
2835
|
+
managing intermediate and output files. <code class="literal">a2x(1)</code> also optionally
|
|
2836
|
+
deploys admonition and navigation icons and a CSS stylesheet. See the
|
|
2837
|
+
<code class="literal"><code class="literal">a2x(1)</code></code> man page for more details. All you need is
|
|
2838
|
+
<a class="link" href="#">xsltproc(1)</a>, <a class="link" href="#">DocBook XSL Stylesheets</a> and optionally:
|
|
2839
|
+
<a class="link" href="#">dblatex</a> or <a class="link" href="#">FOP</a> (if you want PDF); <code class="literal">w3m(1)</code> or
|
|
2840
|
+
<code class="literal">lynx(1)</code> (if you want text).</p><p>The following examples generate <code class="literal">doc/source-highlight-filter.pdf</code> from
|
|
2841
|
+
the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">doc/source-highlight-filter.txt</code> source file. The first
|
|
2842
|
+
example uses <code class="literal">dblatex(1)</code> (the default PDF generator) the second
|
|
2843
|
+
example forces FOP to be used:</p><pre class="literallayout">$ a2x -f pdf doc/source-highlight-filter.txt
|
|
2844
|
+
$ a2x -f pdf --fop 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
|
|
2845
|
+
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>29.2. HTML generation</h3></div></div></div><p><span class="emphasis"><em>AsciiDoc</em></span> produces nicely styled HTML directly without requiring a
|
|
2846
|
+
DocBook toolchain but there are also advantages in going the DocBook
|
|
2847
|
+
route:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
2848
|
+
HTML from DocBook includes automatically generated indexes, tables
|
|
2849
|
+
of contents, footnotes, lists of figures and tables.
|
|
2850
|
+
</li><li>
|
|
2851
|
+
DocBook toolchains can also (optionally) generate separate (chunked)
|
|
2852
|
+
linked HTML pages for each document section.
|
|
2853
|
+
</li><li>
|
|
2854
|
+
Toolchain processing performs link and document validity checks.
|
|
2855
|
+
</li><li>
|
|
2856
|
+
If the DocBook <span class="emphasis"><em>lang</em></span> attribute is set then things like table of
|
|
2857
|
+
contents, revision history, figure and table captions and admonition
|
|
2858
|
+
captions will be output in the specified language (setting the
|
|
2859
|
+
<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).
|
|
2860
|
+
</li></ul></div><p>On the other hand, HTML output directly from <span class="emphasis"><em>AsciiDoc</em></span> is much faster,
|
|
2861
|
+
is easily customized and can be used in situations where there is no
|
|
2862
|
+
suitable DocBook toolchain (see the
|
|
2863
|
+
<a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span> website</a> for example).</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_pdf_generation"></a>29.3. PDF generation</h3></div></div></div><p>There are two commonly used tools to generate PDFs from DocBook,
|
|
2864
|
+
<a class="link" href="#">dblatex</a> and <a class="link" href="#">FOP</a>.</p><div class="itemizedlist"><p class="title"><b>dblatex or FOP?</b></p><ul type="disc"><li>
|
|
2865
|
+
<span class="emphasis"><em>dblatex</em></span> is easier to install, there’s zero configuration
|
|
2866
|
+
required and no Java VM to install — it just works out of the box.
|
|
2867
|
+
</li><li>
|
|
2868
|
+
<span class="emphasis"><em>dblatex</em></span> source code highlighting and numbering is superb.
|
|
2869
|
+
</li><li>
|
|
2870
|
+
<span class="emphasis"><em>dblatex</em></span> is easier to use as it converts DocBook directly to PDF
|
|
2871
|
+
whereas before using <span class="emphasis"><em>FOP</em></span> you have to convert DocBook to XML-FO
|
|
2872
|
+
using <a class="link" href="#">DocBook XSL Stylesheets</a>.
|
|
2873
|
+
</li><li>
|
|
2874
|
+
<span class="emphasis"><em>FOP</em></span> is more feature complete (for example, callouts are processed
|
|
2875
|
+
inside literal layouts) and arguably produces nicer looking output.
|
|
2876
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_html_help_generation"></a>29.4. HTML Help generation</h3></div></div></div><div class="orderedlist"><ol type="1"><li>
|
|
2877
|
+
Convert DocBook XML documents to HTML Help compiler source files
|
|
2878
|
+
using <a class="link" href="#">DocBook XSL Stylesheets</a> and <a class="link" href="#">xsltproc(1)</a>.
|
|
2879
|
+
</li><li>
|
|
2880
|
+
Convert the HTML Help source (<code class="literal">.hhp</code> and <code class="literal">.html</code>) files to HTML Help
|
|
2881
|
+
(<code class="literal">.chm</code>) files using the <a class="link" href="#X67" title="29.6. AsciiDoc dblatex configuration files">Microsoft HTML Help Compiler</a>.
|
|
2882
|
+
</li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_toolchain_components_summary"></a>29.5. Toolchain components summary</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
2883
|
+
<span class="emphasis"><em>AsciiDoc</em></span>
|
|
2884
|
+
</span></dt><dd>
|
|
2885
|
+
Converts <span class="emphasis"><em>AsciiDoc</em></span> (<code class="literal">.txt</code>) files to DocBook XML (<code class="literal">.xml</code>) files.
|
|
2886
|
+
</dd><dt><span class="term">
|
|
2887
|
+
<a class="ulink" href="http://docbook.sourceforge.net/projects/xsl/" target="_top">DocBook XSL Stylesheets</a>
|
|
2888
|
+
</span></dt><dd>
|
|
2889
|
+
These are a set of XSL stylesheets containing rules for converting
|
|
2890
|
+
DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
|
|
2891
|
+
The stylesheets are used in conjunction with an XML parser such as
|
|
2892
|
+
<a class="link" href="#">xsltproc(1)</a>.
|
|
2893
|
+
</dd><dt><span class="term">
|
|
2894
|
+
<a class="ulink" href="http://www.xmlsoft.org" target="_top">xsltproc</a>
|
|
2895
|
+
</span></dt><dd>
|
|
2896
|
+
An XML parser for applying XSLT stylesheets (in our case the
|
|
2897
|
+
<a class="link" href="#">DocBook XSL Stylesheets</a>) to XML documents.
|
|
2898
|
+
</dd><dt><span class="term">
|
|
2899
|
+
<a class="ulink" href="http://dblatex.sourceforge.net/" target="_top">dblatex</a>
|
|
2900
|
+
</span></dt><dd>
|
|
2901
|
+
Generates PDF, DVI, PostScript and LaTeX formats directly from
|
|
2902
|
+
DocBook source via the intermediate LaTeX typesetting language — uses <a class="link" href="#">DocBook XSL Stylesheets</a>, <a class="link" href="#">xsltproc(1)</a> and
|
|
2903
|
+
<code class="literal">latex(1)</code>.
|
|
2904
|
+
</dd><dt><span class="term">
|
|
2905
|
+
<a class="ulink" href="http://xml.apache.org/fop/" target="_top">FOP</a>
|
|
2906
|
+
</span></dt><dd>
|
|
2907
|
+
The Apache Formatting Objects Processor converts XSL-FO (<code class="literal">.fo</code>)
|
|
2908
|
+
files to PDF files. The XSL-FO files are generated from DocBook
|
|
2909
|
+
source files using <a class="link" href="#">DocBook XSL Stylesheets</a> and
|
|
2910
|
+
<a class="link" href="#">xsltproc(1)</a>.
|
|
2911
|
+
</dd><dt><span class="term">
|
|
2912
|
+
Microsoft Help Compiler
|
|
2913
|
+
</span></dt><dd>
|
|
2914
|
+
The Microsoft HTML Help Compiler (<code class="literal">hhc.exe</code>) is a command-line tool
|
|
2915
|
+
that converts HTML Help source files to a single HTML Help (<code class="literal">.chm</code>)
|
|
2916
|
+
file. It runs on MS Windows platforms and can be downloaded from
|
|
2917
|
+
<a class="ulink" href="http://www.microsoft.com" target="_top">http://www.microsoft.com</a>.
|
|
2918
|
+
</dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X67"></a>29.6. AsciiDoc dblatex configuration files</h3></div></div></div><p>The <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">./dblatex</code> directory contains
|
|
2919
|
+
<code class="literal">asciidoc-dblatex.xsl</code> (customized XSL parameter settings) and
|
|
2920
|
+
<code class="literal">asciidoc-dblatex.sty</code> (customized LaTeX settings). These are examples
|
|
2921
|
+
of optional <a class="link" href="#">dblatex</a> output customization and are used by
|
|
2922
|
+
<a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_asciidoc_docbook_xsl_stylesheets_drivers"></a>29.7. AsciiDoc DocBook XSL Stylesheets drivers</h3></div></div></div><p>You will have noticed that the distributed HTML and HTML Help
|
|
2923
|
+
documentation files (for example <code class="literal">./doc/asciidoc.html</code>) are not the
|
|
2924
|
+
plain outputs produced using the default <span class="emphasis"><em>DocBook XSL Stylesheets</em></span>
|
|
2925
|
+
configuration. This is because they have been processed using
|
|
2926
|
+
customized DocBook XSL Stylesheets along with (in the case of HTML
|
|
2927
|
+
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
|
|
2928
|
+
documentation in the distribution <code class="literal">./docbook-xsl</code> directory. The
|
|
2929
|
+
examples that follow are executed from the distribution documentation
|
|
2930
|
+
(<code class="literal">./doc</code>) directory.</p><div class="variablelist"><dl><dt><span class="term">
|
|
2931
|
+
<code class="literal">common.xsl</code>
|
|
2932
|
+
</span></dt><dd>
|
|
2933
|
+
Shared driver parameters. This file is not used directly but is
|
|
2934
|
+
included in all the following drivers.
|
|
2935
|
+
</dd><dt><span class="term">
|
|
2936
|
+
<code class="literal">chunked.xsl</code>
|
|
2937
|
+
</span></dt><dd><p>
|
|
2938
|
+
Generate chunked XHTML (separate HTML pages for each document
|
|
2939
|
+
section) in the <code class="literal">./doc/chunked</code> directory. For example:
|
|
2940
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook asciidoc.txt
|
|
2941
|
+
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml</pre></dd><dt><span class="term">
|
|
2942
|
+
<code class="literal">fo.xsl</code>
|
|
2943
|
+
</span></dt><dd><p>
|
|
2944
|
+
Generate XSL Formatting Object (<code class="literal">.fo</code>) files for subsequent PDF
|
|
2945
|
+
file generation using FOP. For example:
|
|
2946
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook article.txt
|
|
2947
|
+
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
|
|
2948
|
+
$ fop.sh article.fo article.pdf</pre></dd><dt><span class="term">
|
|
2949
|
+
<code class="literal">htmlhelp.xsl</code>
|
|
2950
|
+
</span></dt><dd><p>
|
|
2951
|
+
Generate Microsoft HTML Help source files for the MS HTML Help
|
|
2952
|
+
Compiler in the <code class="literal">./doc/htmlhelp</code> directory. This example is run on
|
|
2953
|
+
MS Windows from a Cygwin shell prompt:
|
|
2954
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook asciidoc.txt
|
|
2955
|
+
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
|
|
2956
|
+
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp</pre></dd><dt><span class="term">
|
|
2957
|
+
<code class="literal">manpage.xsl</code>
|
|
2958
|
+
</span></dt><dd><p>
|
|
2959
|
+
Generate a <code class="literal">roff(1)</code> format UNIX man page from a DocBook XML
|
|
2960
|
+
<span class="emphasis"><em>refentry</em></span> document. This example generates an <code class="literal">asciidoc.1</code> man
|
|
2961
|
+
page file:
|
|
2962
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
|
|
2963
|
+
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml</pre></dd><dt><span class="term">
|
|
2964
|
+
<code class="literal">xhtml.xsl</code>
|
|
2965
|
+
</span></dt><dd><p>
|
|
2966
|
+
Convert a DocBook XML file to a single XHTML file. For example:
|
|
2967
|
+
</p><pre class="literallayout">$ python ../asciidoc.py -b docbook asciidoc.txt
|
|
2968
|
+
$ 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
|
|
2969
|
+
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>30. 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>
|
|
2970
|
+
source text is fine), however you can convert <span class="emphasis"><em>AsciiDoc</em></span> text files to
|
|
2971
|
+
formatted text using the <span class="emphasis"><em>AsciiDoc</em></span> <a class="link" href="#X43" title="29.1. a2x Toolchain Wrapper"><code class="literal">a2x(1)</code></a> toolchain wrapper
|
|
2972
|
+
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>31. 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
|
|
2973
|
+
DocBook files but this can be changed by setting the <code class="literal">xmldecl</code> entry
|
|
2974
|
+
in the <code class="literal">[attributes]</code> section of the <code class="literal">docbook.conf</code> file or by
|
|
2975
|
+
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
|
|
2976
|
+
files you’ll may find that you’ve used an undefined HTML character
|
|
2977
|
+
entity. An easy (although inelegant) fix is to use the character’s
|
|
2978
|
+
character code instead of its symbolic name (for example use <code class="literal">&#160;</code>
|
|
2979
|
+
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
|
|
2980
|
+
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>31.1. PDF Fonts</h3></div></div></div><p>The Adobe PDF Specification states that the following 14 fonts should
|
|
2981
|
+
be available to every PDF reader: Helvetica (normal, bold, italic,
|
|
2982
|
+
bold italic), Times (normal, bold, italic, bold italic), Courier
|
|
2983
|
+
(normal, bold, italic, bold italic), Symbol and ZapfDingbats.
|
|
2984
|
+
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>32. 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
|
|
2985
|
+
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.
|
|
2986
|
+
Help topic names can be shortened so long as they are not ambiguous.
|
|
2987
|
+
Examples:</p><pre class="literallayout">$ asciidoc --help=manpage
|
|
2988
|
+
$ asciidoc -hm # Short version of previous example.
|
|
2989
|
+
$ asciidoc --help=syntax
|
|
2990
|
+
$ 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>32.1. Customizing Help</h3></div></div></div><p>To change, delete or add your own help topics edit a help
|
|
2991
|
+
configuration file. The help file name <code class="literal">help-<lang>.conf</code> is based on
|
|
2992
|
+
the setting of the <code class="literal">lang</code> attribute, it defaults to <code class="literal">help.conf</code>
|
|
2993
|
+
(English). The <a class="link" href="#X27" title="21.11. Configuration File Names and Locations">help file location</a> will depend on whether you
|
|
2994
|
+
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
|
|
2995
|
+
<a class="link" href="#X7" title="21. Configuration Files">configuration files</a>. The <code class="literal">help.conf</code> files are stored in the
|
|
2996
|
+
same locations and loaded in the same order as other configuration
|
|
2997
|
+
files.</p><p>When the <code class="literal">--help</code> command-line option is specified <span class="emphasis"><em>AsciiDoc</em></span> loads the
|
|
2998
|
+
appropriate help files and then prints the contents of the section
|
|
2999
|
+
whose name matches the help topic name. If a topic name is not
|
|
3000
|
+
specified <code class="literal">default</code> is used. You don’t need to specify the whole help
|
|
3001
|
+
topic name on the command-line, just enough letters to ensure it’s not
|
|
3002
|
+
ambiguous. If a matching help file section is not found a list of
|
|
3003
|
+
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>33. 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>33.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
|
|
3004
|
+
know your favorite text editor. Learn how to indent and reformat text
|
|
3005
|
+
blocks, paragraphs, lists and sentences. <a class="link" href="#X20" title="33.2. Vim Commands for Formatting AsciiDoc">Tips for <span class="emphasis"><em>vim</em></span> users</a>
|
|
3006
|
+
follow.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="X20"></a>33.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>33.2.1. Text Wrap Paragraphs</h4></div></div></div><p>Use the vim <code class="literal">:gq</code> command to reformat paragraphs. Setting the
|
|
3007
|
+
<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>
|
|
3008
|
+
Position the cursor at the start of the paragraph.
|
|
3009
|
+
</li><li>
|
|
3010
|
+
Type <code class="literal">gq}</code>.
|
|
3011
|
+
</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>
|
|
3012
|
+
Assign the <code class="literal">gq}</code> command to the Q key with the <code class="literal">nnoremap Q gq}</code>
|
|
3013
|
+
command or put it in your <code class="literal">~/.vimrc</code> file to so it’s always
|
|
3014
|
+
available (see the <a class="link" href="#X61" title="33.2.4. Example ~/.vimrc File">Example <code class="literal">~/.vimrc</code> file</a>).
|
|
3015
|
+
</li><li>
|
|
3016
|
+
Put <code class="literal">set</code> commands in your <code class="literal">~/.vimrc</code> file so you don’t have to
|
|
3017
|
+
enter them manually.
|
|
3018
|
+
</li><li>
|
|
3019
|
+
The Vim website (<a class="ulink" href="http://www.vim.org" target="_top">http://www.vim.org</a>) has a wealth of resources,
|
|
3020
|
+
including scripts for automated spell checking and ASCII Art
|
|
3021
|
+
drawing.
|
|
3022
|
+
</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>33.2.2. Format Lists</h4></div></div></div><p>The <code class="literal">gq</code> command can also be used to format bulleted, numbered and
|
|
3023
|
+
callout lists. First you need to set the <code class="literal">comments</code>, <code class="literal">formatoptions</code>
|
|
3024
|
+
and <code class="literal">formatlistpat</code> (see the <a class="link" href="#X61" title="33.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
|
|
3025
|
+
plus bullets along with numbered ordered lists:</p><div class="orderedlist"><ol type="1"><li>
|
|
3026
|
+
Position the cursor at the start of the list.
|
|
3027
|
+
</li><li>
|
|
3028
|
+
Type <code class="literal">gq}</code>.
|
|
3029
|
+
</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>33.2.3. Indent Paragraphs</h4></div></div></div><p>Indent whole paragraphs by indenting the fist line with the desired
|
|
3030
|
+
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>33.2.4. Example <code class="literal">~/.vimrc</code> File</h4></div></div></div><pre class="screen">" Show tabs and trailing characters.
|
|
3031
|
+
set listchars=tab:»·,trail:·
|
|
3032
|
+
set list
|
|
3033
|
+
|
|
3034
|
+
" Don't highlight searched text.
|
|
3035
|
+
highlight clear Search
|
|
3036
|
+
|
|
3037
|
+
" Don't move to matched text while search pattern is being entered.
|
|
3038
|
+
set noincsearch
|
|
3039
|
+
|
|
3040
|
+
" Reformat paragraphs and list.
|
|
3041
|
+
nnoremap R gq}
|
|
3042
|
+
|
|
3043
|
+
" Delete trailing white space and Dos-returns and to expand tabs to spaces.
|
|
3044
|
+
nnoremap S :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR>
|
|
3045
|
+
|
|
3046
|
+
autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
|
|
3047
|
+
\ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc
|
|
3048
|
+
\ textwidth=70 wrap formatoptions=tcqn
|
|
3049
|
+
\ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
|
|
3050
|
+
\ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:></pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_troubleshooting"></a>33.3. Troubleshooting</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li>
|
|
3051
|
+
The <code class="literal">asciidoc(1)</code> <code class="literal">-v</code> (<code class="literal">--verbose</code>) command-line option displays the
|
|
3052
|
+
order of configuration file loading and warns of potential
|
|
3053
|
+
configuration file problems.
|
|
3054
|
+
</li><li>
|
|
3055
|
+
Not all valid <span class="emphasis"><em>AsciiDoc</em></span> documents produce valid backend markup. Read
|
|
3056
|
+
the <a class="link" 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
|
|
3057
|
+
as non-conformant by a backend processor.
|
|
3058
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_gotchas"></a>33.4. Gotchas</h3></div></div></div><div class="variablelist"><dl><dt><span class="term">
|
|
3059
|
+
Incorrect character encoding
|
|
3060
|
+
</span></dt><dd>
|
|
3061
|
+
If you get an error message like ‘'UTF-8’ codec can’t decode …`
|
|
3062
|
+
then you source file contains invalid UTF-8 characters — set the
|
|
3063
|
+
<span class="emphasis"><em>AsciiDoc</em></span> <a class="link" href="#X54" title="???TITLE???">encoding attribute</a> for the correct character set
|
|
3064
|
+
(typically ISO-8859-1 (Latin-1) for European languages).
|
|
3065
|
+
</dd><dt><span class="term">
|
|
3066
|
+
Misinterpreted text formatting
|
|
3067
|
+
</span></dt><dd><p>
|
|
3068
|
+
If text in your document is incorrectly interpreted as formatting
|
|
3069
|
+
instructions you can suppress formatting by placing a backslash
|
|
3070
|
+
character immediately in front of the leading quote character(s).
|
|
3071
|
+
For example in the following line the backslash prevents text
|
|
3072
|
+
between the two asterisks from being output in a strong (bold)
|
|
3073
|
+
font:
|
|
3074
|
+
</p><pre class="literallayout">Add `\*.cs` files and `*.resx` files.</pre></dd><dt><span class="term">
|
|
3075
|
+
Overlapping text formatting
|
|
3076
|
+
</span></dt><dd><p>
|
|
3077
|
+
Overlapping text formatting will generate illegal overlapping
|
|
3078
|
+
markup tags which will result in downstream XML parsing errors.
|
|
3079
|
+
Here’s an example:
|
|
3080
|
+
</p><pre class="literallayout">Some *strong markup _that overlaps* emphasized markup_.</pre></dd><dt><span class="term">
|
|
3081
|
+
Ambiguous underlines
|
|
3082
|
+
</span></dt><dd>
|
|
3083
|
+
A DelimitedBlock can immediately follow paragraph without an
|
|
3084
|
+
intervening blank line, but be careful, a single line paragraph
|
|
3085
|
+
underline may be misinterpreted as a section title underline
|
|
3086
|
+
resulting in a “closing block delimiter expected” error.
|
|
3087
|
+
</dd><dt><span class="term">
|
|
3088
|
+
Ambiguous ordered list items
|
|
3089
|
+
</span></dt><dd><p>
|
|
3090
|
+
Lines beginning with numbers at the end of sentences will be
|
|
3091
|
+
interpreted as ordered list items. The following example
|
|
3092
|
+
(incorrectly) begins a new list with item number 1999:
|
|
3093
|
+
</p><pre class="literallayout">He was last sighted in
|
|
3094
|
+
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
|
|
3095
|
+
problem will go unnoticed.</p></dd><dt><span class="term">
|
|
3096
|
+
Special characters in attribute values
|
|
3097
|
+
</span></dt><dd><p>
|
|
3098
|
+
Special character substitution precedes attribute substitution so
|
|
3099
|
+
if attribute values contain special characters you may, depending
|
|
3100
|
+
on the substitution context, need to escape the special characters
|
|
3101
|
+
yourself. For example:
|
|
3102
|
+
</p><pre class="literallayout">$ asciidoc -a 'companyname=Bill &amp; Ben' mydoc.txt</pre></dd><dt><span class="term">
|
|
3103
|
+
Macro attribute lists
|
|
3104
|
+
</span></dt><dd><p>
|
|
3105
|
+
If named attribute list entries are present then all string
|
|
3106
|
+
attribute values must be quoted. For example:
|
|
3107
|
+
</p><pre class="literallayout">["Desktop screenshot",width=32]</pre></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_combining_separate_documents"></a>33.5. Combining separate documents</h3></div></div></div><p>You have a number of stand-alone <span class="emphasis"><em>AsciiDoc</em></span> documents that you want to
|
|
3108
|
+
process as a single document. Simply processing them with a series of
|
|
3109
|
+
<code class="literal">include</code> macros won’t work because the documents contain (level 0)
|
|
3110
|
+
document titles. The solution is to create a top level wrapper
|
|
3111
|
+
document that redefines the document underlines, pushing them down one
|
|
3112
|
+
level. For example <code class="literal">combined.txt</code>:</p><pre class="screen">:titles.underlines: "__","==","--","~~","^^"
|
|
3113
|
+
|
|
3114
|
+
Combined Document Title
|
|
3115
|
+
_______________________
|
|
3116
|
+
|
|
3117
|
+
include::document1.txt[]
|
|
3118
|
+
|
|
3119
|
+
include::document2.txt[]
|
|
3120
|
+
|
|
3121
|
+
include::document3.txt[]</pre><p>The document titles in the included documents will now be processed as
|
|
3122
|
+
level 1 section titles.</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3123
|
+
Put a blank line between the <code class="literal">include</code> macro lines to ensure the
|
|
3124
|
+
title of the included document is not seen as part of the last
|
|
3125
|
+
paragraph of the previous document.
|
|
3126
|
+
</li><li>
|
|
3127
|
+
You won’t want document Headers (Author and Revision lines) in the
|
|
3128
|
+
included files — conditionally exclude them if they are necessary
|
|
3129
|
+
for stand-alone processing.
|
|
3130
|
+
</li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_processing_document_sections_separately"></a>33.6. Processing document sections separately</h3></div></div></div><p>You have divided your <span class="emphasis"><em>AsciiDoc</em></span> document into separate files (one per
|
|
3131
|
+
top level section) which are combined and processed with the following
|
|
3132
|
+
top level document:</p><pre class="screen">Combined Document Title
|
|
3133
|
+
=======================
|
|
3134
|
+
Joe Bloggs
|
|
3135
|
+
v1.0, 12-Aug-03
|
|
3136
|
+
|
|
3137
|
+
include::section1.txt[]
|
|
3138
|
+
|
|
3139
|
+
include::section2.txt[]
|
|
3140
|
+
|
|
3141
|
+
include::section3.txt[]</pre><p>You also want to process the section files as separate documents.
|
|
3142
|
+
This is easy because <code class="literal">asciidoc(1)</code> will quite happily process
|
|
3143
|
+
<code class="literal">section1.txt</code>, <code class="literal">section2.txt</code> and <code class="literal">section3.txt</code> separately — the
|
|
3144
|
+
resulting output documents contain the section but have no document
|
|
3145
|
+
title.</p><p>Use the <code class="literal">-s</code> (<code class="literal">--no-header-footer</code>) command-line option to suppress
|
|
3146
|
+
header and footer output, this is useful if the processed output is to
|
|
3147
|
+
be included in another file. For example:</p><pre class="literallayout">$ asciidoc -s -b docbook section1.txt</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_processing_document_snippets"></a>33.7. Processing document snippets</h3></div></div></div><p><code class="literal">asciidoc(1)</code> can be used as a filter, so you can pipe chunks of text
|
|
3148
|
+
through it. For example:</p><pre class="literallayout">$ echo 'Hello *World!*' | asciidoc -s -
|
|
3149
|
+
<div class="paragraph"><p>Hello <strong>World!</strong></p></div></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_badges_in_html_page_footers"></a>33.8. Badges in HTML page footers</h3></div></div></div><p>See the <code class="literal">[footer]</code> section in the <span class="emphasis"><em>AsciiDoc</em></span> distribution <code class="literal">xhtml11.conf</code>
|
|
3150
|
+
configuration file.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_pretty_printing_asciidoc_output"></a>33.9. Pretty printing AsciiDoc output</h3></div></div></div><p>If the indentation and layout of the <code class="literal">asciidoc(1)</code> output is not to your
|
|
3151
|
+
liking you can:</p><div class="orderedlist"><ol type="1"><li>
|
|
3152
|
+
Change the indentation and layout of configuration file markup
|
|
3153
|
+
template sections. The <code class="literal">{empty}</code> glossary entry is useful for
|
|
3154
|
+
outputting trailing blank lines in markup templates.
|
|
3155
|
+
</li><li><p>
|
|
3156
|
+
Use Dave Raggett’s <a class="ulink" href="http://tidy.sourceforge.net/" target="_top">HTML Tidy</a> program
|
|
3157
|
+
to tidy <code class="literal">asciidoc(1)</code> output. Example:
|
|
3158
|
+
</p><pre class="literallayout">$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml</pre></li><li><p>
|
|
3159
|
+
Use the <code class="literal">xmllint(1)</code> format option. Example:
|
|
3160
|
+
</p><pre class="literallayout">$ xmllint --format mydoc.xml</pre></li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_supporting_minor_docbook_dtd_variations"></a>33.10. Supporting minor DocBook DTD variations</h3></div></div></div><p>The conditional inclusion of DocBook SGML markup at the end of the
|
|
3161
|
+
distribution <code class="literal">docbook.conf</code> file illustrates how to support minor DTD
|
|
3162
|
+
variations. The included sections override corresponding entries from
|
|
3163
|
+
preceding sections.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_shipping_stand_alone_asciidoc_source"></a>33.11. Shipping stand-alone AsciiDoc source</h3></div></div></div><p>Reproducing presentation documents from someone else’s source has one
|
|
3164
|
+
major problem: unless your configuration files are the same as the
|
|
3165
|
+
creator’s you won’t get the same output.</p><p>The solution is to create a single backend specific configuration file
|
|
3166
|
+
using the <code class="literal">asciidoc(1)</code> <code class="literal">-c</code> (<code class="literal">--dump-conf</code>) command-line option. You
|
|
3167
|
+
then ship this file along with the <span class="emphasis"><em>AsciiDoc</em></span> source document plus the
|
|
3168
|
+
<code class="literal">asciidoc.py</code> script. The only end user requirement is that they have
|
|
3169
|
+
Python installed (and of course that they consider you a trusted
|
|
3170
|
+
source). This example creates a composite HTML configuration
|
|
3171
|
+
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
|
|
3172
|
+
these three files (and a Python interpreter) the recipient can
|
|
3173
|
+
regenerate the HMTL output:</p><pre class="literallayout">$ ./asciidoc.py -eb xhtml11 mydoc.txt</pre><p>The <code class="literal">-e</code> (<code class="literal">--no-conf</code>) option excludes the use of implicit
|
|
3174
|
+
configuration files, ensuring that only entries from the
|
|
3175
|
+
<code class="literal">mydoc-html.conf</code> configuration are used.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_inserting_blank_space"></a>33.12. Inserting blank space</h3></div></div></div><p>Adjust your style sheets to add the correct separation between block
|
|
3176
|
+
elements. Inserting blank paragraphs containing a single non-breaking
|
|
3177
|
+
space character <code class="literal">{nbsp}</code> works but is an ad hoc solution compared
|
|
3178
|
+
to using style sheets.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_closing_open_sections"></a>33.13. Closing open sections</h3></div></div></div><p>You can close off section tags up to level <code class="literal">N</code> by calling the
|
|
3179
|
+
<code class="literal">eval::[Section.setlevel(N)]</code> system macro. This is useful if you
|
|
3180
|
+
want to include a section composed of raw markup. The following
|
|
3181
|
+
example includes a DocBook glossary division at the top section level
|
|
3182
|
+
(level 0):</p><pre class="screen">ifdef::backend-docbook[]
|
|
3183
|
+
|
|
3184
|
+
eval::[Section.setlevel(0)]
|
|
3185
|
+
|
|
3186
|
+
+++++++++++++++++++++++++++++++
|
|
3187
|
+
<glossary>
|
|
3188
|
+
<title>Glossary</title>
|
|
3189
|
+
<glossdiv>
|
|
3190
|
+
...
|
|
3191
|
+
</glossdiv>
|
|
3192
|
+
</glossary>
|
|
3193
|
+
+++++++++++++++++++++++++++++++
|
|
3194
|
+
endif::backend-docbook[]</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="_validating_output_files"></a>33.14. Validating output files</h3></div></div></div><p>Use <code class="literal">xmllint(1)</code> to check the <span class="emphasis"><em>AsciiDoc</em></span> generated markup is both well
|
|
3195
|
+
formed and valid. Here are some examples:</p><pre class="literallayout">$ xmllint --nonet --noout --valid docbook-file.xml
|
|
3196
|
+
$ xmllint --nonet --noout --valid xhtml11-file.html
|
|
3197
|
+
$ xmllint --nonet --noout --valid --html html4-file.html</pre><p>The <code class="literal">--valid</code> option checks the file is valid against the document
|
|
3198
|
+
type’s DTD, if the DTD is not installed in your system’s catalog then
|
|
3199
|
+
it will be fetched from its Internet location. If you omit the
|
|
3200
|
+
<code class="literal">--valid</code> option the document will only be checked that it is well
|
|
3201
|
+
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>
|
|
3202
|
+
<a id="X8"></a> Block element
|
|
3203
|
+
</dt><dd><p>
|
|
3204
|
+
An <span class="emphasis"><em>AsciiDoc</em></span> block element is a document entity composed of one or
|
|
3205
|
+
more whole lines of text.
|
|
3206
|
+
</p></dd><dt>
|
|
3207
|
+
<a id="X34"></a> Inline element
|
|
3208
|
+
</dt><dd><p>
|
|
3209
|
+
<span class="emphasis"><em>AsciiDoc</em></span> inline elements occur within block element textual
|
|
3210
|
+
content, they perform formatting and substitution tasks.
|
|
3211
|
+
</p></dd><dt>
|
|
3212
|
+
Formal element
|
|
3213
|
+
</dt><dd><p>
|
|
3214
|
+
An <span class="emphasis"><em>AsciiDoc</em></span> block element that has a BlockTitle. Formal elements
|
|
3215
|
+
are normally listed in front or back matter, for example lists of
|
|
3216
|
+
tables, examples and figures.
|
|
3217
|
+
</p></dd><dt>
|
|
3218
|
+
Verbatim element
|
|
3219
|
+
</dt><dd><p>
|
|
3220
|
+
The word verbatim indicates that white space and line breaks in
|
|
3221
|
+
the source document are to be preserved in the output document.
|
|
3222
|
+
</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>
|
|
3223
|
+
A new set of quotes has been introduced which may match inline text
|
|
3224
|
+
in existing documents — if they do you’ll need to escape the
|
|
3225
|
+
matched text with backslashes.
|
|
3226
|
+
</li><li>
|
|
3227
|
+
The index entry inline macro syntax has changed — if your documents
|
|
3228
|
+
include indexes you may need to edit them.
|
|
3229
|
+
</li><li>
|
|
3230
|
+
Replaced <code class="literal">a2x(1)</code> <code class="literal">--no-icons</code> and <code class="literal">--no-copy</code> options with their
|
|
3231
|
+
negated equivalents: <code class="literal">--icons</code> and <code class="literal">--copy</code> respectively. The
|
|
3232
|
+
default behavior has also changed — the use of icons and copying of
|
|
3233
|
+
icon and CSS files must be specified explicitly with the <code class="literal">--icons</code>
|
|
3234
|
+
and <code class="literal">--copy</code> options.
|
|
3235
|
+
</li></ul></div><p>The rationale for the changes can be found in the <span class="emphasis"><em>AsciiDoc</em></span>
|
|
3236
|
+
<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
|
|
3237
|
+
constrained quotes syntax and the new index entry syntax then you can
|
|
3238
|
+
define the attribute <code class="literal">asciidoc7compatible</code> (for example by using the
|
|
3239
|
+
<code class="literal">-a asciidoc7compatible</code> command-line option).</p></td></tr></table></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
|
|
3240
|
+
directory) for install prerequisites and procedures. The distribution
|
|
3241
|
+
<code class="literal">Makefile.in</code> (used by <code class="literal">configure</code> to generate the <code class="literal">Makefile</code>) is the
|
|
3242
|
+
canonical installation procedure.</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>
|
|
3243
|
+
source files by inhibiting the execution of arbitrary code or the
|
|
3244
|
+
inclusion of arbitrary files.</p><p>The safe mode is enabled by default and can only be disabled using the
|
|
3245
|
+
<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>
|
|
3246
|
+
<code class="literal">eval</code>, <code class="literal">sys</code> and <code class="literal">sys2</code> executable attributes and block macros are
|
|
3247
|
+
not executed.
|
|
3248
|
+
</li><li>
|
|
3249
|
+
<code class="literal">include::<filename>[]</code> and <code class="literal">\include1::<filename>[]</code> block macro
|
|
3250
|
+
files must reside inside the parent file’s directory.
|
|
3251
|
+
</li><li>
|
|
3252
|
+
<code class="literal">{include:<filename>}</code> executable attribute files must reside
|
|
3253
|
+
inside the source document directory.
|
|
3254
|
+
</li><li>
|
|
3255
|
+
Passthrough Blocks are dropped.
|
|
3256
|
+
</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>
|
|
3257
|
+
configuration files. Be especially careful when:</p><div class="orderedlist"><ol type="1"><li>
|
|
3258
|
+
Implementing filters.
|
|
3259
|
+
</li><li>
|
|
3260
|
+
Implementing elements that don’t escape special characters.
|
|
3261
|
+
</li><li>
|
|
3262
|
+
Accepting configuration files from untrusted sources.
|
|
3263
|
+
</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
|
|
3264
|
+
you need to be aware of:</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
3265
|
+
If you are generating output documents using a DocBook toolchain
|
|
3266
|
+
then you should set the <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">lang</code> attribute to the appropriate
|
|
3267
|
+
language (it defaults to <code class="literal">en</code> (English)). This will ensure things
|
|
3268
|
+
like table of contents, revision history, figure and table captions
|
|
3269
|
+
and admonition captions are output in the specified language.
|
|
3270
|
+
For example:
|
|
3271
|
+
</p><pre class="literallayout">$ a2x -a lang=es doc/article.txt</pre></li><li>
|
|
3272
|
+
If you are outputting html or xhtml directly from <code class="literal">asciidoc(1)</code> you’ll
|
|
3273
|
+
need to set the various <code class="literal">*_caption</code> attributes to match your target
|
|
3274
|
+
language (see the list of captions and titles in the <code class="literal">[attributes]</code>
|
|
3275
|
+
section of the default <code class="literal">asciidoc.conf</code> file). The easiest way is to
|
|
3276
|
+
create a language <code class="literal">.conf</code> file (see the example <code class="literal">lang-es.conf</code> file
|
|
3277
|
+
that comes with the <span class="emphasis"><em>AsciiDoc</em></span> distribution).
|
|
3278
|
+
</li><li>
|
|
3279
|
+
<code class="literal">asciidoc(1)</code> automatically loads configuration files named like
|
|
3280
|
+
<code class="literal">lang-<lang>.conf</code> where <code class="literal"><lang></code> is a two letter language code that
|
|
3281
|
+
matches the current <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">lang</code> attribute. See also
|
|
3282
|
+
<a class="link" href="#X27" title="21.11. Configuration File Names and Locations">Configuration File Names and Locations</a>.
|
|
3283
|
+
</li><li>
|
|
3284
|
+
Some character sets display double-width characters (for example
|
|
3285
|
+
Japanese). As far as <a class="link" href="#X17" title="8. Titles">title underlines</a> are concerned they
|
|
3286
|
+
should be treated as single character. If you think this looks
|
|
3287
|
+
untidy so you may prefer to use the <a class="link" href="#X46" title="8.2. One line titles">single line title</a>
|
|
3288
|
+
format.
|
|
3289
|
+
</li></ul></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="_vim_syntax_highlighter"></a>E. Vim Syntax Highlighter</h2><p>The <span class="emphasis"><em>AsciiDoc</em></span> <code class="literal">./vim/</code> distribution directory contains Vim syntax
|
|
3290
|
+
highlighter and filetype detection scripts for <span class="emphasis"><em>AsciiDoc</em></span>. Syntax
|
|
3291
|
+
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
|
|
3292
|
+
(<code class="literal">install.sh</code>) will automatically install the vim scripts in the Vim
|
|
3293
|
+
global configuration directory (<code class="literal">/etc/vim</code>).</p><p>You can also turn on syntax highlighting by adding the following line
|
|
3294
|
+
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
|
|
3295
|
+
<span class="emphasis"><em>AsciiDoc</em></span> which can be found here
|
|
3296
|
+
<a class="ulink" 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 class="ulink" href="http://xpt.sourceforge.net/" target="_top">*Nix Power Tools
|
|
3297
|
+
project</a> has released an
|
|
3298
|
+
<a class="ulink" href="http://xpt.sourceforge.net/tools/doc-mode/" target="_top"><span class="emphasis"><em>AsciiDoc</em></span> syntax highlighter
|
|
3299
|
+
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>E.1. Limitations</h3></div></div></div><p>The current implementation does a reasonable job but on occasions gets
|
|
3300
|
+
things wrong. This list of limitations also discusses how to work
|
|
3301
|
+
around the problems:</p><div class="itemizedlist"><ul type="disc"><li>
|
|
3302
|
+
Indented lists with preceding blank lines are sometimes mistaken
|
|
3303
|
+
for literal (indented) paragraphs. You can work around this by
|
|
3304
|
+
deleting the preceding blank line, or inserting a space in the
|
|
3305
|
+
preceding blank lines, or putting a list continuation character
|
|
3306
|
+
(<code class="literal">+</code>) in the preceding blank line.
|
|
3307
|
+
</li><li>
|
|
3308
|
+
Nested quoted text formatting is highlighted according to the outer
|
|
3309
|
+
format.
|
|
3310
|
+
</li><li>
|
|
3311
|
+
If a closing block delimiter is not preceded by a blank line it is
|
|
3312
|
+
sometimes mistaken for a title underline. A workaround is to insert
|
|
3313
|
+
a blank line before the closing delimiter.
|
|
3314
|
+
</li><li>
|
|
3315
|
+
If a list block delimiter is mistaken for a title underline precede
|
|
3316
|
+
it with a blank line.
|
|
3317
|
+
</li><li><p>
|
|
3318
|
+
Lines within a paragraph beginning with a period will be highlighted
|
|
3319
|
+
as block titles. For example:
|
|
3320
|
+
</p><pre class="literallayout">.chm file.</pre><p>To work around this restriction move the last word of the previous
|
|
3321
|
+
line to the start of the current (although words starting with a
|
|
3322
|
+
period should probably be quoted monospace which would also get around
|
|
3323
|
+
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
|
|
3324
|
+
that appear blank but contain white space characters — setting your
|
|
3325
|
+
editor options so that white space characters are visible is a good
|
|
3326
|
+
idea.</p></td></tr></table></div></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="X74"></a>F. Attribute Options</h2><p>Here is the list of predefined <a class="link" href="#X75" title="24.1. Options attribute">attribute list options</a>:</p><div class="informaltable"><table cellpadding="4px" style="border-collapse: collapse;border-top: 2px solid #527bbd; border-bottom: 2px solid #527bbd; border-left: 2px solid #527bbd; border-right: 2px solid #527bbd; "><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead valign="top"><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Option</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Backends</th><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><span class="emphasis"><em>AsciiDoc</em></span> Elements</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Description</th></tr></thead><tbody valign="top"><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>compact</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>docbook, xhtml11</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>bulleted list, numbered list</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Minimizes vertical space in the list</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>strong</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>xhtml11,html4</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>labeled lists</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Emboldens label text.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>footer</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>docbook, xhtml11, html4</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>table</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>The last row of the table is rendered as a footer.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>header</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>docbook, xhtml11, html4</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>table</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>The first row of the table is rendered as a header.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>breakable, unbreakable</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>docbook (XSL/FO)</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>table</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>The <span class="emphasis"><em>breakable</em></span> options allows the table to break across page
|
|
3327
|
+
boundaries (the default behavior); <span class="emphasis"><em>unbreakable</em></span> attempts to keep the
|
|
3328
|
+
table together on a single page. If neither option is specified the
|
|
3329
|
+
default XSL stylesheet behavior prevails.</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>pgwide</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>docbook (XSL/FO)</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>table, block image, horizontal labeled list</p></td><td style="" align="left" valign="top"><p>Specifies that the element should be rendered across the full text
|
|
3330
|
+
width of the page irrespective of the current indentation.</p></td></tr></tbody></table></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id2528525" href="#id2528525" class="simpara">1</a>] </sup>This is a rough structural guide, not a rigorous syntax
|
|
3331
|
+
definition</p></div><div class="footnote"><p><sup>[<a id="ftn.id2533619" href="#id2533619" class="simpara">2</a>] </sup>An example footnote.</p></div><div class="footnote"><p><sup>[<a id="ftn.note2" href="#note2" class="simpara">3</a>] </sup>Second footnote</p></div><div class="footnote"><p><sup>[<a id="ftn.id2541424" href="#id2541424" class="simpara">4</a>] </sup>The existence of a <code class="literal">{revisionhistory}</code> attribute causes a
|
|
3332
|
+
revision history file (if it exists) to be included in DocBook
|
|
3333
|
+
outputs. If a file named like <code class="literal">{docname}-revhistory.xml</code> exists in
|
|
3334
|
+
the document’s directory then it will be added verbatim to the DocBook
|
|
3335
|
+
header (see the <code class="literal">./doc/asciidoc-revhistory.xml</code> example that comes
|
|
3336
|
+
with the <span class="emphasis"><em>AsciiDoc</em></span> distribution).</p></div><div class="footnote"><p><sup>[<a id="ftn.id2543097" href="#id2543097" class="simpara">5</a>] </sup>Conditional inclusion using <code class="literal">ifdef</code> and <code class="literal">ifndef</code> macros
|
|
3337
|
+
differs from attribute conditional inclusion in that the former
|
|
3338
|
+
occurs when the file is read while the latter occurs when the
|
|
3339
|
+
contents are written.</p></div></div></div></body></html>
|