Re: Literate programming

[Ludovic Courtès]

Nikita Karetnikov <address@hidden> skribis:

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

It’s poor in terms of presentation, not in terms of typography.

> Could you show an example?

http://www.gnu.org/software/guile/manual/html_node/Standard-Library.html

(Watch it before 2.0.8 is out.)

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

It’s about the manual.  Initially, each of the sections above was
entirely extracted from the corresponding module: the module contained a
comment at the top that would give a rough overview, and the rest was
just taken from docstrings.

The result looked poor mostly because there is little introductory
material, few cross-references, and the modules and procedures are
listed in alphabetical order, which is rarely the right order to
introduce and connect concepts.

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

Yes, the extraction would be for the APIs, which are currently almost
undocumented in the manual.

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

These are not modules, these are commands.

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.

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

What I have in mind is just API documentation.  This is easily done by
traversing the exported bindings, and calling ‘procedure-documentation’.

There’s a complication: currently docstrings in Guile must be Info-style
plain text, not Texinfo (this may change in the future.)  So one would
need to infer Texinfo markup from the docstrings.

Anyway, a clarification: I find it OK to extract docstrings today,
because it’s better than nothing; but to me, a good manual should be
more than a mere paragraph followed by a list of docstrings.

Thanks,
Ludo’.