I'm seeking request for approval to upgrade the asciidoc package [1]. The latest version of AsciiDoc is 8.6.7, released this month. The version currently packaged is 8.4.5, released May 2009 (not exactly what we would call *first*).

An issue request has already been filed for this upgrade [2] and a link to an updated spec file is available in the comments.

The request for approval has to do with backward compatibility of output. (In case you haven't heard of it, AsciiDoc is a script that transforms lightweight markup--ala markdown--into html, docbook, epub, etc). Any document written for AsciiDoc 8.4.5 is expected to compile successfully with the latest version, as AsciiDoc maintains backwards compatibility of the syntax. However, the output markup is constantly being tweaked and refined. Therefore, the output will be different. Better, but different.

There are a several compelling reasons why the package should be upgraded. First and foremost, adoption of AsciiDoc is taking off, partly because O'Reilly authors can write book drafts entirely in AsciiDoc. Several high profile projects such as Neo4j and JBoss have also adopted AsciiDoc. As a result, a growing number of developers are now looking for it for the first time. When they see that the version in Fedora is so old, they either swap to a different distro (Ubuntu Precise, Debian Sid and even Debian Stable have newer versions), or they download it from the project website. The fact that the other distros have newer versions works in the favor of this request, since build systems are likely requiring the newer versions. It also means those doc builds break when they run on Fedora.

Other key enhancements include:

* HTML5, ePub and slidy output
* source highlighting using pygments
* new themes and a theme engine
* lots of smaller additions to the markup language

I've attempted to summarize the changes to AsciiDoc since the version in Fedora 17, including gotchas for people upgrading, at the bottom of this message.

Can we proceed with the upgrade for Fedora 17? Fedora 18?

-Dan

[1] https://apps.fedoraproject.org/packages/asciidoc
[2] https://bugzilla.redhat.com/show_bug.cgi?id=556171

Gotchas

   The Asciidoc numbered and toc attributes cause DocBook outputs to
   include asciidoc-numbered and asciidoc-toc processing instructions,
   these are used by DocBook XSL to include section numbering and
   table of contents (like Asciidoc HTML backends). For backward
   compatibility both numbered and toc attributes are defined by
   default when the docbook backend is used.
   See http://groups.google.com/group/asciidoc/browse_frm/thread/1badad21ff9447ac

   There’s been quite a bit of tiding up to the xhtml11 JavaScript. The
   most obvious change is that the toc.js script has been superceded by
   asciidoc-xhtml11.js so if you’re linking you’ll need get a copy of the
   new file from the distribution javascripts directory.

   xhtml11: Verse block and verse paragraph content enveloped in a pre
   tag (instead of a div) so it renders better in text-only browsers.
   See: http://groups.google.com/group/asciidoc/browse_frm/thread/1b6b66adb24e710

   CSS quirks mode is no longer the default xhtml11 output
   (http://groups.google.com/group/asciidoc/browse_thread/thread/1c02d27d49221aa2).

   The global configuration files directory is ignored by both
   asciidoc and a2x if AsciiDoc configuration files are installed in
   the same directory as the asciidoc executable. This change allows
   both a system wide copy and multiple local copies of AsciiDoc to
   coexist on the same host PC.

   Break compatibility with quoted element positional color
   and size attributes (HTML backends). To revert to the deprecated quote
   behavior define the deprecated-quotes attribute in the global
   asciidoc.conf file or on the command-line. For a more detailed
   explanation of the rationale behind this change see
   http://groups.google.com/group/asciidoc/browse_thread/thread/b22603bfb879418c.

   xhtml11: list bullets colored gray.

   Renamed paragraph default style to normal.

   attributes, titles and specialcharacters sections are now read from
   the local asciidoc.conf file before the header is parsed. This
   fixes a regression problem. See
   http://groups.google.com/group/asciidoc/browse_thread/thread/1b3f88f1f8118ab3

   Added text foreground and background color along with text size CSS
   styles for XHTML outputs, see
   http://www.methods.co.nz/asciidoc/userguide.html#X96.

   xhtml11, html5: Made verse and quote block text darker to print
   legibly in Google Chrome browser.

Features

     * Added html5 backend.
     * The new a2x can output EPUB formatted documents (script now written in python instead of bash).
     * Pygments (http://pygments.org/) option added to source code
       highlight filter. Based on Pygments source code filter written by
       David Hajage
       (http://groups.google.com/group/asciidoc/browse_thread/thread/d8d042f5a3021369/8934ebbb8cb7144b).
     * A new flask theme for xhtml11 and html5 backends. A shameless
       knock-off of the Flask website styling.
     * xhtml11: Added a new theme (volnitsky). Written and contributed by
       Leonid V. Volnitsky.
     * xhtml11,html5: Added toc2 attribute which generates a scrollable
       table of contents in the left hand margin. Based on customized CSS
       written by Suraj Kurapati, see http://groups.google.com/group/asciidoc/browse_thread/thread/c5
     * Implemented counter system attribute.
     * Added style and role CSS classes to xhtml11 section templates.
     * Added dblatex table-width processing instruction — tables generated
       by dblatex now observe the AsciiDoc table width as a percentage
       (thanks to Gustav Broberg for suggesting this enhancement).
     * Added a start attribute to numbered lists to set the start number.
       See: http://groups.google.com/group/asciidoc/browse_thread/thread/c14a4c3b1e4f6dc5
     * Added slidy backend (based on Phillip Lord’s slidy backend
       https://phillordbio-asciidoc-fixes.googlecode.com/hg/).
     * a2x: Added --xsl-file option to allow custom XSL stylesheets to be
       specified.
     * html5,xhtml11: If the data-uri attribute is defined then icons from
       the theme icons directory (if they exist) will be embedded in the
       generated document.
     * Added args block attribute to source highlight blocks to allow
       arbitrary parameters to be passed to the source highlighters.
     * Implemented toc::[] block macro and toc-placement attribute for
       HTML backends to allow the Table of Contents placement to be set
       manually by the author.
     * fixes to Jython compatibility

--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction