Re: Literate programming

[ludo@gnu.org (Ludovic Courtès)]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> Here is what I found yesterday: [1,2].  Those (texinfo ...) modules
> provide various functions to generate html, pdf, and info from a single
> source file.

[...]

> [1] http://wingolog.org/archives/2004/07/25/literate-programming-with-guile-lib
> [2] http://wingolog.org/archives/2006/11/17/high-on-sodium-vapor

Guile-Lib’s method was eventually integrated in Guile 2.0, to generate
the documentation of modules that were imported from Guile-Lib, such as
the texinfo and sxml modules.  The result, as can be seen in Guile’s
manual up to 2.0.7, was of poor quality compared to the rest of the
manual.

That’s why the upcoming 2.0.8 (due in a couple of days) got rid of
that.  NEWS reads this (written by Andy):

  ** An end to the generated-documentation experiment.

  When Guile 2.0 imported some modules from Guile-Lib, they came with a
  system that generated documentation from docstrings and module
  commentaries.  This produced terrible documentation.  We finally bit the
  bullet and incorporated these modules into the main text, and will be
  improving them manually over time, as is the case with SXML.  Help is
  appreciated.

So yes, you’re right that synchronizing code (and docstrings) with a
separate Texinfo manual can lead to discrepancies.  Yet, “good” manuals
can hardly be automatically generated.

For Guix, perhaps a middle ground approach could be used.  For instance,
we would keep the manual in its current form, but extract docstrings for
internal modules in separate .texi files, which would be @included in
the right places of the manual.  (It would be an improvement over the
current situation where almost none of the API documentation appears in
the manual.)  We would still write appropriate text to provide context
and cross-references above the raw function @deffn lists.

WDYT?

Thanks,
Ludo’.