4 ms·

I haven't been able to get good quality PDF output using the docbook based toolchain, as seems to be used in git-scribe. You can style the HTML output with css

by tbirdz 12y ago

I haven't been able to get good quality PDF output using the docbook based toolchain, as seems to be used in git-scribe. You can style the HTML output with css easily, and you can even get good looking math by including your LaTeX in a literal block, and use MathJAX in your HTML template to generate the math when the reader looks at it. PDF however is a different story. Currently, docbook's PDF backends use dblatex or fop. Fop is more styleable out of the box, having many parameters you can set. However, fop doesn't support ligatures in the output, and has some issues with math typesetting. dblatex has better quality output, but the amount of configurability of the xml stylesheet is limited. In order to configure the output, you must write a LaTeX sty file, which is much more difficult than a css stylesheet. A nice thing about docbook is it has xml stylesheets to transform to split page HTML and single page HTML. Honestly though there's not really many alternatives. Texinfo can produce single page HTML, split HTML, and PDF, but offers very little PDF styling. If you want your output to look like a GNU Manual you are set, but even things like changing fonts are not supported. Troff supports PDF, but even though there are some HTML backends, they are all pretty bad. There are also some html-generators for LaTeX, but they aren't really that good either. I think there is just too much of a gap between web and paper targets to be able to generate both in high quality from a single source. It may be possible, but it is difficult, and current tools are not able to do this. honestly, I would love to be wrong about this conclusion, and if anyone knows of any other tools that can do this with good quality, please let me know.

ivanr 12y ago
I built a similar single-source publishing workflow to publish my books, but it's based around DocBook. I am very happy with DocBook because it has all the features I need for technical publishing (styling, indexing, cross-references, etc). For writing I use OxygenXML, which allows me to edit text without working with XML directly and -- crucially -- supports change tracking that makes working with editors/copyeditors a breeze. To get good results from FOP you really need to dig deep into the XSL stylesheets. The amount of customisation work is usually not that big, but the problem is that you need to learn a lot about the stylesheets to know how to make the changes. If you don't already know XSLT the learning curve can be steep. The change-build-test process is very slow, especially when you're essentially guessing where to make the changes. (Which, for me, happened most of the time.) I was happy with FOP, but eventually moved to a commercial product: 1) I wanted to use OpenType fonts, which generally offer better quality and support a wide range of languages, 2) full support for ligatures, 3) better handling of SVG illustrations (FOP's integration with Batik is clunky and makes it very difficult to use the same fonts as the main document), and 4) better indexes.

by tbirdz 12y ago

ivanr 12y ago

I built a similar single-source publishing workflow to publish my books, but it's based around DocBook. I am very happy with DocBook because it has all the features I need for technical publishing (styling, indexing, cross-references, etc). For writing I use OxygenXML, which allows me to edit text without working with XML directly and -- crucially -- supports change tracking that makes working with editors/copyeditors a breeze. To get good results from FOP you really need to dig deep into the XSL stylesheets. The amount of customisation work is usually not that big, but the problem is that you need to learn a lot about the stylesheets to know how to make the changes. If you don't already know XSLT the learning curve can be steep. The change-build-test process is very slow, especially when you're essentially guessing where to make the changes. (Which, for me, happened most of the time.) I was happy with FOP, but eventually moved to a commercial product: 1) I wanted to use OpenType fonts, which generally offer better quality and support a wide range of languages, 2) full support for ligatures, 3) better handling of SVG illustrations (FOP's integration with Batik is clunky and makes it very difficult to use the same fonts as the main document), and 4) better indexes.