

Ask HN: Best working file format for writing open source books? - compay

A friend and I are starting to write a book, which we intend to publish and distribute ourselves under a Creative Commons license. Since we're both programmers we want to use a plain text format to work with, and maintain versions using Git. We'd like to (reasonably) easily output formats like HTML, PDF, print, eBook, etc. while also keeping the files easy to edit. What do you recommend as a working file format? I have considered Latex and HTML but wonder if there isn't something better.
======
SwellJoe
I used Docbook SGML (and later XML) for my book about Webmin. It wasn't worth
the pain.

I've worked on another large Open Source project that used Word (yes, really!)
and OpenOffice with custom templates and conversion tools (they would, for the
most part, save as HTML, and then convert from that to PyDoc, .chm, and
several other formats).

I later converted the Webmin book into wiki format (TWiki, specifically), and
now we're in the midst of moving it to Markdown (with extensions). I like
Markdown best of all, and is now what we're using for _everything_ (forums,
tickets in the issue tracker, and all documentation).

Don't underestimate the cost of hard to deal with formats. Docbook produced
beautiful output, and in many formats, and was useful for pulling data out
automatically. But, the effort involved in writing the docs was atrocious.
Even with good tools (most competent XML-capable editors can work with Docbook
pretty well...I used jEdit in the end), you'll produce half the docs with
twice the frustration. With Markdown, when you need more control you can drop
to straight HTML.

Markdown works great in revision control systems, and is easy to generate
programmatically (we've started exporting our API doc PODs to Markdown, for
example). Nearly everything support it, as well. Our new CMS is Drupal, and it
has great Markdown support, and there are converters from various wikis (we
have more than a thousand printed pages worth of docs in two different wikis
to be converted).

I can wholeheartedly recommend it. Textile is another popular minimal markup
that I imagine has pretty much all the same advantages as Markdown.

Pandoc might be worth a look, too. I haven't had need for it, yet, but it's
got an awesome feature set, and can do PDF from Markdown (so I probably _will_
use it soon, as we get pretty frequent PDF requests).

------
makecheck
I have used reStructuredText (which both "docutils" and "prest" can use to
generate documents). The source text actually _is_ the plain text "output",
while it is still possible to automatically generate HTML, etc.

For something as complex as a book, reStructuredText is best; though I often
fall back on the simple Textile format for really short documents that still
need to be converted to HTML.

------
aneesh
LaTeX is pretty standard for typesetting math/CS texts of any length. You can
use your favorite version control system, and write a Makefile to build a
PDF/PS document.

If you want to make it easily readable on a webpage (and not just a PDF
download), you may want to use html.

~~~
dantheman
I'll second latex it's really quite powerful and not that hard to use. Also if
your on windows check out protex it's a bundle of everything you need to get
started.

Also there are latex to html converters - I'm not too familiar with them.

------
compay
Thanks everyone for the insightful answers, you've given me some good ideas to
look into.

