[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Literate programming

From: Ludovic Courtès
Subject: Re: Literate programming
Date: Sat, 11 May 2013 18:14:35 +0200
User-agent: Gnus/5.130005 (Ma Gnus v0.5) Emacs/24.3 (gnu/linux)

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]