I'm writing a book for O'Reilly (http://www.obeythetestinggoat.com/), and they recommended AsciiDoc, which I've been really happy with.
http://www.methods.co.nz/asciidoc/userguide.html It's a lot like RST or Markdown, but it's designed to convert to docbooks xml as well as html, so it gives you more publishing-specific tools. Another tool I just found out about, which sounds like it could be a useful addition is dexy, which gives you a templating language for including source code listings and command-line output in your doc in an automated way. http://www.dexy.it/ On 21 April 2013 00:50, Aahz <[email protected]> wrote: > On Sat, Apr 20, 2013, Naomi Ceder wrote: > > > > No useful advice from me, just a caveat. The real pain point I've always > > felt is keeping code snippets current through testing and revision. I > know > > that some people have been working on solutions to this issue. I can tell > > you that managing code when writing in something like Word is a total > > nightmare. > > This was one of the main reasons I chose reST: I wrote a special include > directive that brought in both code and output. (I.e. each example was > a separate external file.) > -- > Aahz ([email protected]) <*> > http://www.pythoncraft.com/ > > "In theory, there is no difference between theory and practice. But, in > practice, there is." --Jan L.A. van de Snepscheut > _______________________________________________ > Python-authors mailing list > [email protected] > http://mail.python.org/mailman/listinfo/python-authors > -- ------------------------------ Harry J.W. Percival ------------------------------ Twitter: @hjwp Mobile: +44 (0) 78877 02511 Skype: harry.percival
_______________________________________________ Python-authors mailing list [email protected] http://mail.python.org/mailman/listinfo/python-authors
