- Added FAQ explaining how to override special section titles.

- Added {zwsp} (zero width space) attribute.
- Undefined paragraph styles are reported (previously threw a runtime error).
- Eliminated empty preamble generation.
- Floating titles now processed in all contexts.
- Updated example article and book documents with the recommended explicit
  special section syntax.
- Implemented auto-lettered appendix names
- Section numbering can be disabled in HTML outputs with a :numbered!:
  AttributeEntry.

21 files changed, 331 insertions, 146 deletions

diff --git a/asciidoc.conf b/asciidoc.conf
index 5a25908..6cf6d76 100644
--- a/asciidoc.conf
+++ b/asciidoc.conf
@@ -27,6 +27,7 @@ lt=<
 gt=>

 brvbar=|

 nbsp=&#160;

+zwsp=&#8203;

 wj=&#8288;

 deg=&#176;

 backslash=\

@@ -518,6 +519,36 @@ template::[pass-blockmacro]
 [passblock]

 |

 

+#----------------------------------

+# Default special section templates

+#----------------------------------

+[abstract]

+template::[sect1]

+

+[colophon]

+template::[sect1]

+

+[dedication]

+template::[sect1]

+

+[preface]

+template::[sect1]

+

+[appendix]

+template::[sect1]

+

+[glossary]

+template::[sect1]

+

+[bibliography]

+template::[sect1]

+

+[index]

+template::[sect1]

+

+[synopsis]

+template::[sect1]

+

 #--------------------------------------------------------------------

 # Deprecated old table definitions.

 #

diff --git a/asciidoc.py b/asciidoc.py
index 3971cf1..6705df7 100755
--- a/asciidoc.py
+++ b/asciidoc.py
@@ -1089,7 +1089,10 @@ class Lex:
         elif AttributeList.isnext():
             result = AttributeList
         elif Title.isnext():
-            result = Title
+            if AttributeList.style() == 'float':
+                result = FloatingTitle
+            else:
+                result = Title
         elif macros.isnext():
             result = macros.current
         elif lists.isnext():
@@ -1288,13 +1291,7 @@ class Document:
                 self.attributes[new] = self.attributes[old]
         else:
             self.attributes[old] = self.attributes[new]
-    def translate(self):
-        assert self.doctype in ('article','manpage','book'), \
-            'illegal document type'
-        assert self.level == 0
-        config.expand_all_templates()
-        self.load_lang()
-        # Skip leading comments and attribute entries.
+    def consume_attributes_and_comments(self):
         finished = False
         attr_count = 0
         while not finished:
@@ -1313,7 +1310,18 @@ class Document:
                     if attr_count > 0:
                         message.error('lang attribute should be first entry')
                 attr_count += 1
+            if AttributeList.isnext():
+                finished = False
+                AttributeList.translate()
+    def translate(self):
+        assert self.doctype in ('article','manpage','book'), \
+            'illegal document type'
+        assert self.level == 0
+        config.expand_all_templates()
+        self.load_lang()
         message.verbose('writing: '+writer.fname,False)
+        # Skip leading comments and attribute entries.
+        self.consume_attributes_and_comments()
         # Process document header.
         has_header =  Lex.next() is Title and Title.level == 0
         if self.doctype == 'manpage' and not has_header:
@@ -1329,6 +1337,7 @@ class Document:
             if config.header_footer:
                 hdr = config.subs_section('header',{})
                 writer.write(hdr,trace='header')
+            self.consume_attributes_and_comments()
             if self.doctype in ('article','book'):
                 # Translate 'preamble' (untitled elements between header
                 # and first section title).
@@ -1573,7 +1582,8 @@ class AttributeEntry:
             attr.name = re.sub(r'(?u)[^\w\-_]', '', attr.name).lower()
             # Don't override command-line attributes (the exception is the
             # system 'trace' attribute).
-            if attr.name in config.cmd_attrs and attr.name != 'trace':
+            if attr.name in config.cmd_attrs \
+                    and attr.name not in ('trace','numbered'):
                 return
             # Update document attributes with attribute value.
             if attr.value is not None:
@@ -1715,7 +1725,7 @@ class Title:
     def translate():
         """Parse the Title.attributes and Title.level from the reader. The
         real work has already been done by parse()."""
-        assert Lex.next() is Title
+        assert Lex.next() in (Title,FloatingTitle)
         # Discard title from reader.
         for i in range(Title.linecount):
             reader.read()
@@ -1877,6 +1887,25 @@ class Title:
         return number
 
 
+class FloatingTitle(Title):
+    '''Floated titles are translated differently.'''
+    @staticmethod
+    def isnext():
+        return Title.isnext() and AttributeList.style() == 'float'
+    @staticmethod
+    def translate():
+        assert Lex.next() is FloatingTitle
+        Title.translate()
+        Section.set_id()
+        AttributeList.consume(Title.attributes)
+        template = 'floatingtitle'
+        if template in config.sections:
+            stag,etag = config.section2tags(template,Title.attributes)
+            writer.write(stag,trace='floating title')
+        else:
+            message.warning('missing template section: [%s]' % template)
+
+
 class Section:
     """Static methods and attributes only."""
     endtags = []  # Stack of currently open section (level,endtag) tuples.
