Re: Documentation (and Literate Programming)

[James Morrison]

--- Wolfgang_Jährling <wolfgang@pro-linux.de> wrote:
> 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.

 I like this idea. For one, it would be the easier to integrate minixfs into
the actual hurd source.  Also once you have a working version of minixfs you
only need to copy the important parts of the translator into the HHG.

> - Add lots of comments to the source which one would normally not add
>   and refer from the HHG to the source.

 This is pretty good as well, but I think it would be a good idea to put lots
of extra comments in the source code to begin with so people have an easier 
time learning the basics.

> - 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 know much of this style, but wouldn't it be hard to integrate minixfs
into the hurd source?

> 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 ]
> 
> _______________________________________________
> Help-hurd mailing list
> Help-hurd@gnu.org
> http://mail.gnu.org/mailman/listinfo/help-hurd


=====
James Morrison
   University of Waterloo
   Computer Science - Digital Hardware
   2A co-op
http://hurd.dyndns.org

Anyone referring to this as 'Open Source' shall be eaten by a GNU

__________________________________________________
Do You Yahoo!?
Yahoo! - Official partner of 2002 FIFA World Cup
http://fifaworldcup.yahoo.com