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.
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.
I really like the idea of a continuous build system, but I find the PDF produced is not super well typeset.
If you ask me, the Future of Technical Writing looks more like this: https://github.com/softcover/softcover , mhartl's (markdown-->latex)-based build scripts
Do these tools facilitate composition in multimedia?
I love using my text tools, including Vim and efficient markup; I would hate to give them up. However I feel that I'm holding onto to something obsolete. The multimedia communication future is here, and only our tools and habits are holding us back. (My dream is that someone, even Bram Moolenaar, will write something as efficient as Vim that incorporates multimedia as a first class, supported format.)
People use multimedia instinctively where the tools are available, such as SMS/MMS, social media, etc. Why do so many of our composition tools and communication mediums still treat multimedia as a second class citizen? Why do Word, our editors, or HN's comment system not fully incorporate multimedia?
End users and even many HN readers are accustomed to this state of affairs, but one day text-only (or text-primary) composition will look archaic. (Yes, I know text is more appropriate in many cases, but images/movies are more appropriate in others and our tools stop us from using them.)
In medicine, we use simple but formal notes for our thinking. In the military, we use radio messages. In law: plain text you could generate with a type writer. I submit, code is the same for computing.
Excepting architecture and engineering, you could argue that most professions don't need markup.
> Why do Word, our editors, or HN's comment system not fully incorporate multimedia
Because you can usually do more with less. And ascii is about as less as you can get.
Why would you think that "text-primary composition will look archaic"? What exactly is this "social media"-form of communication are you talking about? Because much of the social media that I see is text-based.
Just curious, but were you around during the time of MySpace's peak? That was a site that fully integrated multimedia into profile creation and wall posting, much more so than Facebook.
If you're primarily a communicator and not a coder making code for other coders, text-primary composition already looks archaic.
Let's not forget that the main aim of PDFs and even TeX is to replace ink on paper.
As a goal for 2014, I'd suggest that perhaps this is lacking ambition - as is the idea that the best of all possible systems is one where you crank a handle on some input data to run a batch process which generates various output formats.
>much of the social media that I see is text-based.
In my very average Facebook feed most messages include at least one image, and as a wild hand-wavy estimate maybe 10% include a video clip.
Entire sites are devoted to slides, video tutorials, and photo sharing.
I guess if 'We only do text' works for you, that's fine. It doesn't work for a lot of users.
As a footnote, consider that it might be possible to write software using images, sounds, and video clips as semantic tokens instead of text strings.
There's no real reason, beyond fear of the unknown, to constrain programming to text shuffling.
My guess is that over the next century or so, associative intelligent systems that can parse (e.g.) visual, verbal and other sensory metaphors will provide better tools for solving certain kinds of problems than strict Turing logic.
The reasons cited here are basically why I built Storytella[0]. Writing tools seem vastly inferior to developer tools when it comes to basic layout and document conversion. At the moment Storytella is aimed at novels for self-publishing authors so doesn't have much in the way of complex formatting - I want to update the Markdown syntax it uses to include some of the extensions available such as table formatting.
O'Reilly Atlas looks really interesting but the "email for a quote" thing really puts me off.
Leanpub offers something really similar but it pretty much locks you in to their platform to unless you want to publish through them it's not really an option.
A self-hosting option for this type of software, open source or not, will be really nice.
I am sure the future of writing looks something like this, (first technical, then all) but it can't happen fast enough for me. I am stuck with Word on my current project but I am planning to write early drafts in Markdown and convert.
https://github.com/bitemyapp/doc-workshop
Uses Pandoc, compiles markdown to LaTeX, LaTeX renders to PDF.
Dynamically re-renders the preview of the PDF as I save my markdown files.
Pandoc admits inline LaTeX in the markdown documents themselves.
Auto-rebuilder script by http://twitter.com/mwotton
Learn about Pandoc here: http://johnmacfarlane.net/pandoc/
I edit in Emacs, but you can use whatever obviously.