continuing documentation

[Gordon Matzigkeit]

This is a proposal for how I want to continue working on the Hurd
reference manual.  If you don't like something about my approach,
please tell me, otherwise I'll assume you don't care one way or the
other, and go ahead.

A lot of the work on the Hurd manual that I did so far was taking the
contents of header files, texiing the comments, and breaking things up
into chapters.  I realize this is not the perfect thing to do, but it
puts the interface documentation in one place.  I think the ideal is
to have header comments to describe the functions, with more prosaic
text in between to tie together the main ideas.

I looked at automatic tools for doing this kind of thing, but they all
failed to provide ways of working around text in the generated output.
I wouldn't want to put all the text into the header files.

My latest direction has been to have a little tool that would scan the
headers for functions that aren't documented in the manual.  It would
also provide convenient ways of moving the manual description to the
header files, and vice versa.

Thus, people could easily handle updates to the headers or manual.  I
could also use it to splat the documentation for the remaining
interfaces into the manual.

I intend to write it in Emacs Lisp, since it provides such a rich
environment for doing diffs and making edits while a script is
running.

Any comments?

-- 
 Gordon Matzigkeit <address@hidden>  //\ I'm a FIG (http://fig.org/)
Committed to freedom and diversity \// Do Screen (http://fig.org/gnu/screen/)