Asciidoctor :: Discussion

chunked html output like neo4j docs

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

marc

chunked html output like neo4j docs

Hi,

just disovered asciidoctor (and asciidoc in general). I am currently researching documentation toolchains for our technical documentation project for a software manual.

My background over the years is documenting with: DITA, Docbook and Latex. But neither of them is very "writer" friendly. Of course i experimented with markdown but i cant help thinking that this is mainly suitable for simple "articles" not the best choice for books.

I checked some references mentioned on your site and very liked the neo4j and golo chunked HTML output but i really dont unterstand their toolchain to produce it.

I am planing to use the gradle plugin since we are using gradle anyway for our java based projects. I have set up a simple example and got the unchunked html output. What do i need to do to get the output like the neo4j guys?

Thanks
Marc

mojavelinux

Re: chunked html output like neo4j docs

Administrator

Marc,

On Mon, Oct 20, 2014 at 4:21 PM, marc [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I am planing to use the gradle plugin since we are using gradle anyway for our java based projects. I have set up a simple example and got the unchunked html output. What do i need to do to get the output like the neo4j guys?

This is probably the biggest missing piece in the Asciidoctor toolchain at the moment. It's possible to get chunked output, but you have to convert to DocBook, then use the DocBook toolchain to create chunked HTML (that's what Neo4j does currently). What we want is to skip the whole DocBook part like we do with all the other converters.

Technically, it's possible to get chunked HTML output today if you write some extension code and custom converter logic. (I've prototyped it and still need share that prototype...made note to self). One way to do it is to load the document into the AST (Asciidoctor.load_file), then pick apart the AST by walking the sections and creating separate documents objects. Then, you convert the individual documents and use the section metadata to produce a master outline.

It's pretty easy to get 80% of the way there. The last 20% is tricky because it requires dealing with the subtleties of inherited attributes, cross references and the like. Anxiety over the 20% is what has prevented me from starting (and time).

Ultimately, I envision a project like asciidoctor-chunker or something like that to provide this logic. For more discussion, see the open issue in core: https://github.com/asciidoctor/asciidoctor/issues/626

Cheers,

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen