Grendel Schemes

So we've decided we need to version our documentation alongside our code at work. This means we need a documentation solution that plays well with CVS.

Many things were looked at (DocBook, TexInfo, etc.) but nothing tickled the less technical users who would be writing most of the docs. Currently our documentation is in a Wiki so we started discussing the possibility of using a Wiki format stored in CVS and explicitly published to a web as we release the software. This being a fairly natural migration.

The closest thing I've found to the above is Muse Mode for emacs. Muse Mode is really an excellent package, but the project set-up and interaction isn't trivial for Emacs newbies, so I set about writing some Emacs LISP to put a decent front end on it.

Alls well, right up until you publish a project in Muse. Publishing makes this calll:

(muse-project-file-alist project)

.. this function claims to do the following:

"Return member filenames for the given Muse PROJECT. On UNIX, this list is only updated if one of the directories contents have changed. On Windows, it is always reread from disk."

.. however tracing this code through shows that if the source path for publishing is a directory then last-mod will always get set to the current modification time:

(while pats
(if (symbolp (car pats))
(setq pats (cddr pats))
(let ((dir (or (and (file-directory-p (car pats)) (car pats))
(and (not (file-readable-p (car pats)))
(file-directory-p
(file-name-directory (car pats)))
(file-name-directory (car pats))))))
(if dir
(let ((mod-time (nth 5 (file-attributes dir))))
(if (or (null last-mod)
(and mod-time
(muse-time-less-p last-mod mod-time)))
(setq last-mod mod-time)))))
(setq pats (cdr pats))))))

.. this is a shame, because this means the function will always claim there are no files in the project. :-(

So I need to work out how to modify the a-list before this gets called - I've got a feeling that "normal" usage suggests that you publish every file individually before publishing the project as a whole (although I've had no luck finding documentation to support that idea, and it sounds down right odd).

As the #muse channel on freenode seems to be deserted at the moment I'll keep going and see where I get.

I've been using Chicken Scheme for a while now, I really like it. However it's GUI bindings aren't really up to much yet.

I've done a few simple things using bb (a toolkit based on FLTK), but I'm going to need Gtk2 bindings to embark on some more serious projects.

I thought I was in luck when I came across this:

Chicken GTK+ Egg

... but the subversion server and wiki mentioned there seem to have dropped off the web :-(

More searching suggested my best bet might be some work Tony Garnock-Jones did. I downloaded his tarball's from here, but it seems hopelessly out of date (it won't even compile on my box). This post seems to confirm my suspicions, but at least the various groups are talking and it seems (at least) as if the Gtk2 egg will eventually turn up on eggs unlimited.

So, with my adventures in Chicken GUI land on hold for a while i guess the next things on the agenda are "The Reasoned Schemer" and the completion my Emacs based documentation system for work.

All things start somewhere. This starts here. Who knows when or where this will end?

Having recovered from my annual cold right on time to hit the hiatus between Christmas and the New Year, I find myself full of the energy and adventurous spirit required to come up with some resolutions for the year ahead. This is a first for me, and I'm not for a moment suggesting that any of these will survive January, but...

1. Read "The Seasoned Schemer" to reinforce the knowledge gained from reading "The Little Schemer" this autumn


2. Write more Free Software, and do so in Scheme (probably Chicken Scheme)


3. Carry my camera with me as much as possible and in doing so take more and better pictures.


4. Record my experiences of the above here.

I wonder how well I'll keep to these?