Re: Markdown version of reference manual

[Ross Berteig <Ross@...>]

Sometime on 7/18/2011, Dirk Laurie wrote:
> ....
> However, the HTML-to-markdown converter Pandoc (which can do a lot
> more too) did not forgive those faults until the most recent version
> 1.8.1.2.  This version does a near-perfect job, as can be tested by
> converting back from markdown to HTML.
>     http://johnmacfarlane.net/pandoc/

As a long-time user of StackOverflow, I've found Markdown to be
an eminently practical compromise between the full expressive
power of a real markup language and just plain legible text. I've
started writing all my project documentation in Markdown and
converting it to PDF with pandoc and LuaLaTex. All the expressive
power of TeX, the ease of expression of Lua when needed, and in a
package that fits neatly in a classic Makefile build system. And
if I needed to generate HTML or CHM, I could easily do that too.

Having recently (re-)discovered the spell mode in my usual editor
has meant that writing decent documentation is easier than ever,
and I don't have to resort to Word, or try to make the binary
.doc or .docx files fit neatly into revision control or into my
build system.

I'd encourage anyone with a document on the scale of the Lua
manual to give Markdown a try.

Ross Berteig                               Ross@CheshireEng.com
Cheshire Engineering Corp.           http://www.CheshireEng.com/