@@ -1963,23 +1992,10 @@ class Section:
         isempty = True
         next = Lex.next()
         while next and next is not terminator:
-            if (isinstance(terminator,DelimitedBlock)
-                and next is Title and AttributeList.style() != 'float'):
+            if isinstance(terminator,DelimitedBlock) and next is Title:
                 message.error('section title not permitted in delimited block')
             next.translate()
             next = Lex.next()
-            if next is Title and AttributeList.style() == 'float':
-                # Process floating titles.
-                template = 'floatingtitle'
-                if template in config.sections:
-                    Title.translate()
-                    Section.set_id()
-                    AttributeList.consume(Title.attributes)
-                    stag,etag = config.section2tags(template,Title.attributes)
-                    writer.write(stag,trace='floating title')
-                    next = Lex.next()
-                else:
-                    message.warning('missing template section: [%s]' % template)
             isempty = False
         # The section is not empty if contains a subsection.
         if next and isempty and Title.level > document.level:
@@ -2019,7 +2035,7 @@ class AbstractBlock:
         # Leading delimiter match object.
         self.mo=None
     def short_name(self):
-        """ Return the text following the last dash in the section namem """
+        """ Return the text following the last dash in the section name."""
         i = self.name.rfind('-')
         if i == -1:
             return self.name
@@ -2165,7 +2181,7 @@ class AbstractBlock:
         for k,v in self.styles.items():
             t = v.get('template')
             if t and not t in config.sections:
-                message.warning('[%s] missing template section' % t)
+                message.warning('missing template section: [%s]' % t)
             if not t:
                 all_styles_have_template = False
         # Check we have a valid template entry or alternatively that all the
@@ -2173,10 +2189,10 @@ class AbstractBlock:
         if self.is_conf_entry('template') and not 'skip' in self.options:
             if self.template:
                 if not self.template in config.sections:
-                    message.warning('[%s] missing template section' % self.template)
+                    message.warning('missing template section: [%s]' % self.template)
             elif not all_styles_have_template:
                 if not isinstance(self,List): # Lists don't have templates.
-                    message.warning('[%s] styles missing templates' % self.name)
+                    message.warning('missing styles templates: [%s]' % self.name)
     def isnext(self):
         """Check if this block is next in document reader."""
         result = False
@@ -2204,7 +2220,7 @@ class AbstractBlock:
 
         1. Copy the default parameters (self.*) to self.parameters.
         self.parameters are used internally to render the current block.
-        Optional params array of addtional parameters.
+        Optional params array of additional parameters.
 
         2. Copy attrs to self.attributes. self.attributes are used for template
         and tag substitution in the current block.
@@ -2244,14 +2260,21 @@ class AbstractBlock:
         # Load the selected style attributes.
         posattrs = self.posattrs
         if posattrs and posattrs[0] == 'style':
+            # Positional attribute style has highest precedence.
             style = self.attributes.get('1')
         else:
             style = None
         if not style:
+            # Use explicit style attribute, fall back to default style.
             style = self.attributes.get('style',self.style)
         if style:
             if not is_name(style):
-                raise EAsciiDoc, 'illegal style name: %s' % style
+                message.error('illegal style name: %s' % style)
+                style = self.style
+            # Lists have implicit styles and do their own style checks.
+            elif style not in self.styles and not isinstance(self,List):
+                message.warning('missing style: [%s]: %s' % (self.name,style))
+                style = self.style
             if style in self.styles:
                 self.attributes['style'] = style
                 for k,v in self.styles[style].items():
@@ -2381,7 +2404,7 @@ class Paragraphs(AbstractBlocks):
                 self.blocks.remove(b)
                 break
         else:
