I'm seeking request for approval to upgrade the asciidoc package . 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
An issue request has already been filed for this upgrade  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
Can we proceed with the upgrade for Fedora 17? Fedora 18?
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.
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
xhtml11: Verse block and verse paragraph content enveloped in a pre
tag (instead of a div) so it renders better in text-only browsers.
CSS quirks mode is no longer the default xhtml11 output
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
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
Added text foreground and background color along with text size CSS
styles for XHTML outputs, see
xhtml11, html5: Made verse and quote block text darker to print
legibly in Google Chrome browser.
* 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
* 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
* 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.
* Added slidy backend (based on Phillip Lord’s slidy backend
* a2x: Added --xsl-file option to allow custom XSL stylesheets to be
* html5,xhtml11: If the data-uri attribute is defined then icons from
the theme icons directory (if they exist) will be embedded in the
* 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
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597