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
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.
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 _javascript_s 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.
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.
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
* 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.
* Added slidy backend (based on Phillip Lord’s slidy backend
* 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 ActionRegistered Linux User #231597
-- devel mailing list devel@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/devel