-            raise EAsciiDoc,'missing [paradef-default] section'
+            raise EAsciiDoc,'missing section: [paradef-default]'
 
 class List(AbstractBlock):
     NUMBER_STYLES= ('arabic','loweralpha','upperalpha','lowerroman',
@@ -3284,7 +3307,7 @@ class Tables(AbstractBlocks):
                 default = self.blocks[i]
                 break
         else:
-            raise EAsciiDoc,'missing [tabledef-default] section'
+            raise EAsciiDoc,'missing section: [tabledef-default]'
         # Propagate defaults to unspecified table parameters.
         for b in self.blocks:
             if b is not default:
@@ -3292,7 +3315,7 @@ class Tables(AbstractBlocks):
                 if b.template is None: b.template = default.template
         # Check tags and propagate default tags.
         if not 'default' in self.tags:
-            raise EAsciiDoc,'missing [tabletags-default] section'
+            raise EAsciiDoc,'missing section: [tabletags-default]'
         default = self.tags['default']
         for tag in ('bodyrow','bodydata','paragraph'): # Mandatory default tags.
             if tag not in default:
@@ -4332,7 +4355,7 @@ class Config:
             if not v:
                 del self.specialsections[k]
             elif not v in self.sections:
-                message.warning('[%s] missing specialsections section' % v)
+                message.warning('missing specialsections section: [%s]' % v)
         paragraphs.validate()
         lists.validate()
         blocks.validate()
@@ -4406,7 +4429,7 @@ class Config:
         if section in self.sections:
             return subs_attrs(self.sections[section],d)
         else:
-            message.warning('missing [%s] section' % section)
+            message.warning('missing section: [%s]' % section)
             return ()
 
     def parse_tags(self):
@@ -4561,7 +4584,7 @@ class Config:
                 if s in self.sections:
                     result += self.expand_templates(self.sections[s])
                 else:
-                    message.warning('missing [%s] section' % s)
+                    message.warning('missing section: [%s]' % s)
             else:
                 result.append(line)
         return result
@@ -4578,7 +4601,7 @@ class Config:
         if section in self.sections:
             body = self.sections[section]
         else:
-            message.warning('missing [%s] section' % section)
+            message.warning('missing section: [%s]' % section)
             body = ()
         # Split macro body into start and end tag lists.
         stag = []
@@ -5059,7 +5082,7 @@ class Tables_OLD(AbstractBlocks):
                 default = self.blocks[i]
                 break
         else:
-            raise EAsciiDoc,'missing [OLD_tabledef-default] section'
+            raise EAsciiDoc,'missing section: [OLD_tabledef-default]'
         # Set default table defaults.
         if default.format is None: default.subs = 'fixed'
         # Propagate defaults to unspecified table parameters.
diff --git a/doc/article.txt b/doc/article.txt
index c4b7050..b7754e4 100644
--- a/doc/article.txt
+++ b/doc/article.txt
@@ -11,8 +11,9 @@ NOTE: The abstract, preface, appendix, bibliography, glossary and
 index section titles are significant ('specialsections').

 

 

-Abstract

---------

+[abstract]

+Example Abstract

+----------------

 The optional abstract (one or more paragraphs) goes here.

 

 This document is an AsciiDoc article skeleton containing briefly

@@ -79,8 +80,12 @@ indexterm:[Second example index entry]
 

 An example link to a bibliography entry <<taoup>>.

 

-Appendix A: Example Appendix

-----------------------------

+

+:numbered!:

+

+[appendix]

+Example Appendix

+----------------

 AsciiDoc article appendices are just just article sections with

 'specialsection' titles.

 

@@ -89,8 +94,9 @@ Appendix Sub-section
 Appendix sub-section at level 2.

 

 

-Bibliography

-------------

+[bibliography]

+Example Bibliography

+--------------------

 The bibliography list is a style of AsciiDoc bulleted list.

 

 [bibliography]

@@ -101,8 +107,9 @@ The bibliography list is a style of AsciiDoc bulleted list.
   ISBN 1-56592-580-7.

 

 

-Glossary

---------

+[glossary]

+Example Glossary

+----------------

 Glossaries are optional. Glossaries entries are an example of a style

 of AsciiDoc labeled lists.

 

@@ -115,8 +122,9 @@ A second glossary term::
 

 

 ifdef::backend-docbook[]

-Index

------

+[index]

+Example Index

+-------------

 ////////////////////////////////////////////////////////////////

 The index is normally left completely empty, it's contents being

 generated automatically by the DocBook toolchain.

diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
index b7d519c..5803d86 100644
--- a/doc/asciidoc.conf
+++ b/doc/asciidoc.conf
@@ -3,6 +3,5 @@
 #

 [specialwords]

 ifndef::doctype-manpage[]

-emphasizedwords=(?u)\\?\bAsciiDoc\b

 monospacedwords=(?u)\\?\basciidoc\(1\) (?u)\\?\ba2x\(1\)

 endif::doctype-manpage[]

diff --git a/doc/asciidoc.dict b/doc/asciidoc.dict
index c33d482..9be9f17 100644
--- a/doc/asciidoc.dict
+++ b/doc/asciidoc.dict
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 835 
+personal_ws-1.1 en 837 
 mandoc
 colspecs
 API
@@ -26,8 +26,8 @@ LiteralParagraph
 BOM
 Bon
 ungenerated
-cmd
 des
+cmd
 ListItems
 dev
 vulputate
@@ -81,8 +81,8 @@ hhc
 Chai
 strongwords
 setlocal
-listingblock
 ListingBlock
+listingblock
 exe
 vsides
 rewriteSystem
@@ -92,8 +92,8 @@ listelement
 AttributeLists
 magna
 xreflabel
-PDFs
 PDF's
+PDFs
 MSIE
 permalinks
 Daly
@@ -106,8 +106,8 @@ ListContinuation
 apos
 ShareSource
 hoc
-Maier
 ispum
+Maier
 TableFooter
 blog
 passthroughs
@@ -216,9 +216,9 @@ BlockId
 png
 lobortis
 Bowlin
-ASCIIMathML
-AsciiMathML
 asciimathml
+AsciiMathML
+ASCIIMathML
 conf
 RCS
 CalloutList
@@ -235,6 +235,7 @@ Windtrainer
 eget
 sed
 userguide
+zwsp
 keeptogether
 bweb
 PRS
@@ -262,8 +263,8 @@ biggy
 pgwide
 crlf
 tex
-Bolido
 B�lido
+Bolido
 tabsize
 colpcwidth
 onload
@@ -276,8 +277,8 @@ listdef
 Tsawassen
 postsubs
 src
-lastname
 LastName
+lastname
 toc
 tmp
 Knisley
@@ -317,13 +318,13 @@ revisionhistory
 params
 undefines
 Andr�s
-HTMLHelp
 htmlhelp
+HTMLHelp
 cellspacing
 Citeaux
 srackham
-Lulea
 Lule�
+Lulea
 Ubuntu
 xml
 XSLTLib
@@ -356,8 +357,8 @@ gq
 refactored
 sgml
 backcolor
-asciidoc
 AsciiDoc
+asciidoc
 subslist
 hs
 hu
@@ -603,6 +604,7 @@ admonitionparagraph
 mantitle
 init
 VerbatimBlocks
+refsynopsisdiv
 emacs
 consetetur
 JIMI
@@ -812,8 +814,8 @@ Redhat
 datadir
 Kumar
 IndentedParagraphs
-Berguvsv�gen
 Berguvsvagen
+Berguvsv�gen
 executables
 tabledef
 ftdetect
@@ -831,6 +833,6 @@ Firefox
 JavaHelp
 unescaped
 mydoc
-MiddleName
 middlename
+MiddleName
 Jimmac's
diff --git a/doc/asciidoc.txt b/doc/asciidoc.txt
index 8a18b84..ba7a581 100644
--- a/doc/asciidoc.txt
+++ b/doc/asciidoc.txt
@@ -112,6 +112,10 @@ article
 Used for short documents, articles and general documentation.  See the
 AsciiDoc distribution `./doc/article.txt` example.
 
+AsciiDoc defines standard DocBook article frontmatter and backmatter
+<<X93,section markup templates>> (appendix, abstract, bibliography,
+glossary, index).
+
 book
 ~~~~
 Books share the same format as articles; in addition there is the
@@ -122,9 +126,9 @@ DocBook processors can automatically generate footnotes, table of
 contents, list of tables, list of figures, list of examples and
 indexes.
 
-AsciiDoc markup supports standard DocBook frontmatter and backmatter
-<<X16,special sections>> (dedication, preface, bibliography, glossary,
-index, colophon) plus footnotes and index entries.
+AsciiDoc defines standard DocBook book frontmatter and backmatter
+<<X93,section markup templates>> (appendix, dedication, preface,
+bibliography, glossary, index, colophon).
 
 .Example book documents
 Book::
@@ -139,6 +143,9 @@ Used to generate UNIX manual pages.  AsciiDoc manpage documents
 observe special header title and section naming conventions -- see the
 <<X1,Manpage Documents>> section for details.
 
+AsciiDoc defines the 'synopsis' <<X93,section markup template>> to
+generate the DocBook `refsynopsisdiv` section.
+
 See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from
 the AsciiDoc distribution.
 
@@ -168,8 +175,7 @@ formats such as Postscript, HTML, PDF, EPUB, DVI, PostScript, LaTeX,
 roff (the native man page format), HTMLHelp, JavaHelp and text.
 
 The AsciiDoc <<X86,Preamble>> element generates a DocBook book
-'preface' element although it's more usual to use an explicit
-'Preface' special section (see the `./doc/book.txt` example book).
+'preface'.
 
 [[X33]]
 xhtml11
@@ -399,7 +405,7 @@ templates:
 
 level::
 The `level` attribute is the section level number, it is normally just
-the <<X17,title>> level number. However, if the `leveloffset`
+the <<X17,title>> level number (1..4). However, if the `leveloffset`
 attribute is defined it will be added to the `level` attribute. The
 `leveloffset` attribute is useful for <<X90,combining documents>>.
 
@@ -409,12 +415,17 @@ The `-n` (`--section-numbers`) command-line option generates the
 for section numbers in HTML outputs (DocBook section numbering are
 handled automatically by the DocBook toolchain commands).
 
-Section markup template names are specified in the following ways (in
-order of precedence):
-
-1. By setting the title's first positional attribute or 'template'
-   attribute to the name of a configuration file template. The
-   following three section titles are functionally equivalent:
+[[X93]]
+Section markup templates
+^^^^^^^^^^^^^^^^^^^^^^^^
+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):
+
+1. From the title's first positional attribute or 'template'
+   attribute to the name of a configuration file template. For
+   example, the following three section titles are functionally
+   equivalent:
 +
 .....................................................................
 [[terms]]
