polygene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Paul Merlin (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (ZEST-149) Migrate documentation to AsciiDoctor
Date Sun, 03 Jul 2016 13:56:10 GMT

    [ https://issues.apache.org/jira/browse/ZEST-149?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15360549#comment-15360549

Paul Merlin commented on ZEST-149:

One issue with asciidoctor is that cross-references in chunked HTML output is not supported,
see https://github.com/asciidoctor/asciidoctor/issues/626
And we use them a lot!

One way people work around it is by using direct html file links in the asciidoctor source.
But this then prevent producing PDFs.

> Migrate documentation to AsciiDoctor
> ------------------------------------
>                 Key: ZEST-149
>                 URL: https://issues.apache.org/jira/browse/ZEST-149
>             Project: Zest
>          Issue Type: Bug
>            Reporter: Niclas Hedhman
>            Priority: Minor
> AsciiDoctor is a more modern AsciiDoc processing system.
> Since most of our documentation is in AsciiDoc markdown format, this should be a relatively
easy process.
> There is a Gradle plugin;
> http://asciidoctor.org/docs/asciidoctor-gradle-plugin/
> Hurdles;
> 1. SNIPPET support won't work as AsciiDoctor is built out of Ruby, whereas the old AsciiDoc
toolchain is in Python. The SNIPPET plugin needs to be re-written, but I think it can be done
in Java.
> 2. dev-status.xml processing. Same thing, something needs to be done.
> 3. At the moment a large DocBook document is generate, and then transformed using XSLT
into a chunk per web page. It seems that the AsciiDoctor approach would be to generate HTML5
directly and that the "chunking" is done with the source files directly. Need to investigate
this a bit more.

This message was sent by Atlassian JIRA

View raw message