[
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
(v6.3.4#6332)