@@ -431,11 +442,21 @@ List of Terms
 -------------
 .....................................................................
 
-2. When the title matches a configuration file <<X16,specialsections>>
-   entry.
-3. If neither of the above use the default `sect<level>` template
-   name.
+2. When the title text matches a configuration file
+   <<X16,`[specialsections]`>> entry.
+3. If neither of the above the default `sect<level>` template is used
+   (where `<level>` is a number from 1 to 4).
+
+In addition to the normal section template names ('sect1', 'sect2',
+'sect3', 'sect4') AsciiDoc has the following templates for
+frontmatter, backmatter and other special sections: 'abstract',
+'preface', 'colophon', 'dedication', 'glossary', 'bibliography',
+'synopsis', 'appendix', 'index'.  These special section templates
+generate the corresponding Docbook elements; for HTML outputs they
+default to the 'sect1' section template.
 
+Section IDs
+^^^^^^^^^^^
 Section IDs are auto-generated from section titles if the `sectids`
 attribute is defined (the default behavior). The primary purpose of
 this feature is to ensure persistence of table of contents links
@@ -459,15 +480,15 @@ For example the title 'Jim's House' would generate the ID
 `_jim_s_house`.
 
 [[X16]]
-Special Sections
-^^^^^^^^^^^^^^^^
-In addition to normal sections there are DocBook section elements for
-frontmatter and backmatter sections -- for example: preface,
-bibliography, table of contents, index.
-
-`[specialsections]` sections are in AsciiDoc language configuration
-files; they map specific section titles to markup templates.
-Section entries are formatted like:
+Special Section Titles
+^^^^^^^^^^^^^^^^^^^^^^
+AsciiDoc has a mechanism for mapping predefined section titles
+auto-magically to specific markup templates. For example a title
+'Appendix A: Code Reference' will automatically use the 'appendix'
+<<X93,section markup template>>. The mappings from title to template
+name are specified in `[specialsections]` sections in the Asciidoc
+language configuration files (`lang-*.conf`).  Section entries are
+formatted like:
 
   <title>=<template>
 
