Saturday, December 31, 2005
Hacking on muse mode for Emacs
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:
.. this function claims to do the following:
.. 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:
.. 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.
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.
