[jira] [Updated] (POLYGENE-149) Migrate documentation to AsciiDoctor

["Paul Merlin (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/POLYGENE-149?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Paul Merlin updated POLYGENE-149:
---------------------------------
    Attachment: core.html

I've been doing some experiments with Asciidoctor.
It definitely lacks support for nice chunked output.
But, it also have a lot of pros like a vibrant community, nice extensibility, is much faster than asciidoc, is usable with no installation and the output looks great.

The toc support is quite nice too, making big documents quite easy to use.
For an example see: http://asciidoctor.org/docs/user-manual/
You get to easily jump from one section to the other using the TOC, and searching in the page using your browser make it easy to find stuff.

Our core documentation could be a single page like the doc linked above.
Then libraries, extensions, tools and samples shipped with the SDK could be another page each.

The only place where we have a lot of deep links "across documents" is the glossary.
We also have a few links e.g. from some extensions to some libraries.
All these can be done as regular relative html links.
This way we'd loose dead links validation, but we can also easily add such a check on the whole website.

So, moving to asciidoctor would require to "split" the documentation, maybe just like we already do with the documentation website top navigation (core/libs/ext ...).
It moves away from the "book" format, but I think that if we ever want to edit a book from this content, we would have to massage it anyway.
And it is more close to reality: what we have today is a web site.

We also have two asciidoc filters: {{snippet}} and {{devstatus}}. The former is supported out of the box by asciidoctor and I wrote a working prototype of the latter very quickly.

Having said all that, I'd like to propose that we move forward with this.
I can handle the migration and integration into the build system.

I attached a sample of the core manual converted using asciidoctor.
It is a work in progress, content is missing, not all snippets were converted etc...
But it gives a good view of how it could look.

WDYAT?


> Migrate documentation to AsciiDoctor
> ------------------------------------
>
>                 Key: POLYGENE-149
>                 URL: https://issues.apache.org/jira/browse/POLYGENE-149
>             Project: Polygene
>          Issue Type: Bug
>            Reporter: Niclas Hedhman
>            Priority: Minor
>         Attachments: core.html
>
>
> 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.4.14#64029)