Asciidoc

--------------------------
*15-December-2004: Interim update:* Updated `asciidoc.py` to fix
broken `join_lines` function -- no other changes.

- PDF documentation is now produced from DocBook XML using XSLTLib and
FOP. Previously we processed DocBook SGML with `jw(1)` (which used
Dvips to convert DVI files to PDF). FOP has come a long way in the
last 12 months and produces very acceptable PDF under both Linux and
Windows.
- Sections detailing how to install and use the DocBook XSL
Stylesheets, xsltproc, FOP toolchain and the AsciiDoc XSLT drivers
have been added to the User Guide.
- The PDF output from the he example article template has been
included in the distribution (`./doc/article.pdf`).
- Special characters are emitted using decimal Unicode character codes
(previously used named character entities which cannot be assumed
included in non-HTML documents).
- Added registered trademark (R) to `[replacements]`.
- CSS stylesheet tweaks.
- Admonitions (Note, Tip, Important, Warning, Caution) include icons
when generating css output.

--------------------------
- Callouts have been implemented (see the 'Callouts' section of the
AsciiDoc User Guide for details).
- Added XSL drivers for generating XHTML, chunked XHTML and HTML Help
from DocBook XML using XSL stylesheets and xsltproc(1).
- Added CSS stylesheet for HTML generated from DocBook XML using XSL
stylesheets.
- Distribution contains HTML Help formatted User Guide
(`./doc/asciidoc.chm`), the User Guide tells you how it's generated.
- Images referred to by distributed stylesheets are now located in the
`./images` subdirectory (previously located in `.`).
- Filters path names are now handled properly under Cygwin.
- The usual documentation and examples additions, updates and
polishing.

--------------------------
- The convention of using a `.asc` file extension for AsciiDoc files
has been dropped in favor of the familiar `.txt` extension. It makes
more sense in that AsciiDoc is a text presentation format and
because `.asc` clashed with the same extension used by other
applications. It's only a naming convention -- you don't have to
switch if you don't want to.
- Changed the subscript formatting character from underline to tilde
since underscores in file names are reasonably common (especially in
link and image macros).
- An alternative syntax for the index term inline macro has been
added: `++<primary>,<secondary>,<tertiary>++`.
- Index terms that have secondary and tertiary entries now
additionally generate separate index terms for the secondary and
tertiary entries.
- A `+<primary>+` index term inline macro has been added which
displays the term in the primary text flow.
- Added alternative variable list definition using double semi-colon
terminator as opposed to the standard double colon terminator so
variable lists can be nested to two levels.
- Footnotes now appear on a separate line in HTML and Linuxdoc
outputs.
- Python version compatibility is checked at startup.
- Preface and appendix section titles in multi-part Book documents are
meant to be out of sequence -- warnings are no longer emitted when
outputting HTML.
- Empty section warnings have been replaced by error messages and are
emitted only if invalid markup would result.
- Missing macro sections or invalid macro name warnings are only
generated at startup if the `-v` (verbose) option is set. Otherwise
they are deferred until a matching macro is encountered in the input
file.
- Missing or invalid table definition warnings are only generated at
startup if the `-v` (verbose) option is set. Otherwise they are
deferred until a matching table is encountered in the input file.
- AsciiDoc now makes more of an effort to continue in the face of
errors.
- Fixed broken `./examples/website/main.aap` script.
- Converted distribution text files DOS text format as a sop to
Windows users with challenged text editors.
- Documentation additions and corrections.

--------------------------
- Spurious 'out of sequence' level 2 warnings no longer appear when
processing 'book' document multi-part book top level Preface and
Appendix sub-sections since they are (correctly) out of sequence.
- A warning is no longer emitted for empty Index sections since this
is normal when generating DocBook outputs.
- Fixed: `[quotes]` configuration file entries where not being
overridden by downstream configuration file entries.
- Footnote text is now output enclosed in square brackets in HTML
documents.
- Added superscripts and subscripts to the standard PRS configuration
files.
- Adjusted CSS stylesheets so list titles don't have so much space
between title and first list item (broken in IE6 due to poor CSS
compliance). Lessened sidebar title top margin.

--------------------------
- The version 5.0.6 README incorrectly stated that AsciiDoc would run
under Python 2.0, in fact it requires Python 2.1 or better. The
README has been corrected.
- Documented techniques for combining and splitting AsciiDoc documents
and processing the combined and split parts (see the 'Tips and
Tricks' section of the User Guide).
- An example of marking up superscripts and subscripts is documented
in the 'Tips and Tricks' section of the User Guide (the example
configuration file is in the AsciiDoc `examples` directory).
- Added ellipsis to shipped `[replacements]`; three periods output an
ellipsis entity.
- Removed unused 'SectionClose' class.
- The AsciiDoc 'Preamble' element is output as a DocBook 'Preface'
when processed as a 'book' document type (in older AsciiDoc versions
a warning was issued and processing stopped).
- Fixed a quoting anomaly: quoted text can no longer begin or end with
with white space.

--------------------------
- New 'image' macro implements optional image scaling and linking and
works in both inline and block contexts. The 'image' macro obsolesces
the existing 'graphic' block macro and 'icon' inline macro.
- Macro substitution section names now have `-inlinemacro` and
`-blockmacro` suffixes to resolve context ambiguity, make their
purpose clearer and relieve section namespace congestion.
- Header derived glossary entries can now be overridden from the
command-line.
- Special character substitution is now performed on AuthorLine
derived author names.
- A macro or block argument called 'options' can be used as a shortcut
for a list named arguments with zero length string values.
- Tables can be output without borders using the `options="noborders"`
argument.
- Table data lines that do not immediately follow a table section
underline can now be blank. This allows CSV data with embedded blank
lines to be processed correctly.
- Blank DSV format table data lines are silently skipped.
- Tightened up on enforcement of configuration file section names to
reduce the possibility of section content being seen as a section
header line.
- Section titles can be optionally suffixed with title arguments
enclosed in double square brackets.
- A replacement has been added to `asciidoc.conf` to replace inline
double dashes with the `&mdash;` entity.
- Changed the `.UNDER-CONSTRUCTION.` macro syntax to
`UNDER-CONSTRUCTION` so it is not mistaken for a BlockTitle.
Similarly changed the `.NEW.` replacement with
`&35;NEW&35;`.
- `&35;NEW&35;` and `UNDER-CONSTRUCTION` macros are now
included in the DocBook backend.
- Replaced shipped `smallnew.gif` with `smallnew.png`.
- Documentation tidy ups.