@@ -481,17 +502,32 @@ is set to the value of the matched regular expression group named
 of the AsciiDoc section title. If `<template>` is blank then any
 existing entry with the same `<title>` will be deleted.
 
-AsciiDoc comes preconfigured with the following special section
-titles:
+.Special section titles vs. explicit template names
+*********************************************************************
+AsciiDoc has two mechanisms for specifying non-default section markup
+templates: you can specify the template name explicity (using the
+'template' attribute) or indirectly (using 'special section titles').
+Specifying a <<X93,section template>> attribute explicitly is
+preferred.  Auto-magical 'special section titles' have the following
+drawbacks:
+
+- They are non-obvious, you have to know the exact matching
+  title for each special section on a language by language basis.
+- Section titles are predefined and can only be customised with a
+  configuration change.
+- The implementation is complicated by multiple languages: every
+  special section title has to be defined for each language (in each
+  of the `lang-*.conf` files).
+
+Specifying special section template names explicitly does add more
+noise to the source document (the 'template' attribute declaration),
+but the intention is obvious and the syntax is consistent with other
+AsciiDoc elements c.f.  bibliographic, Q&A and glossary lists.
+
+Special section titles have been deprecated but are retained for
+backward compatibility.
 
-  Preface                    (book documents only)
-  Abstract                   (article documents only)
-  Dedication                 (book documents only)
-  Glossary
-  Bibliography|References
-  Colophon                   (book documents only)
-  Index
-  Appendix [A-Z][:.] <title>
+*********************************************************************
 
 Inline Elements
 ~~~~~~~~~~~~~~~
@@ -916,9 +952,12 @@ Most block elements support the following attributes:
 Unique identifier typically serve as link targets.
 Can also be set by the 'BlockId' element.
 
-|role |docbook |
-Role contains a string used to classify or subclassify an element.
-Used to add the 'role' attribute to DocBook block elements.
+|role |html4, xhtml11, docbook |
+Role contains a string used to classify or subclassify an element:
+
+- Adds 'role' attribute to DocBook block elements.
+- Adds 'role' attribute to DocBook and HTML <<X51,quoted inline
+  elements>>.
 
 |reftext |docbook |
 'reftext' is used to set the DocBook 'xreflabel' attribute.
@@ -1679,7 +1718,7 @@ For working examples see the `article.txt` and `book.txt` documents in
 the AsciiDoc `./doc` distribution directory.
 
 NOTE: To generate valid DocBook output glossary lists must be located
-in a glossary section.
+in a section that uses the 'glossary' <<X93,section markup template>>.
 
 Bibliography Lists
 ~~~~~~~~~~~~~~~~~~
