Re: Documentation (and Literate Programming)

[Michael Teichgräber]

Wolfgang Jährling <wolfgang@pro-linux.de> writes:

> Now I want to write a diskfs example. I thought that implementing
> minixfs is a good idea. [...]
> 
> - Write minixfs like any other program, and create a lot of redundancy
>   by copying parts of it into the HHG.

You could turn the HHG texinfo source into a skeleton and, besides
this, insert marks (like `/* HHG begin XY */') into the C sources of
minixfs. Later the skeleton could be compiled with use of the minixfs
sources into the HHG by means of perhaps sed, awk ... so that you
wouldn't have redundancy. But, if much code would be needed within the
document, this could make the C sources difficult to read.


> - Use Literate Programming. While I find LP a bit strange, it seems to
>   be a good choice here. 

Some people would say, it always is a good choice. ;-)


>   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.

So, minixfs' C sources and its documentation could be generated by a
single document outside the HHG. One problem that could arise, if you
take CWEB as an example, that the C sources would not match--as optic
is concerned--some parts of the GCSs.

To me it has been a hurdle that I need to view the (LP) documented
source codes with tools as xdvi or gv, or have to print it on paper to
get an overview about it. With `info' or an editor its often easier to
me to view and look for information.


> would be the most comfortable thing for (current and future) people
> who want to learn about the Hurd?

But, besides this, I have a feeling that LP is the right thing; one
could for instance combine C and texinfo by means of scripts to do
something similar like LP (the result indeed could be similar to
e.g. CWEB documents, but would additionally be browseable in various
formats).

(There also have been approaches to do LP with SGML/XML. There could
be a DTD and tools that would translate an SGML document into texinfo
or C source.)


Michael