request for approval to upgrade asciidoc package
Dan Allen
dan.j.allen at gmail.com
Fri Jul 27 05:43:28 UTC 2012
Btw, here's the full changelog for AsciiDoc:
http://www.methods.co.nz/asciidoc/CHANGELOG.html
Oh yeah, btw, the latest version is 8.6.8 :)
I've also attached a diff of the output when I run the asciidoc test suite
on version 8.4.5 and 8.6.7. While all the documents are parsed correctly,
you'll notice the differences in the markup (mostly changes in how styles
are applied in the HTML output).
-Dan
On Fri, Jul 27, 2012 at 1:28 AM, Dan Allen <dan.j.allen at gmail.com> wrote:
> 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
>
>
--
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/devel/attachments/20120727/c2766c38/attachment-0001.html>
More information about the devel
mailing list