@@ -4050,6 +4089,7 @@ predefined intrinsic attributes:
   {two-semicolons}      Two semicolon characters
   {user-dir}            the ~/.asciidoc directory (if it exists)
   {verbose}             defined as '' if --verbose command option specified
+  {zwsp}                Zero-width space.
 
 .NOTES
 1. Intrinsic attributes are global so avoid defining custom attributes
@@ -5067,6 +5107,8 @@ it will be fetched from its Internet location. If you omit the
 formed.
 
 
+:numbered!:
+
 Glossary
 --------
 [glossary]
@@ -5088,8 +5130,9 @@ Verbatim element::
     the source document are to be preserved in the output document.
 
 
-Appendix A: Migration Notes
----------------------------
+[appendix]
+Migration Notes
+---------------
 [[X53]]
 Version 7 to version 8
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -5113,8 +5156,9 @@ define the attribute `asciidoc7compatible` (for example by using the
 `-a asciidoc7compatible` command-line option).
 
 [[X38]]
-Appendix B: Packager Notes
----------------------------
+[appendix]
+Packager Notes
+--------------
 Read the `README` and `INSTALL` files (in the distribution root
 directory) for install prerequisites and procedures.  The distribution
 `Makefile.in` (used by `configure` to generate the `Makefile`) is the
@@ -5122,8 +5166,9 @@ canonical installation procedure.
 
 
 [[X39]]
-Appendix C: AsciiDoc Safe Mode
-------------------------------
+[appendix]
+AsciiDoc Safe Mode
+-------------------
 AsciiDoc 'safe mode' skips potentially dangerous scripted sections in
 AsciiDoc source files by inhibiting the execution of arbitrary code or
 the inclusion of arbitrary files.
@@ -5151,8 +5196,9 @@ configuration files. Be especially careful when:
 =====================================================================
 
 
-Appendix D: Using AsciiDoc with non-English Languages
------------------------------------------------------
+[appendix]
+Using AsciiDoc with non-English Languages
+-----------------------------------------
 AsciiDoc can process UTF-8 character sets but there are some things
 you need to be aware of:
 
@@ -5187,8 +5233,9 @@ the HTML output file.
   format.
 
 
-Appendix E: Vim Syntax Highlighter
-----------------------------------
+[appendix]
+Vim Syntax Highlighter
+----------------------
 Syntax highlighting is incredibly useful, in addition to making
 reading AsciiDoc documents much easier syntax highlighting also helps
 you catch AsciiDoc syntax errors as you write your documents.
@@ -5254,8 +5301,9 @@ idea.
 
 
 [[X74]]
-Appendix F: Attribute Options
------------------------------
+[appendix]
+Attribute Options
+-----------------
 Here is the list of predefined <<X75,attribute list options>>:
 
 
@@ -5294,8 +5342,9 @@ Emboldens label text.
 
 
 [[X82]]
-Appendix G: Diagnostics
------------------------
+[appendix]
+Diagnostics
+-----------
 The `asciidoc(1)` `--verbose` command-line option prints additional
 information to stderr: files processed, filters processed, warnings,
 system attribute evaluation.
@@ -5352,8 +5401,9 @@ Attribute Entry examples:
 
 
 [[X88]]
-Appendix H: Backend Attributes
-------------------------------
+[appendix]
+Backend Attributes
+------------------
 This table contains a list of optional attributes that influence the
 generated outputs.
 
@@ -5421,7 +5471,8 @@ Set the document maximum display width (sets the 'body' element CSS
 document header.
 
 |numbered |html4, xhtml11, docbook (XSL Stylesheets) |
-Adds section numbers to section titles.
+Adds section numbers to section titles. The 'dobook' backend ignores
+'numbered' attribute entries after the document header.
 
 |quirks |xhtml11 |
 Use the `xhtml11-quirks.css` stylesheet to work around IE6 browser
diff --git a/doc/book-multi.txt b/doc/book-multi.txt
index 91982a8..30d1b3e 100644
--- a/doc/book-multi.txt
+++ b/doc/book-multi.txt
@@ -4,8 +4,9 @@ Author's Name
 v1.0, Dec 2003

 

 

-Dedication

-==========

+[dedication]

+Example Dedication

+==================

 The optional dedication goes here.

 

 This document is an AsciiDoc multi-part book skeleton containing

@@ -20,8 +21,9 @@ appendices, bibliography, glossary, index) must be level zero headings
 (not level one).

 

 

-Preface

-=======

+[preface]

+Example Preface

+================

 The optional book preface goes here at section level zero.

 

 Preface Sub-section

@@ -110,8 +112,11 @@ sub-sections.
 

 

 

-Appendix A: Example Appendix

-============================

+:numbered!:

+

+[appendix]

+Example Appendix

+================

 One or more optional appendixes go here at section level zero.

 

 Appendix Sub-section

@@ -122,8 +127,9 @@ documents.
 

 

 

