On 1/17/17 11:35 AM, John Maddock wrote:
Given that Docbook now has direct support for ePub output, generating ePub should be as easy as generating html, at least in theory ;)
But getting the details setup correctly can be very time consuming. Of course changing to some other system is not going to make that any easier.
There are 2 difficulties, one is in setting up the docbook toolchain, then other is that if you want something other than html, then you're going to have to be prepared to do some serious proofreading and tweaking of your documentation. A trivial example, would be large tables that are fine on screen as HTML, but are way too large to fit on a printed page.
Right. I think that these problems could diminished by not trying to make a giant "book" (PDF, ePUB, or whatever) from all the libraries but rather to to build each library independently. This would eliminate the requirement that everyone be exactly on the same page. Another unfortunate feature if the current system is that it depends up using b2 which is really overkill and a big pain for the casual user. (Actually any user). In the incubator I've shown how to create pdf and epub documentation for a particular library just using the tools out of the box and a couple of 1/2 line shell scripts. Promoting this way of building the docs would go a long way to quell the calls for mucking around with current system.
DocBook has been around for quite a while and is still widely used. It has worked well for Boost, and I think all libraries should use it. +1, there is a lot to be said for consistency.
Personally I'm not less concerned about consistency that others. My concern is simplicity. I investigated all the alternatives I could find in giving my advice to authors in the boost library incubator. Correct and complete documents are not trivial so the "lightweight" solutions didn't suit me. I came up with boost build but without b2.
I can't help feeling that too much has been made of Boost using "non standard" or home made tools for this - we don't - the canonical format is Docbook, how you get to that is up to you.
Right
You can author the XML yourself (not recommended frankly or all though it does work quite well for small documents), use a commercial editor, or yes use our quickbook tool, something I've always found to be completely reliable and trivial to use. And yes, I resisted it at first too ;)
I resisted it because I didn't want to become dependent on boost tools. b2 burned me. I turned to XMLMind which is great as far as I'm concerned. So my tool chain is: XMLMind - edit xml tools xslt and boostbook/docbook to produce html and ePUB fop - to produce pdf I'm pretty pleased and it works great outside of boost as well!
Just my 2c, John
+1c from me.
Robert Ramey