Blog roll
R-bloggers, Debian Weekly![[Valid RSS]](valid-rss-rogers.png "Validate my RSS feed")
Last modified:
2007-07-27
In my quest for the best tool for writing and managing documentation of software I develop, I have gone from debiandoc-sgml to muse.
The sgml-based Debiandoc has converters to a nice set of output formats including my favorite reading format info. For me the drawbacks of debiandoc are that it lacks support for tables, and that editing sgml is not fun, not even with EMACS psgml-mode.
debiandoc is considered obsolete in favour of docbook-xml and there is a conversion script that converts from debiandoc to docbook-xml. However after converting my debiandoc document Ordino.sgml without warnings into Ordino.docbookxml, and running
$ xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl Ordino.docbookxml > Ordino.html No template matches listitem in sect1. No template matches listitem in sect2. No template matches listitem in sect1. No template matches listitem in sect2. No template matches listitem in sect1. No template matches listitem in sect2.
There were warnings and the table of contents contained non-working links. I tried another stylesheet chunk.xsl and this time the links worked, however the they where not named only numbered which made navigation hard.
Instead of diving into the wonderful world of docbook-xml, I choosed to use muse, which I had previously used for a blog-like site with notes on computing. But why muse?
I normally prefer editing texts in a almost text-only version. I prefer creating latex with EMACS/auctex rather than lyx. In this regard EMACS/psgml has an advantage against muse, particularly if you are editing an existing document (be it in sgml or xml) rather than writing a new document. Muse has partly changed my view on this. I really enjoy being able to switch between seeing all formatting codes as code and as effect. Perhaps I haven't really learned psgml, but I never find it that easy to edit with as muse. From what I gather, this switching code/effect view was perhaps the most loved part of WordPerfect at least by the hardcore users.
There are problems with muse, though.
Output to info doesn't really work (bad links).
I also met with problem which is probably not a bug, but inherent in the way muse works. I was creating a link to another muse document within the same project. This other file had a non-ascii character ("ö") in its name ("Kön.muse"). The simplest way to make a link in muse is to write =Kön, but this resulted in a non-working link. I had to rename the file (to "Kon.muse") and use the long version of the link format =Kön=.