Re: Literate programming

[Nikita Karetnikov <nikita@karetnikov.org>]

[-- Attachment #1: Type: text/plain, Size: 1847 bytes --]

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

Are you talking about the pdf versions?  Could you show an example?

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

I don't understand this part.  Is it trying to say that it was necessary
to rewrite the relevant parts of the manual by hand?  Is it trying to
say that the sources were moved somewhere from Guile-Lib?  Is it about
the code or the manual?

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

Good, I agree.

> We would still write appropriate text to provide context and
> cross-references above the raw function @deffn lists.

OK.  But I hope that the glue text won't be technical but philosophical
(to avoid mistakes).  For instance, it can explain the rationale or talk
about the GNU system.

Each module should be self-contained.  It should be possible to import
it somewhere without a problem.  Basically, the current version of the
manual follows the same approach; each module has its own node:
"Invoking guix-daemon," "Invoking guix package," and so forth.

So it's only necessary to represent this information using docstrings
and commentary (i.e., a module-level documentation).

Could you explore the possibilities of the literate programming system?
So we can identify the missing bits.  Of course, I'll do the same.

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]