From mboxrd@z Thu Jan  1 00:00:00 1970
From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=)
Subject: Re: Literate programming
Date: Sat, 11 May 2013 18:14:35 +0200
Message-ID: <87obchqys4.fsf@gnu.org>
References: <87obfzhmbk.fsf@karetnikov.org> <877gmnsq5z.fsf@gnu.org>
	<87y5cwxxmg.fsf@karetnikov.org> <87d2u76a4q.fsf@gnu.org>
	<87vc7zissi.fsf@karetnikov.org> <871uan35qw.fsf@gnu.org>
	<87ppwz23s1.fsf@karetnikov.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Return-path: <bug-guix-bounces+gcggb-bug-guix=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([208.118.235.92]:46461)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ludo@gnu.org>) id 1UbCRb-0002EW-Qo
	for bug-guix@gnu.org; Sat, 11 May 2013 12:14:49 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <ludo@gnu.org>) id 1UbCRa-0003V3-R3
	for bug-guix@gnu.org; Sat, 11 May 2013 12:14:47 -0400
Received: from [2a01:e0b:1:123:ca0a:a9ff:fe03:271e] (port=32793
	helo=xanadu.aquilenet.fr) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ludo@gnu.org>) id 1UbCRa-0003TT-LP
	for bug-guix@gnu.org; Sat, 11 May 2013 12:14:46 -0400
In-Reply-To: <87ppwz23s1.fsf@karetnikov.org> (Nikita Karetnikov's message of
	"Fri, 10 May 2013 02:21:18 +0400")
List-Id: Bug reports for GNU Guix <bug-guix.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-guix>,
	<mailto:bug-guix-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/bug-guix>
List-Post: <mailto:bug-guix@gnu.org>
List-Help: <mailto:bug-guix-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-guix>,
	<mailto:bug-guix-request@gnu.org?subject=subscribe>
Errors-To: bug-guix-bounces+gcggb-bug-guix=m.gmane.org@gnu.org
Sender: bug-guix-bounces+gcggb-bug-guix=m.gmane.org@gnu.org
To: Nikita Karetnikov <nikita@karetnikov.org>
Cc: bug-guix@gnu.org

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> --- a/guix/scripts/hash.scm
> +++ b/guix/scripts/hash.scm
> @@ -30,6 +30,41 @@
>      #:export (guix-hash))
>=20=20
>  
> +;;; Commentary:
> +;;
> +;; @node Invoking guix hash
> +;; @section Invoking @command{guix hash}
> +;;
> +;; The @command{guix hash} command allows to check the integrity of a fi=
le.
> +;; 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=E2=80=99m reluctant to this approach.  First because currently
=E2=80=9Ccommentary=E2=80=9D is supposed to plain text, so using markup the=
re would be
an inconvenience (for instance, when viewing it in Geiser, it doesn=E2=80=
=99t
get automatically converted from Texinfo.)

Second, it doesn=E2=80=99t 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=E2=80=99.