Living the Future of Technical Writing
medium.com
medium.com
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.
I can do anything Pandoc can do.
It's still early. I wouldn't expect anything earlier than 3-6 months from now if I don't find a coauthor.
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.
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.
It is really an amazing workflow, and makes writing documentation as well as books a breeze.
I would love to see a standardized site building template for asciidoctor, so that we could support it as well as reStructuredText and Markdown.
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
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.)
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.
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.
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.
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.