Support for multi page documentation

[rwinch]

I'm also interested in this feature and am willing to contribute support for it. For the initial discussion see http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-td118.html

[mojavelinux]

As a stop-gap, you are nearly there. You can use asciidoctor-fopdf. Just pass in the xhtml-chunked backend. Change the use of 'fo.xsl' to 'chunked.xsl' and you've got it. You may need to customize the XSLT to get exactly what you want, but the foundation is all there.

Of course, we want to do better than using that toolchain, but it should suffice in a pinch.

[mojavelinux]

Since you converted from DocBook, you probably have XSLT files laying around in the repository that have the customizations that were in place before.

[mojavelinux]

To be a bit more clear, add the file src/dist/docbook-xsl/chunked.xsl with the following content:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
<xsl:import href="common.xsl"/>
<xsl:import href="highlight.xsl"/>
<xsl:import href="callouts.xsl"/>
</xsl:stylesheet>

Then tweak the launcher to recognize 'chunked' as an alternative to 'fo-pdf' to callout the correct stylesheet.

Btw, it's important to recognize that asciidoctor-fopdf is basically a more self-contained, less complex version of jdocbook :)

[rwinch]

Thanks @mojavelinux for your suggestions. I wasn't aware that fopdf was a more concise version of jdocbook and was a bit concerned that I had taken the wrong approach since I had seen suggestions to use jdocbook to convert to multi page view.

I played with converting the docbook to multi page html and think that it may be a bit more work than I want. The issue is that I like the asciidcotor rendered html5 styling and want the multi page html to look like the single html5 output. This means I would need to put in the effort of converting the docbook into the same html markup and applying the asciidoctor style sheets.

I'm thinking I may be better off just processing the html5 output and converting it into a multi page output.

Any thoughts on this approach?

[aalmiray]

Is there anything else to be done for this issue given @rwinch's recent code contributions?

[maxmil]

+1 for this issue. We need to generate html, html single page and pdf output for our documentation and are using jdocbook.

If i've understood correctly @rwinch's contribution integrated fop with asciidoctor but a multipage html export is still not possible?

[rwinch]

Multipage html is possible, but you must provide your own stylesheets to convert from docbook to html. For this reason, I believe this issue should still be kept open.

[mojavelinux]

As Rob points out, multipage documentation currently relies on pushing the
document down the DocBook toolchain. Ultimately we want to be able to do
this without DocBook. In order for that to happen, it needs to be added to
Asciidoctor core.

I'm currently working on a refactoring that is going to open the door to
this feature. Specifically, I'm making the renderer pluggable so we can do
more complex exports, such as generating multiple files.

[maxmil]

Sounds great. Just what i'm looking for.

At the moment i'm trying to generate style sheets for docbook that produce HTML similar to the asciidoctor output so that i can use the asciidoctor stylesheet factory.

I'm not reinventing the wheel by any chance? The most similar stylesheets that i could find were those of the pressgang.

[gAmUssA]

@rwinch Any progress in this?

[ysb33r]

@mojavelinux Has there been any chancing in asciidoctor core to be able to support this?

[mojavelinux]

No. I'm currently investing it another strategy, which is to pre-chunk the content and recombine as needed.

The experimentation for multi-page converter has been happening here: asciidoctor/asciidoctor-extensions-lab#96 Perhaps check with @owenh000. I'm happy to merge in his changes, I just haven't gotten around to it yet.