Asciidoctor :: Discussion - Re: Recommendations for multi-page and single-page documentation

Re: Recommendations for multi-page and single-page documentation

Posted by mojavelinux on Apr 12, 2013; 9:14pm
URL: https://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p122.html

First, I would say don't worry about parsing the docs multiple times. Asciidoctor is fast as hell. The RichFaces documentation, which is just astronomically huge, parses and renders in 0.16 seconds. This is not a concern (and I'll be damned if I can't make it faster).

Now, as for the traditional outputs (single page, multi page, pdf)...the first solution I would propose is to chain it to the jdocbook plugin. Asciidoctor takes AsciiDoc and converts it to DocBook, jdocbook takes it from there and does what it's been doing for years. Add the pressgang tools into that and you get some pretty nice looking PDFs.

Here's an archetype that combines these two great plugins:

https://github.com/KurtStam/pressgang-tools/wiki/GuideReadme

Kurt posted about this on the mailinglist yesterday. I spent yesterday experimenting with it and I ended up with the PDF of the AsciiDoc quick reference (after some color and style hacking of the XSL):

http://asciidoctor.org/docs/asciidoc-quick-reference.pdf

Having said that, part of the vision for Asciidoctor is to be able to work w/o the DocBook toolchain. Right now Asciidoctor can take a source file and create a single HTML page. Support for ePub and zipped result is prototyped, but not yet implemented.

...as for multi-page, or "chunked" output...I first have to say, I think it's a terrible reader experience. I *always* click on single HTML. Browsers are so unbelievably fast at rendering that this is not a problem for users to have a huge, huge, huge HTML document. Besides, if it's so huge, then it probably is too big and no one will read it (break it up into different manuals, not just splitting up all the chapters).

With that out of the way, the way in which you would create the single chapters is to either have Asciidoctor run on each chapter file, producing a standalone document, or you could work with the AST tree and split up the document and render the parts out manually. The problem, however, is that cross-references in the document aren't going to work as expected. That is one of the things that jdocbook solves.

How we move forward depends a lot on the requirements that are brought forth. We'll meld Asciidoctor to meet the needs of the users. I am totally open to that policy. I do urge you, though, to think about why you are creating output in a particular way (e.g., multi-page documents) and ask yourself if that is really what you want or you just did it because you always did it.

Btw, I'd love to see the jdocbook plugin w/ the pressgang tools additions work in Gradle. It's a nice stack.

-Dan

On Fri, Apr 12, 2013 at 8:56 AM, lightguard.jp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

That's a good question. I think the answer as it currently stands with Asciidoctor is you'll have to run it multiple times. This something we should enable in core Asciidoctor, however, I feel it would be a larger change and we'll have to discuss how it would look on the cli. My initial thoughts are to add a separate attribute for multiple output runs as we can't pass multiple -b attributes currently. Unless we do further parsing of the attribute and make it delimited, that would be an easy change to get that part. The other, I describe below is much more work (I think).

Actually now that I think about it, you would probably have to parse the docs multiple times anyway, unless we make some deep core changes to keep the ast around after we've done parsing. I'll let Dan comment once he wakes in a few hours, he may have a better idea.

—
Sent from Mailbox for iPhone

On Fri, Apr 12, 2013 at 8:45 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

I'm playing with AsciiDoctor through the Gradle plugin, so I don't really yet have access to all the flags one can pass to the asciidoctor on the command-line... but hopefully, the plugin can soon expose some further configuration options -- thanks Andrés!

But I'm wondering what are the recommendations regarding outputting a big documentation in both multi-page format, and big single-page format, at the same time, hopefully without necessarily reparsing the docs twice.

Similarily, I might want to expose the documentation online on a website, but in a slightly different format standalone (in a ZIP for example). Again, does that mean parsing docs as many times as needed, to produce as many outputs with different combinations of stylesheets, javascript bits, etc?

Thanks for the advice

Guillaume

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p119.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction