polygene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Merlin <p...@nosphere.org>
Subject Re: Documentation
Date Mon, 18 Apr 2016 11:56:48 GMT
Niclas,

I've been looking at asciidoctor for a while.

There's built-in support for source code includes:

   include::{rootDir}/path/to/SomeFile.java[tags=whatever,indent=0]

And in the source file:

    // tag::whatever[]
    ...
    // end::whatever[]

PDF output using java only is pretty well supported through docbook and fop.

The asciidoctor HTML backend does not support chunked output with
cross-references. Which we use a lot. The only way to get chunked output
with cross-references is through docbook.

The docbook XSLs are published on maven central as a zip so we can
automate their usage too.
 
We would have to write/maintain the necessary plumbing code but it is
feasible to produce all the documentation without anything installed but
java.

I have a prototype build lying on disk, I'll review it and see if I can
come up with something satisfying.

Cheers


Niclas Hedhman a écrit :
> I should probably add that there is perhaps some challenge to get the
> Source Code inclusions to work. Not sure if AsciiDoctor will support those
> Python scripts we have...
>
> On Sat, Apr 16, 2016 at 1:54 PM, Niclas Hedhman <niclas@hedhman.org> wrote:
>
>> Gang,
>> Perhaps my prayers has been heard by the Almighty (just kidding), but
>> there seems to be a toolchain for AsciiDoc that makes our docs a bit neater.
>>
>> http://asciidoctor.org/
>>
>> If someone wants to take a shot at integrating this to the build system,
>> and plainly remove the old one (do in a separate branch so we can iron it
>> out), I would be eternally grateful, buy you beers until you fall off the
>> chair, whatever...
>>
>>
>> Cheers
>> --
>> Niclas Hedhman, Software Developer
>> http://zest.apache.org - New Energy for Java
>>
>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message