From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nikita Karetnikov Subject: Re: Literate programming Date: Sat, 06 Apr 2013 05:21:11 +0400 Message-ID: <87y5cwxxmg.fsf@karetnikov.org> References: <87obfzhmbk.fsf@karetnikov.org> <877gmnsq5z.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha1; protocol="application/pgp-signature" Return-path: Received: from eggs.gnu.org ([208.118.235.92]:51009) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UOHmB-0000PS-PH for bug-guix@gnu.org; Fri, 05 Apr 2013 21:18:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UOHm6-0002it-JZ for bug-guix@gnu.org; Fri, 05 Apr 2013 21:18:39 -0400 In-Reply-To: <877gmnsq5z.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "(unknown date)") List-Id: Bug reports for GNU Guix List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: bug-guix@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable >> What do you think about literate programming [1,2,3]? > I don=E2=80=99t think it=E2=80=99s appropriate here. We have (or should = have) user doc > for command-line tools, a manual for the API, as well as an on-line > reference in the form of docstrings; the code itself is reasonably > commented, I think, and in a functional style that hopefully simplifies > reasoning a bit (I know there=E2=80=99s more to it than just writing func= tional > code, but still, it=E2=80=99s better than TeX macros ;-)). > WDYT? Here is what I found yesterday: [1,2]. Those (texinfo ...) modules provide various functions to generate html, pdf, and info from a single source file. If different files are used, it's easy to end up with undocumented code [3] or to have a documentation for nonexistent functions [4]. There might be some problems (I've only checked a couple of functions). Though, I hope that we'll give it a try. The only drawback I see right now is the need to adapt the existing modules. But I'm willing to do it. [1] http://wingolog.org/archives/2004/07/25/literate-programming-with-guile= -lib [2] http://wingolog.org/archives/2006/11/17/high-on-sodium-vapor [3] https://lists.gnu.org/archive/html/guile-user/2007-06/msg00046.html [4] https://lists.gnu.org/archive/html/bug-guile/2013-04/msg00000.html --=-=-= Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) iQIcBAEBAgAGBQJRX3iKAAoJEM+IQzI9IQ38CucP/25D5IXrRXr9AMWPqA6E2Cgz gGfSWtzi9xVH1mD/XfMjtAOP1O3lwpfhp2DjOCYJyX/ZNCqX+FXMJz4IoFPLHyE1 fGhvrcACmTvax+RxoW3I57JRD+FXqwKQej5OfC7UelRlSy0stOmpPfPObB+70OZk rejeKrHY2hME2QFH9CmiX3f9XIcx5jiPEzNXaAb5unBvOtoJ2dNsClvHANf0Z6ry /NIxiiPJwlhMf2iJ4XCmky9AJk89qxXKBFUKoe3M8d7Til+G7GG1VmjHY5Oo/L4z 6GEYaXQ8Mk5tLUo+P2Ztw4Z+0QnjNkjNZJxu0HwF9pjoNFWrp9o3Th1W6E+Z+nw+ +dpMSS3emuwgpI8WQmDUCslKB9P7zSs5BYb8HZrjZXPleUqcfCaOdw59Rq2xR8Bk vFUbfAUUmjPbz3wlXrJHSaj/p4caq2wdIsY91AtzNrcHnGH4vY+3ozMwDHYB9fL9 Y+ZXLNWmaM0K9d24XyiqmKEw59PFXBVZIOSTdYKyxRobAoMm+CqpnkAFfs3LfTmn B1LpNaeSHw/EDhjShdASvL6tO8M6Fgv32NX/08xElxClvNRrk6uwGvJP4Kja5qRU bAffm2tL4VNf42NUK/h48KepsqB1xUOZycm8g2q7qrxAtbN1cjr/Z3ZCoodro489 sPDNcq3FHd2cBVdxY43O =CMrO -----END PGP SIGNATURE----- --=-=-=--