Documentation (and Literate Programming)

[Wolfgang Jährling]

Hi!

I have been pondering about one thing for a while, but now I want to get
peoples opinion. As some of you will know, I'm working on a piece of
documentation called the Hurd Hacking Guide (HHG), which is basically a
collection of example programs with longer explanations.

Now I want to write a diskfs example. I thought that implementing
minixfs is a good idea. Ok, so I want to implement it, but also explain
libdiskfs and - as we don't have free documentation about such stuff -
explain file systems in general. Doing this all at once, I have various
choices:

- Write minixfs like any other program, and create a lot of redundancy
  by copying parts of it into the HHG.
- Add lots of comments to the source which one would normally not add
  and refer from the HHG to the source.
- Use Literate Programming. While I find LP a bit strange, it seems to
  be a good choice here. But then we would still have a different
  document for the diskfs example, i.e. it would be outside of the HHG,
  and in addition to that, one would need special software to generate
  the code and/or the documentation.

I don't like any of these choices as they stand. Other suggestions? What
would be the most comfortable thing for (current and future) people who
want to learn about the Hurd?

Cheers,
GNU/Wolfgang

-- 
Wolfgang Jährling  <wolfgang@pro-linux.de>  \\  http://stdio.cjb.net/
Debian GNU/Hurd user && Debian GNU/Linux user \\  http://www.gnu.org/
The Hurd Hacking Guide: http://www.gnu.org/software/hurd/hacking-guide/
["We're way ahead of you here. The Hurd has always been on the    ]
[ cutting edge of not being good for anything." -- Roland McGrath ]