Thu, 23 Apr 2009
I really like how easy reStructuredText makes adding custom interpreted text roles [1] [2]. I do a fair bit for writing for the RPGs campaigns I run or play, and the custom roles are useful for mark specific things, like spell names or skill names.
| [1] | http://docutils.sourceforge.net/docs/ref/rst/roles.html#customization |
| [2] | http://docutils.sourceforge.net/docs/ref/rst/directives.html#role |
Tue, 21 Apr 2009
I've recently changed the way I build my website, from using DocBook source and the DocBook XSL Stylesheets to convert it to HTML, over to reStructuredText source and Sphinx to convert it over to HTML. Sphinx is much faster and less resource intensive for the way I build my website, and is more reliable about noticing when things have changed than my old hacked up cook- or make-based build systems. Since updating the site is now much easier I'm much more likely to actually do so.
Sun, 10 Aug 2008
I'm slowly figuring out more about pyBlosxom, and will eventually end up with a reasonable set of blog tools. This evening I've been figuring out more about statically rendering my blog, which ought to overcome the noticable lags when accessing my blog. I haven't switched the actual blog over to static rendering yet, but I'm getting closer. So far the incremental part doesn't seem to be working.
I considered moving to awb, an AsciiDoc-based Website Builder, but I still find the reStructuredText markup slightly nicer. If only there was a good reStructuredText to DocBook path I'd have no qualms at all.
Tue, 08 Jul 2008
Note
This is unfinished.
I still like plain text. Almost none of the e-mail that I get that uses HTML formatting actually gains anything from the additional complexity.
Most of my writing doesn't require a 200 mebibyte word processor installation that still can't do reasonable intra-document linking, much less inter-document linking. Moreover, whenever I have to use such a beast, the conceptual overhead always gets in the way. I realize these may just be my own quirks, but they really make a difference to me.
So, I like to do my writing in plain (or very nearly plain) text. But I also like having nicely printed documents, plus some hope of being able to move from the plain text documents to something more sophisticated on those occasions where it is warranted. So, what do I do?
I use AsciiDoc and reStructuredText (aka ReST) for writing.
Why both? Well, they both have pluses and minuses.
reStructuredText
Pros: I found reStructuredText first. It looks pretty good as plain text, and produces clean HTML and PDF. It can handle deeper structures off the bat than AsciiDoc, which is occasionally important to me. (Some document formats require absurdly deep levels of nested sections.) It can be turned into PDF using LaTeX fairly easily.
Cons: some of the systems I use regularly don't have good packages for docutils, the underlying toolset. This may be in part because although docutils has a long history and is pretty solid, it's still not considered version 1.0 material. I get the surface impression that there are still some things that the developers are thinking about. And there isn't a supported DocBook output format. That's a real shame.
AsciiDoc
Pros: AsciiDoc, just like reStructuredText, can go straight to HTML. And AsciiDoc's HTML looks nicer straight out of the box.
AsciiDoc is also explicitly a plain-text encoding of DocBook. This lets you be sure you can convert it to something widely used and well understood, which can then be converted by well-known tools into various other formats including PDF and HTML.
It has better package support amongst the environments I use.
Cons: not as pretty looking in source form as reStructuredText.
Conclusions
I wish it was easier to add special purpose structure to both AsciiDoc and reStructuredText that can easily added to all the output formats, for special purpose things like RPG stats or other complicated technical documentation.
So, what do I do when I need something more sophisticated? Use DocBook, of course.