Re: Literate programming

[Nikita Karetnikov]

> I wouldn’t want to automatically extract command-line doc.  First,
> because --help needs to be concise, whereas the manual can give
> additional details (compare ‘guix package --help’ and “Invoking guix
> packages”.)  Second, because the manual should include cross-references
> and examples to make things more understandable.

Here is how I see the process: one creates a command-line tool and uses
Commentary to document it.  Then the person should manually @include the
output of extracted and converted Commentary (e.g., 'filename.texi'),
which isn't created at this point.  After that it's only necessary to
run 'make' to compile 'filename.texi' and 'guix.texi'.  (Note that it's
possible to use cross-references.)

I've created a rough example.  'doc/hash-texi.scm' shows how to extract
and convert Commentary.  The same thing should be done for all scripts.
So each 'file.scm' should have a corresponding 'file.texi'.  Other files
in 'guix' will need a different extraction scheme because it's necessary
to get docstrings as well.  I'd like to write a couple of procedures and
put them into a makefile.  Still, it'll be necessary to @include files
manually.

I guess this sounds like a lot of work, but the same approach is also
used with LaTeX [1].  You have a main file, a style file, and other files
which will be included into the main file.

I'd also like to find a way to automatically create a table of contents.

[1] https://en.wikibooks.org/wiki/LaTeX/Modular_Documents

autodoc.diff
Description: Text Data

pgpaG5Cz07MSD.pgp
Description: PGP signature