Re: Literate programming

[Ludovic Courtès]

Nikita Karetnikov <address@hidden> skribis:

> --- a/guix/scripts/hash.scm
> +++ b/guix/scripts/hash.scm
> @@ -30,6 +30,41 @@
>      #:export (guix-hash))
>  
>
> +;;; Commentary:
> +;;
> +;; @node Invoking guix hash
> +;; @section Invoking @command{guix hash}
> +;;
> +;; The @command{guix hash} command allows to check the integrity of a file.
> +;; It is primarily a convenience tool for anyone contributing to the
> +;; distribution: it computes the cryptographic hash of a file, which can be
> +;; used in the definition of a package (@pxref{Defining Packages}).

Honestly I’m reluctant to this approach.  First because currently
“commentary” is supposed to plain text, so using markup there would be
an inconvenience (for instance, when viewing it in Geiser, it doesn’t
get automatically converted from Texinfo.)

Second, it doesn’t buy us anything in terms of automation.  It even
requires some thought to get the build system right (remember that the
GCS mandate that .info files be distributed with tarballs.)

Furthermore, this is really what the failed experiment in Guile did.

Lastly, info "(standards) Doc Strings and Manuals":

     The only good way to use documentation strings in writing a good
  manual is to use them as a source of information for writing good text.

Sorry for being so unenthusiastic.

Ludo’.