-Bibliography

-============

+[bibliography]

+Example Bibliography

+====================

 The bibliography list is a style of AsciiDoc bulleted list.

 

 [bibliography]

@@ -134,8 +140,9 @@ The bibliography list is a style of AsciiDoc bulleted list.
   ISBN 1-56592-580-7.

 

 

-Glossary

-========

+[glossary]

+Example Glossary

+================

 Glossaries are optional. Glossaries entries are an example of a style

 of AsciiDoc labeled lists.

 

@@ -147,8 +154,15 @@ A second glossary term::
   The corresponding (indented) definition.

 

 

-Index

-=====

+[colophon]

+Example Colophon

+================

+Text at the end of a book describing facts about its production.

+

+

+[index]

+Example Index

+=============

 ////////////////////////////////////////////////////////////////

 The index is normally left completely empty, it's contents are

 generated automatically by the DocBook toolchain.

diff --git a/doc/book.txt b/doc/book.txt
index 9fb9c30..7f0471b 100644
--- a/doc/book.txt
+++ b/doc/book.txt
@@ -4,8 +4,9 @@ Author's Name
 v1.0, Dec 2003

 

 

-Dedication

-----------

+[dedication]

+Example Dedication

+------------------

 Optional dedication.

 

 This document is an AsciiDoc book skeleton containing briefly

@@ -17,8 +18,9 @@ the preface, appendix, bibliography, glossary and index sections are
 significant ('specialsections').

 

 

-Preface

--------

+[preface]

+Example Preface

+---------------

 Optional preface.

 

 Preface Sub-section

@@ -89,8 +91,11 @@ The Third Chapter
 Book chapters are at level 1 and can contain sub-sections.

 

 

-Appendix A: Example Appendix

-----------------------------

+:numbered!:

+

+[appendix]

+Example Appendix

+----------------

 One or more optional appendixes go here at section level 1.

 

 Appendix Sub-section

@@ -98,8 +103,9 @@ Appendix Sub-section
 Sub-section body.

 

 

-Bibliography

-------------

+[bibliography]

+Example Bibliography

+--------------------

 The bibliography list is a style of AsciiDoc bulleted list.

 

 [bibliography]

@@ -110,8 +116,9 @@ The bibliography list is a style of AsciiDoc bulleted list.
   ISBN 1-56592-580-7.

 

 

-Glossary

---------

+[glossary]

+Example Glossary

+----------------

 Glossaries are optional. Glossaries entries are an example of a style

 of AsciiDoc labeled lists.

 

@@ -123,8 +130,15 @@ A second glossary term::
   The corresponding (indented) definition.

 

 

-Index

------

+[colophon]

+Example Colophon

+----------------

+Text at the end of a book describing facts about its production.

+

+

+[index]

+Example Index

+-------------

 ////////////////////////////////////////////////////////////////

 The index is normally left completely empty, it's contents being

 generated automatically by the DocBook toolchain.

diff --git a/doc/faq.txt b/doc/faq.txt
index 031907b..525a762 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -2,6 +2,30 @@ AsciiDoc Frequently Asked Questions
 ===================================

 

 

+== Why am I getting DocBook validation errors?

+Not all valid AsciiDoc source generates in valid DocBook, for example

+'special sections' (abstract, preface, colophon, dedication,

+bibliography, glossary, appendix, index, synopsis) have different

+DocBook schemas compared to normal document sections. For example, a

+paragraph is illegal in a bibliography.

+

+Don't forget if your document is a book you need to specify the `-d

