diff options
author | Stuart Rackham <srackham@methods.co.nz> | 2009-11-19 12:36:41 +1300 |
---|---|---|
committer | Stuart Rackham <srackham@methods.co.nz> | 2009-11-19 12:36:41 +1300 |
commit | e1961013e22ba0726778182ceca3c8ac904e2a4d (patch) | |
tree | 5f25d35985ca0cd705e203f4a30e97f6141088be /doc | |
parent | 0e2b53e89673c12d98cde63339eb0b1a699b70b3 (diff) | |
download | asciidoc-e1961013e22ba0726778182ceca3c8ac904e2a4d.tar.gz |
- 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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/article.txt | 28 | ||||
-rw-r--r-- | doc/asciidoc.conf | 1 | ||||
-rw-r--r-- | doc/asciidoc.dict | 30 | ||||
-rw-r--r-- | doc/asciidoc.txt | 163 | ||||
-rw-r--r-- | doc/book-multi.txt | 38 | ||||
-rw-r--r-- | doc/book.txt | 38 | ||||
-rw-r--r-- | doc/faq.txt | 25 |
7 files changed, 217 insertions, 106 deletions
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.
|