Posted by glaforge on Apr 15, 2013; 3:16pm
URL: https://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p129.html

Regarding fast parsing time, that's good to know, and removes some worries I had.
When playing with asciidoctor through the Gradle plugin, for a very small document, it took like 6-7 seconds on my machine -- half of that being just the Gradle machinery. And as soon as I added a second small document, it went up to 9-10 seconds, which gave me the impression that parsing even small documents took quite long.
But that's perhaps a question of JRuby startup time? And perhaps also the Gradle plugin integration which somehow spins up a JRuby environment afresh each time too?

On the PDF aspect, I'm glad that you're progressing nicely here, and that it'll be possible to use Asciidoctor out of the box to do that PDF generation.

Now on the chuncked / single document, I have to somewhat disagree with you here.
The thing is that I want to rewrite the whole Groovy website and documentation.
I want a PDF output because folks like having a PDF handy to search into when offline, for example, and same thing for the full/single document.
But I also want chuncked documents because it's much easier for our users to just use Google and go directly right on the good page covering the topic they are searching -- instead of having to find the right spot in a huge document!
That said, I'll definitely have several manuals anyway, with, for example, the "language reference", the "metaprogramming guide", the "libraries guide" and what not.
But if we take the example of the "language reference", it's going to be a huge document if it were only one Asciidoc file. So I'd much rather split for easier collaboration on each sub-topics, and also to be able to publish that on the Groovy website as dedicated pages cover each and every aspect of the language.

So, I definitely think it's important to split the whole documentation in different manuals, of course, but each manual should be available both in chuncked and single document(s).

And ideally, of course, cross references should work out of the box when in chuncked and single modes!

Does my use case make sense?

(happy to further discuss it offline live if you're interested or need more context or background)