diff options
Diffstat (limited to 'chunked/ch08.html')
| -rw-r--r-- | chunked/ch08.html | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/chunked/ch08.html b/chunked/ch08.html new file mode 100644 index 0000000..401e06b --- /dev/null +++ b/chunked/ch08.html @@ -0,0 +1,301 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 8. Document Structure</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ch07.html" title="Chapter 7. HTML5 and XHTML 1.1" /><link rel="next" href="ch09.html" title="Chapter 9. Document Processing" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch07.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch09.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_document_structure"></a>Chapter 8. Document Structure</h1></div></div></div><p>An AsciiDoc document consists of a series of <a class="link" href="go01.html#X8">block elements</a> +starting with an optional document Header, followed by an optional +Preamble, followed by zero or more document Sections.</p><p>Almost any combination of zero or more elements constitutes a valid +AsciiDoc document: documents can range from a single sentence to a +multi-part book.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_block_elements"></a>8.1. Block Elements</h2></div></div></div><p>Block elements consist of one or more lines of text and may contain +other block elements.</p><p>The AsciiDoc block structure can be informally summarized as follows +<a href="#ftn.idm531" class="footnote" id="idm531"><sup class="footnote">[1]</sup></a>:</p><pre class="literallayout">Document ::= (Header?,Preamble?,Section*) +Header ::= (Title,(AuthorInfo,RevisionInfo?)?) +AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?) +RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?) +Preamble ::= (SectionBody) +Section ::= (Title,SectionBody?,(Section)*) +SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+ +Block ::= (Paragraph|DelimitedBlock|List|Table) +List ::= (BulletedList|NumberedList|LabeledList|CalloutList) +BulletedList ::= (ListItem)+ +NumberedList ::= (ListItem)+ +CalloutList ::= (ListItem)+ +LabeledList ::= (ListEntry)+ +ListEntry ::= (ListLabel,ListItem) +ListLabel ::= (ListTerm+) +ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)</pre><p>Where:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<span class="emphasis"><em>?</em></span> implies zero or one occurrence, <span class="emphasis"><em>+</em></span> implies one or more + occurrences, <span class="emphasis"><em>*</em></span> implies zero or more occurrences. +</li><li class="listitem"> +All block elements are separated by line boundaries. +</li><li class="listitem"> +<code class="literal">BlockId</code>, <code class="literal">AttributeEntry</code> and <code class="literal">AttributeList</code> block elements (not + shown) can occur almost anywhere. +</li><li class="listitem"> +There are a number of document type and backend specific + restrictions imposed on the block syntax. +</li><li class="listitem"> +The following elements cannot contain blank lines: Header, Title, + Paragraph, ItemText. +</li><li class="listitem"> +A ListParagraph is a Paragraph with its <span class="emphasis"><em>listelement</em></span> option set. +</li><li class="listitem"> +A ListContinuation is a <a class="link" href="ch17.html#X15" title="17.7. List Item Continuation">list continuation element</a>. +</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X95"></a>8.2. Header</h2></div></div></div><p>The Header contains document meta-data, typically title plus optional +authorship and revision information:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +The Header is optional, but if it is used it must start with a + document <a class="link" href="ch11.html" title="Chapter 11. Titles">title</a>. +</li><li class="listitem"> +Optional Author and Revision information immediately follows the + header title. +</li><li class="listitem"> +The document header must be separated from the remainder of the + document by one or more blank lines and cannot contain blank lines. +</li><li class="listitem"> +The header can include comments. +</li><li class="listitem"> +The header can include <a class="link" href="ch28.html" title="Chapter 28. Attribute Entries">attribute entries</a>, typically + <span class="emphasis"><em>doctype</em></span>, <span class="emphasis"><em>lang</em></span>, <span class="emphasis"><em>encoding</em></span>, <span class="emphasis"><em>icons</em></span>, <span class="emphasis"><em>data-uri</em></span>, <span class="emphasis"><em>toc</em></span>, + <span class="emphasis"><em>numbered</em></span>. +</li><li class="listitem"> +Header attributes are overridden by command-line attributes. +</li><li class="listitem"> +If the header contains non-UTF-8 characters then the <span class="emphasis"><em>encoding</em></span> must + precede the header (either in the document or on the command-line). +</li></ul></div><p>Here’s an example AsciiDoc document header:</p><pre class="literallayout">Writing Documentation using AsciiDoc +==================================== +Joe Bloggs <jbloggs@mymail.com> +v2.0, February 2003: +Rewritten for version 2 release.</pre><p>The author information line contains the author’s name optionally +followed by the author’s email address. The author’s name is formatted +like:</p><pre class="literallayout">firstname[ [middlename ]lastname][ <email>]]</pre><p>i.e. a first name followed by optional middle and last names followed +by an email address in that order. Multi-word first, middle and last +names can be entered using the underscore as a word separator. The +email address comes last and must be enclosed in angle <> brackets. +Here a some examples of author information lines:</p><pre class="literallayout">Joe Bloggs <jbloggs@mymail.com> +Joe Bloggs +Vincent Willem van_Gogh</pre><p>If the author line does not match the above specification then the +entire author line is treated as the first name.</p><p>The optional revision information line follows the author information +line. The revision information can be one of two formats:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara"> +An optional document revision number followed by an optional + revision date followed by an optional revision remark: +</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +If the revision number is specified it must be followed by a + comma. +</li><li class="listitem"> +The revision number must contain at least one numeric character. +</li><li class="listitem"> +Any non-numeric characters preceding the first numeric character + will be dropped. +</li><li class="listitem"> +If a revision remark is specified it must be preceded by a colon. + The revision remark extends from the colon up to the next blank + line, attribute entry or comment and is subject to normal text + substitutions. +</li><li class="listitem"> +If a revision number or remark has been set but the revision date + has not been set then the revision date is set to the value of the + <span class="emphasis"><em>docdate</em></span> attribute. +</li></ul></div><p class="simpara">Examples:</p><pre class="literallayout">v2.0, February 2003 +February 2003 +v2.0, +v2.0, February 2003: Rewritten for version 2 release. +February 2003: Rewritten for version 2 release. +v2.0,: Rewritten for version 2 release. +:Rewritten for version 2 release.</pre></li><li class="listitem"><p class="simpara"> +The revision information line can also be an RCS/CVS/SVN $Id$ + marker: +</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +AsciiDoc extracts the <span class="emphasis"><em>revnumber</em></span>, <span class="emphasis"><em>revdate</em></span>, and <span class="emphasis"><em>author</em></span> + attributes from the $Id$ revision marker and displays them in the + document header. +</li><li class="listitem"> +If an $Id$ revision marker is used the header author line can be + omitted. +</li></ul></div><p class="simpara">Example:</p><pre class="literallayout">$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $</pre></li></ol></div><p>You can override or set header parameters by passing <span class="emphasis"><em>revnumber</em></span>, +<span class="emphasis"><em>revremark</em></span>, <span class="emphasis"><em>revdate</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 <span class="emphasis"><em>lastname</em></span> attributes using the asciidoc(1) <code class="literal">-a</code> +(<code class="literal">--attribute</code>) command-line option. For example:</p><pre class="literallayout">$ asciidoc -a revdate=2004/07/27 article.txt</pre><p>Attribute entries can also be added to the header for substitution in +the header template with <a class="link" href="ch28.html" title="Chapter 28. Attribute Entries">Attribute Entry</a> elements.</p><p>The <span class="emphasis"><em>title</em></span> element in HTML outputs is set to the AsciiDoc document +title, you can set it to a different value by including a <span class="emphasis"><em>title</em></span> +attribute entry in the document header.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="X87"></a>8.2.1. Additional document header information</h3></div></div></div><p>AsciiDoc has two mechanisms for optionally including additional +meta-data in the header of the output document:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +<span class="emphasis"><em>docinfo</em></span> configuration file sections +</span></dt><dd> +If a <a class="link" href="ch26.html" title="Chapter 26. Configuration Files">configuration file</a> section named <span class="emphasis"><em>docinfo</em></span> has been loaded +then it will be included in the document header. Typically the +<span class="emphasis"><em>docinfo</em></span> section name will be prefixed with a <span class="emphasis"><em>+</em></span> character so that it +is appended to (rather than replace) other <span class="emphasis"><em>docinfo</em></span> sections. +</dd><dt><span class="term"> +<span class="emphasis"><em>docinfo</em></span> files +</span></dt><dd> +Two docinfo files are recognized: one named <code class="literal">docinfo</code> and a second +named like the AsciiDoc source file with a <code class="literal">-docinfo</code> suffix. For +example, if the source document is called <code class="literal">mydoc.txt</code> then the +document information files would be <code class="literal">docinfo.xml</code> and +<code class="literal">mydoc-docinfo.xml</code> (for DocBook outputs) and <code class="literal">docinfo.html</code> and +<code class="literal">mydoc-docinfo.html</code> (for HTML outputs). The <a class="link" href="aph.html#X97">docinfo</a> attributes control which docinfo files are included in +the output files. +</dd></dl></div><p>The contents docinfo templates and files is dependent on the type of +output:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +HTML +</span></dt><dd> + Valid <span class="emphasis"><em>head</em></span> child elements. Typically <span class="emphasis"><em>style</em></span> and <span class="emphasis"><em>script</em></span> elements + for CSS and JavaScript inclusion. +</dd><dt><span class="term"> +DocBook +</span></dt><dd> + Valid <span class="emphasis"><em>articleinfo</em></span> or <span class="emphasis"><em>bookinfo</em></span> child elements. DocBook defines + numerous elements for document meta-data, for example: copyrights, + document history and authorship information. See the DocBook + <code class="literal">./doc/article-docinfo.xml</code> example that comes with the AsciiDoc + distribution. The rendering of meta-data elements (or not) is + DocBook processor dependent. +</dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X86"></a>8.3. Preamble</h2></div></div></div><p>The Preamble is an optional untitled section body between the document +Header and the first Section title.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_sections"></a>8.4. Sections</h2></div></div></div><p>In addition to the document title (level 0), AsciiDoc supports four +section levels: 1 (top) to 4 (bottom). Section levels are delimited +by section <a class="link" href="ch11.html" title="Chapter 11. Titles">titles</a>. Sections are translated using +configuration file <a class="link" href="ch08.html#X93" title="8.4.1. Section markup templates">section markup templates</a>. AsciiDoc +generates the following <a class="link" href="ch31.html" title="Chapter 31. Intrinsic Attributes">intrinsic attributes</a> specifically for +use in section markup templates:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +level +</span></dt><dd> +The <code class="literal">level</code> attribute is the section level number, it is normally just +the <a class="link" href="ch11.html" title="Chapter 11. Titles">title</a> level number (1..4). However, if the <code class="literal">leveloffset</code> +attribute is defined it will be added to the <code class="literal">level</code> attribute. The +<code class="literal">leveloffset</code> attribute is useful for <a class="link" href="ch36.html#X90" title="36.5. Combining separate documents">combining documents</a>. +</dd><dt><span class="term"> +sectnum +</span></dt><dd> +The <code class="literal">-n</code> (<code class="literal">--section-numbers</code>) command-line option generates the +<code class="literal">sectnum</code> (section number) attribute. The <code class="literal">sectnum</code> attribute is used +for section numbers in HTML outputs (DocBook section numbering are +handled automatically by the DocBook toolchain commands). +</dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="X93"></a>8.4.1. Section markup templates</h3></div></div></div><p>Section markup templates specify output markup and are defined in +AsciiDoc configuration files. Section markup template names are +derived as follows (in order of precedence):</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara"> +From the title’s first positional attribute or <span class="emphasis"><em>template</em></span> + attribute. For example, the following three section titles are + functionally equivalent: +</p><pre class="literallayout">[[terms]] +[glossary] +List of Terms +------------- + +["glossary",id="terms"] +List of Terms +------------- + +[template="glossary",id="terms"] +List of Terms +-------------</pre></li><li class="listitem"> +When the title text matches a configuration file + <a class="link" href="ch08.html#X16" title="8.4.3. Special Section Titles"><code class="literal">[specialsections]</code></a> entry. +</li><li class="listitem"> +If neither of the above the default <code class="literal">sect<level></code> template is used + (where <code class="literal"><level></code> is a number from 1 to 4). +</li></ol></div><p>In addition to the normal section template names (<span class="emphasis"><em>sect1</em></span>, <span class="emphasis"><em>sect2</em></span>, +<span class="emphasis"><em>sect3</em></span>, <span class="emphasis"><em>sect4</em></span>) AsciiDoc has the following templates for +frontmatter, backmatter and other special sections: <span class="emphasis"><em>abstract</em></span>, +<span class="emphasis"><em>preface</em></span>, <span class="emphasis"><em>colophon</em></span>, <span class="emphasis"><em>dedication</em></span>, <span class="emphasis"><em>glossary</em></span>, <span class="emphasis"><em>bibliography</em></span>, +<span class="emphasis"><em>synopsis</em></span>, <span class="emphasis"><em>appendix</em></span>, <span class="emphasis"><em>index</em></span>. These special section templates +generate the corresponding Docbook elements; for HTML outputs they +default to the <span class="emphasis"><em>sect1</em></span> section template.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_section_ids"></a>8.4.2. Section IDs</h3></div></div></div><p>If no explicit section ID is specified an ID will be synthesised from +the section title. The primary purpose of this feature is to ensure +persistence of table of contents links (permalinks): the missing +section IDs are generated dynamically by the JavaScript TOC generator +<span class="strong"><strong>after</strong></span> the page is loaded. If you link to a dynamically generated TOC +address the page will 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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +Replace all non-alphanumeric title characters with underscores. +</li><li class="listitem"> +Strip leading or trailing underscores. +</li><li class="listitem"> +Convert to lowercase. +</li><li class="listitem"> +Prepend the <code class="literal">idprefix</code> attribute (so there’s no possibility of name + clashes with existing document IDs). Prepend an underscore if the + <code class="literal">idprefix</code> attribute is not defined. +</li><li class="listitem"> +A numbered suffix (<code class="literal">_2</code>, <code class="literal">_3</code> …) is added if a same named + auto-generated section ID exists. +</li><li class="listitem"> +If the <code class="literal">ascii-ids</code> attribute is defined then non-ASCII characters + are replaced with ASCII equivalents. This attribute should be + <span class="strong"><strong>should be avoided</strong></span> if possible as its sole purpose is to accommodate + deficient downstream applications that cannot process non-ASCII ID + attributes. If available, it will use the + <a class="ulink" href="https://pypi.org/project/trans/" target="_top">trans python module</a>, otherwise it + will fallback to using NFKD algorithm, which cannot handle all + unicode characters. For example, <span class="emphasis"><em>Wstęp żółtej łąki</em></span> will be + translated to <span class="emphasis"><em>Wstep zoltej laki</em></span> under trans and <span class="emphasis"><em>Wstep zotej aki</em></span> + under NFKD. +</li></ul></div><p>Example: the title <span class="emphasis"><em>Jim’s House</em></span> would generate the ID <code class="literal">_jim_s_house</code>.</p><p>Section ID synthesis can be disabled by undefining the <code class="literal">sectids</code> +attribute.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="X16"></a>8.4.3. Special Section Titles</h3></div></div></div><p>AsciiDoc has a mechanism for mapping predefined section titles +auto-magically to specific markup templates. For example a title +<span class="emphasis"><em>Appendix A: Code Reference</em></span> will automatically use the <span class="emphasis"><em>appendix</em></span> +<a class="link" href="ch08.html#X93" title="8.4.1. Section markup templates">section markup template</a>. The mappings from title to template +name are specified in <code class="literal">[specialsections]</code> sections in the Asciidoc +language configuration files (<code class="literal">lang-*.conf</code>). Section entries are +formatted like:</p><pre class="literallayout"><title>=<template></pre><p><code class="literal"><title></code> is a Python regular expression and <code class="literal"><template></code> is the name +of a configuration file markup template section. If the <code class="literal"><title></code> +matches an AsciiDoc document section title then the backend output is +marked up using the <code class="literal"><template></code> markup template (instead of the +default <code class="literal">sect<level></code> section template). The <code class="literal">{title}</code> attribute value +is set to the value of the matched regular expression group named +<span class="emphasis"><em>title</em></span>, if there is no <span class="emphasis"><em>title</em></span> group <code class="literal">{title}</code> defaults to the whole +of the AsciiDoc section title. If <code class="literal"><template></code> is blank then any +existing entry with the same <code class="literal"><title></code> will be deleted.</p><div class="sidebar"><div class="titlepage"><div><div><p class="title"><strong>Special section titles vs. explicit template names</strong></p></div></div></div><p>AsciiDoc has two mechanisms for specifying non-default section markup +templates: you can specify the template name explicitly (using the +<span class="emphasis"><em>template</em></span> attribute) or indirectly (using <span class="emphasis"><em>special section titles</em></span>). +Specifying a <a class="link" href="ch08.html#X93" title="8.4.1. Section markup templates">section template</a> attribute explicitly is +preferred. Auto-magical <span class="emphasis"><em>special section titles</em></span> have the following +drawbacks:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +They are non-obvious, you have to know the exact matching + title for each special section on a language by language basis. +</li><li class="listitem"> +Section titles are predefined and can only be customised with a + configuration change. +</li><li class="listitem"> +The implementation is complicated by multiple languages: every + special section title has to be defined for each language (in each + of the <code class="literal">lang-*.conf</code> files). +</li></ul></div><p>Specifying special section template names explicitly does add more +noise to the source document (the <span class="emphasis"><em>template</em></span> attribute declaration), +but the intention is obvious and the syntax is consistent with other +AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.</p><p>Special section titles have been deprecated but are retained for +backward compatibility.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_inline_elements"></a>8.5. Inline Elements</h2></div></div></div><p><a class="link" href="go01.html#X34">Inline document elements</a> are used to format text and to +perform various types of text substitution. Inline elements and inline +element syntax is defined in the asciidoc(1) configuration files.</p><p>Here is a list of AsciiDoc inline elements in the (default) order in +which they are processed:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +Special characters +</span></dt><dd> + These character sequences escape special characters used by + the backend markup (typically <code class="literal"><</code>, <code class="literal">></code>, and <code class="literal">&</code> characters). + See <code class="literal">[specialcharacters]</code> configuration file sections. +</dd><dt><span class="term"> +Quotes +</span></dt><dd> + Elements that markup words and phrases; usually for character + formatting. See <code class="literal">[quotes]</code> configuration file sections. +</dd><dt><span class="term"> +Special Words +</span></dt><dd> + Word or word phrase patterns singled out for markup without + the need for further annotation. See <code class="literal">[specialwords]</code> + configuration file sections. +</dd><dt><span class="term"> +Replacements +</span></dt><dd> + Each replacement defines a word or word phrase pattern to + search for along with corresponding replacement text. See + <code class="literal">[replacements]</code> configuration file sections. +</dd><dt><span class="term"> +Attribute references +</span></dt><dd> + Document attribute names enclosed in braces are replaced by + the corresponding attribute value. +</dd><dt><span class="term"> +Inline Macros +</span></dt><dd> + Inline macros are replaced by the contents of parametrized + configuration file sections. +</dd></dl></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm531" class="footnote"><p><a href="#idm531" class="simpara"><sup class="simpara">[1] </sup></a>This is a rough structural guide, not a rigorous syntax +definition</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch07.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch09.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/icons/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
\ No newline at end of file |