+book`, if you don't an article DocBook document will be generated,

+possibly containing book specific sections, leading to validation

+errors.

+

+

+== How can I disable special section titles?

+For example, you want to use 'References' as a normal section name but

+AsciiDoc is auto-magically generating a DocBook 'bibliography'

+section. All you need to do is explicitly specify the section template

+name:

+

+  [sect1]

+  References

+  ----------

+

+

 == Why don't tables generated by dblatex obey the width attribute?

 Tables generated by dblatex will take 100% of the available space

 unless you change the 'pageunits' micellaneous parameter to 'pt'. You

@@ -14,7 +38,6 @@ can do this:
 

   :miscellaneous.pageunits: pt

 

-

 See the

 http://www.methods.co.nz/asciidoc/userguide.html#X89[DocBook table

 widths] sidebar in the 'AsciiDoc User Guide' for an explanation.

diff --git a/examples/website/layout1.conf b/examples/website/layout1.conf
index eebef3d..5c090a8 100644
--- a/examples/website/layout1.conf
+++ b/examples/website/layout1.conf
@@ -27,7 +27,6 @@
 #   xhtml11 backend stylesheets.
 
 [specialwords]
-emphasizedwords=(?u)\\?\bAsciiDoc\b
 monospacedwords=(?u)\\?\basciidoc\(1\) (?u)\\?\ba2x\(1\)
 
 [header]
diff --git a/examples/website/layout2.conf b/examples/website/layout2.conf
index 141ea9f..320cd0c 100644
--- a/examples/website/layout2.conf
+++ b/examples/website/layout2.conf
@@ -24,7 +24,6 @@
 #   xhtml11 backend stylesheets.
 
 [specialwords]
-emphasizedwords=(?u)\\?\bAsciiDoc\b
 monospacedwords=(?u)\\?\basciidoc\(1\) (?u)\\?\ba2x\(1\)
 
 [header]
diff --git a/html4.conf b/html4.conf
index b224196..697b545 100644
--- a/html4.conf
+++ b/html4.conf
@@ -412,6 +412,11 @@ cellspacing="0" cellpadding="4">
 <h5>{id?<a name="{id}"></a>}{title}</h5>

 |

 

+[appendix]

+<hr>

+<h2>{id?<a name="{id}"></a>}{numbered?{sectnum} }{appendix-caption} {counter:appendix-number:A}: {title}</h2>

+|

+

 [footer]

 <p></p>

 <p></p>

diff --git a/lang-de.conf b/lang-de.conf
index 683f398..d9ba570 100644
--- a/lang-de.conf
+++ b/lang-de.conf
@@ -17,6 +17,7 @@ figure-caption=Abbildung
 table-caption=Tabelle
 example-caption=Beispiel
 toc-title=Inhaltsverzeichnis
+appendix-caption=Anhang
 
 endif::basebackend-html[]
 
diff --git a/lang-en.conf b/lang-en.conf
index eed6486..a5a9a43 100644
--- a/lang-en.conf
+++ b/lang-en.conf
@@ -16,6 +16,7 @@ figure-caption=Figure
 table-caption=Table
 example-caption=Example
 toc-title=Table of Contents
+appendix-caption=Appendix
 
 endif::basebackend-html[]
 
diff --git a/lang-es.conf b/lang-es.conf
index 96b15d6..62986cb 100644
--- a/lang-es.conf
+++ b/lang-es.conf
@@ -16,6 +16,7 @@ figure-caption=Figura
 table-caption=Tabla
 example-caption=Ejemplo
 toc-title=Tabla de contenidos
+appendix-caption=Apéndice
 
 endif::basebackend-html[]
 
diff --git a/lang-fr.conf b/lang-fr.conf
index 7d0378b..161435c 100644
--- a/lang-fr.conf
+++ b/lang-fr.conf
@@ -17,6 +17,7 @@ figure-caption=Figure
 table-caption=Tableau
 example-caption=Exemple
 toc-title=Table des matières
+appendix-caption=Appendice
 
 endif::basebackend-html[]
 
diff --git a/lang-hu.conf b/lang-hu.conf
index fe5531e..34b5dee 100644
--- a/lang-hu.conf
+++ b/lang-hu.conf
@@ -17,6 +17,7 @@ figure-caption=Ábra
 table-caption=Táblázat
 example-caption=Példa
 toc-title=Tartalomjegyzék
+appendix-caption=függelék
 
 endif::basebackend-html[]
 
diff --git a/lang-pt-BR.conf b/lang-pt-BR.conf
index 05ea143..e01f370 100644
--- a/lang-pt-BR.conf
+++ b/lang-pt-BR.conf
@@ -17,6 +17,7 @@ figure-caption=Figura
 table-caption=Tabela
 example-caption=Exemplo
 toc-title=Tabela de conteúdos
+appendix-caption=Appêndice
 
 endif::basebackend-html[]
 
diff --git a/lang-ru.conf b/lang-ru.conf
index c03523c..3ce22ea 100644
--- a/lang-ru.conf
+++ b/lang-ru.conf
@@ -17,6 +17,7 @@ figure-caption=Рисунок
 table-caption=Таблица
 example-caption=Пример
 toc-title=Содержание
+appendix-caption=Приложение
 
 endif::basebackend-html[]
 
diff --git a/stylesheets/xhtml11.css b/stylesheets/xhtml11.css
index 30d887d..57d0711 100644
--- a/stylesheets/xhtml11.css
+++ b/stylesheets/xhtml11.css
@@ -336,6 +336,10 @@ span.footnote, span.footnoteref {
   div#footer-badges { display: none; }
 }
 
+div#toc {
+  margin-bottom: 2.5em;
+}
+
 div#toctitle {
   color: #527bbd;
   font-family: sans-serif;
diff --git a/xhtml11.conf b/xhtml11.conf
index 5ff310f..d5ae759 100644
--- a/xhtml11.conf
+++ b/xhtml11.conf
@@ -456,6 +456,12 @@ cellspacing="0" cellpadding="4">
 <h5{id? id="{id}"}>{title}</h5>

 |

 

+[appendix]

+<h2{id? id="{id}"}>{numbered?{sectnum} }{appendix-caption} {counter:appendix-number:A}: {title}</h2>

+<div class="sectionbody">

+|

+</div>

+

 [header]

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">