Re: Literate programming

[Nikita Karetnikov <nikita@karetnikov.org>]

[-- Attachment #1.1: Type: text/plain, Size: 1530 bytes --]

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

Here is how I see the process: one creates a command-line tool and uses
Commentary to document it.  Then the person should manually @include the
output of extracted and converted Commentary (e.g., 'filename.texi'),
which isn't created at this point.  After that it's only necessary to
run 'make' to compile 'filename.texi' and 'guix.texi'.  (Note that it's
possible to use cross-references.)

I've created a rough example.  'doc/hash-texi.scm' shows how to extract
and convert Commentary.  The same thing should be done for all scripts.
So each 'file.scm' should have a corresponding 'file.texi'.  Other files
in 'guix' will need a different extraction scheme because it's necessary
to get docstrings as well.  I'd like to write a couple of procedures and
put them into a makefile.  Still, it'll be necessary to @include files
manually.

I guess this sounds like a lot of work, but the same approach is also
used with LaTeX [1].  You have a main file, a style file, and other files
which will be included into the main file.

I'd also like to find a way to automatically create a table of contents.

[1] https://en.wikibooks.org/wiki/LaTeX/Modular_Documents


[-- Attachment #1.2: autodoc.diff --]
[-- Type: text/x-diff, Size: 5287 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 9147f43..17f7e14 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1214,36 +1214,7 @@ the @code{package-derivation} procedure of the @code{(guix packages)}
 module, and to the @code{build-derivations} procedure of the @code{(guix
 store)} module.
 
-@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}).
-
-The general syntax is:
-
-@example
-guix hash @var{option} @var{file}
-@end example
-
-@command{guix hash} has the following option:
-
-@table @code
-
-@item --format=@var{fmt}
-@itemx -f @var{fmt}
-Write the hash in the given format.
-
-Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
-(@code{hex} and @code{hexadecimal} can be used as well).
-
-If the @option{--format} option is not specified, @command{guix hash}
-will output the hash in @code{nix-base32}.  This representation is used
-in the definitions of packages.
-
-@end table
+@include hash.texi
 
 @node Invoking guix refresh
 @section Invoking @command{guix refresh}
diff --git a/doc/hash-texi.scm b/doc/hash-texi.scm
new file mode 100644
index 0000000..801f92f
--- /dev/null
+++ b/doc/hash-texi.scm
@@ -0,0 +1,29 @@
+;;; GNU Guix --- Functional package management for GNU
+;;; Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
+;;;
+;;; This file is part of GNU Guix.
+;;;
+;;; GNU Guix is free software; you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation; either version 3 of the License, or (at
+;;; your option) any later version.
+;;;
+;;; GNU Guix is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+(use-modules (texinfo serialize)
+             (ice-9 session))
+
+;; 'string->stexi' and 'module-commentary' are used instead of
+;; 'module-stexi-documentation' because we do not want to mention 'guix-hash'
+;; and the names of sections.
+(call-with-output-file "doc/hash.texi"
+  (lambda (out)
+    (format out "~a~%"
+            (stexi->texi ((@@ (texinfo reflection) string->stexi)
+                          (module-commentary '(guix scripts hash)))))))
\ No newline at end of file
diff --git a/doc/hash.texi b/doc/hash.texi
new file mode 100644
index 0000000..a6469da
--- /dev/null
+++ b/doc/hash.texi
@@ -0,0 +1,35 @@
+
+@c %start of fragment
+
+@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}).
+
+The general syntax is:
+
+@example 
+ guix hash @var{option} @var{file}
+@end example
+
+@command{guix hash} has the following option:
+
+@table @code
+@item --format=@var{fmt}
+@itemx -f @var{fmt}
+Write the hash in the given format.
+
+Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
+(@code{hex} and @code{hexadecimal} can be used as well).
+
+If the @option{--format} option is not specified, @command{guix hash}
+will output the hash in @code{nix-base32}.  This representation is used
+in the definitions of packages.
+
+@end table
+
+
+@c %end of fragment
+
diff --git a/guix/scripts/hash.scm b/guix/scripts/hash.scm
index deded63..41346ac 100644
--- a/guix/scripts/hash.scm
+++ b/guix/scripts/hash.scm
@@ -30,6 +30,41 @@
     #:export (guix-hash))
 
 \f
+;;; 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}).
+;;
+;; The general syntax is:
+;;
+;; @example
+;; guix hash @var{option} @var{file}
+;; @end example
+;;
+;; @command{guix hash} has the following option:
+;;
+;; @table @code
+;;
+;; @item --format=@var{fmt}
+;; @itemx -f @var{fmt}
+;; Write the hash in the given format.
+;;
+;; Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
+;; (@code{hex} and @code{hexadecimal} can be used as well).
+;;
+;; If the @option{--format} option is not specified, @command{guix hash}
+;; will output the hash in @code{nix-base32}.  This representation is used
+;; in the definitions of packages.
+;;
+;; @end table
+;;
+;;; Code:
+
 ;;;
 ;;; Command-line options.
 ;;;

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]