[PATCH] Turn on more documentation

[PATCH] Turn on more documentation

[Noah Lavine]

[-- Attachment #1: Type: text/plain, Size: 1249 bytes --]

Hello all,

As part of my investigation into modules that don't have
documentation, I discovered that several modules in ice-9/ actually
have usable documentation that we are just not using in our build
process. (For reference, everything in the "Standard Library" section
of the manual is snarfed from .scm source files.) This patch makes
Guile build documentation for (ice-9 binary-ports), (ice-9
common-list), (ice-9 documentation), (ice-9 gap-buffer), (ice-9 runq),
(ice-9 serialize), and (ice-9 time). It gets incorporated into the
manual as part of the "Standard Library" section.

This seems like an easy way to get documentation for a few more
modules. What do you think?

(You may have to do "rm doc/ref/standard-library.texi && rm
doc/ref/guile.info*" in order to build with the change. The makefile
doesn't know about all of the dependencies that it should.)

I also discovered while working on this that several modules have
in-line commentary and also hand-written texinfo pages. The list is
expect.scm, ftw.scm, futures.scm, getopt-long.scm, i18n.scm,
optargs.scm, q.scm, regex.scm, threads.scm, and vlist.scm. Was there a
reason for this? Perhaps the inline documentation format isn't as
flexible as writing it by hand?

Thanks,
Noah

[-- Attachment #2: 0001-Turn-on-documentation-for-more-modules.patch --]
[-- Type: application/octet-stream, Size: 3494 bytes --]

From b1447d255e55ff193cc6751fb3d22b89c6006321 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Wed, 2 May 2012 23:07:58 -0400
Subject: [PATCH] Turn on documentation for more modules

 * doc/ref/standard-library.scm (*modules*): add
  (ice-9 binary-ports), (ice-9 common-list), (ice-9 documentation),
  (ice-9 gap-buffer), (ice-9 runq), (ice-9 serialize), and
  (ice-9 time).
 * doc/ref/standard-library.am: automatically generated from
  doc/ref/standard-library.scm.
---
 doc/ref/standard-library.am  |    2 +-
 doc/ref/standard-library.scm |   16 +++++++++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/doc/ref/standard-library.am b/doc/ref/standard-library.am
index 27246f4..f902463 100644
--- a/doc/ref/standard-library.am
+++ b/doc/ref/standard-library.am
@@ -1,2 +1,2 @@
 # Automatically generated, do not edit.
-standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm 
\ No newline at end of file
+standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm $(top_srcdir)/module/ice-9/binary-ports.scm $(top_srcdir)/module/ice-9/common-list.scm $(top_srcdir)/module/ice-9/documentation.scm $(top_srcdir)/module/ice-9/gap-buffer.scm $(top_srcdir)/module/ice-9/runq.scm $(top_srcdir)/module/ice-9/serialize.scm $(top_srcdir)/module/ice-9/time.scm 
\ No newline at end of file
diff --git a/doc/ref/standard-library.scm b/doc/ref/standard-library.scm
index 7fd17b5..2869c2e 100644
--- a/doc/ref/standard-library.scm
+++ b/doc/ref/standard-library.scm
@@ -33,7 +33,21 @@
     ((texinfo serialize)
      "Render " (code "stexi") " as texinfo")
     ((texinfo reflection)
-     "Enable texinfo across Guile's help system")))
+     "Enable texinfo across Guile's help system")
+    ((ice-9 binary-ports)
+     "Access to binary ports")
+    ((ice-9 common-list)
+     "List manipulation functions from Common Lisp")
+    ((ice-9 documentation)
+     "Generate documentation from source files")
+    ((ice-9 gap-buffer)
+     "Strings with fast insertion")
+    ((ice-9 runq)
+     "Run tasks from a queue")
+    ((ice-9 serialize)
+     "Syntax for multithreading")
+    ((ice-9 time)
+     "See how long things take to run")))
 
 (define *module-sources*
   '(((sxml ssax) . "http://ssax.sourceforge.net/")
-- 
1.7.6

Re: [PATCH] Turn on more documentation

[Noah Lavine]

[-- Attachment #1: Type: text/plain, Size: 2069 bytes --]

Replying to myself, I've attached two more patches, which document two
more modules.

The approach I've been taking is to take the comments that modules
already have and convert them to the documentation format that
(texinfo reflection) understands. If people agree that this is a good
approach, there are a few more modules I can convert easily, but I'd
like to check that we want to use this approach before doing a lot of
work and getting out of sync with the main repository.

I can say more about the tradeoffs if anyone is interested, but I
think this is the right choice because we can use it right now. Other
options would give prettier documentation, but would be more work.

Noah

On Wed, May 2, 2012 at 11:20 PM, Noah Lavine <noah.b.lavine@gmail.com> wrote:
> Hello all,
>
> As part of my investigation into modules that don't have
> documentation, I discovered that several modules in ice-9/ actually
> have usable documentation that we are just not using in our build
> process. (For reference, everything in the "Standard Library" section
> of the manual is snarfed from .scm source files.) This patch makes
> Guile build documentation for (ice-9 binary-ports), (ice-9
> common-list), (ice-9 documentation), (ice-9 gap-buffer), (ice-9 runq),
> (ice-9 serialize), and (ice-9 time). It gets incorporated into the
> manual as part of the "Standard Library" section.
>
> This seems like an easy way to get documentation for a few more
> modules. What do you think?
>
> (You may have to do "rm doc/ref/standard-library.texi && rm
> doc/ref/guile.info*" in order to build with the change. The makefile
> doesn't know about all of the dependencies that it should.)
>
> I also discovered while working on this that several modules have
> in-line commentary and also hand-written texinfo pages. The list is
> expect.scm, ftw.scm, futures.scm, getopt-long.scm, i18n.scm,
> optargs.scm, q.scm, regex.scm, threads.scm, and vlist.scm. Was there a
> reason for this? Perhaps the inline documentation format isn't as
> flexible as writing it by hand?
>
> Thanks,
> Noah

[-- Attachment #2: 0001-Document-ice-9-and-let-star.patch --]
[-- Type: application/octet-stream, Size: 4166 bytes --]

From ffb8664621684e442062c756ba545daa16da815f Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Thu, 3 May 2012 10:33:41 -0400
Subject: [PATCH 1/2] Document (ice-9 and-let-star)

 * module/ice-9/and-let-star.scm: add commentary and a docstring.
 * doc/ref/standard-library.scm: incorporate (ice-9 and-let-star)
   commentary in the build system.
 * doc/ref/standard-library.am: automatically generated from
   standard-library.scm.
---
 doc/ref/standard-library.am   |    2 +-
 doc/ref/standard-library.scm  |    2 ++
 module/ice-9/and-let-star.scm |    9 ++++++++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/doc/ref/standard-library.am b/doc/ref/standard-library.am
index f902463..56e8755 100644
--- a/doc/ref/standard-library.am
+++ b/doc/ref/standard-library.am
@@ -1,2 +1,2 @@
 # Automatically generated, do not edit.
-standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm $(top_srcdir)/module/ice-9/binary-ports.scm $(top_srcdir)/module/ice-9/common-list.scm $(top_srcdir)/module/ice-9/documentation.scm $(top_srcdir)/module/ice-9/gap-buffer.scm $(top_srcdir)/module/ice-9/runq.scm $(top_srcdir)/module/ice-9/serialize.scm $(top_srcdir)/module/ice-9/time.scm 
\ No newline at end of file
+standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm $(top_srcdir)/module/ice-9/and-let-star.scm $(top_srcdir)/module/ice-9/binary-ports.scm $(top_srcdir)/module/ice-9/common-list.scm $(top_srcdir)/module/ice-9/documentation.scm $(top_srcdir)/module/ice-9/gap-buffer.scm $(top_srcdir)/module/ice-9/runq.scm $(top_srcdir)/module/ice-9/serialize.scm $(top_srcdir)/module/ice-9/time.scm 
\ No newline at end of file
diff --git a/doc/ref/standard-library.scm b/doc/ref/standard-library.scm
index 2869c2e..ec1491b 100644
--- a/doc/ref/standard-library.scm
+++ b/doc/ref/standard-library.scm
@@ -34,6 +34,8 @@
      "Render " (code "stexi") " as texinfo")
     ((texinfo reflection)
      "Enable texinfo across Guile's help system")
+    ((ice-9 and-let-star)
+     "The and-let* syntax")
     ((ice-9 binary-ports)
      "Access to binary ports")
     ((ice-9 common-list)
diff --git a/module/ice-9/and-let-star.scm b/module/ice-9/and-let-star.scm
index bfd597b..dd848d4 100644
--- a/module/ice-9/and-let-star.scm
+++ b/module/ice-9/and-let-star.scm
@@ -17,11 +17,18 @@
 ;;;; License along with this library; if not, write to the Free Software
 ;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
+
+;;; Commentary:
+
+;; This module provides the and-let* syntax, as defined in SRFI-2.
+
+;;; Code:
+
 (define-module (ice-9 and-let-star)
   :export-syntax (and-let*))
 
 (defmacro and-let* (vars . body)
-
+  "and-let* works like let*, except that if one of its value expressions returns false, the remaining value expressions and the body are not evaluated, and the and-let* returns false."
   (define (expand vars body)
     (cond
      ((null? vars)
-- 
1.7.6


[-- Attachment #3: 0002-Document-ice-9-calling.patch --]
[-- Type: application/octet-stream, Size: 12972 bytes --]

From 25f48ef9ba05324f96a60a7495b41de9be43e0f5 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Thu, 3 May 2012 11:46:28 -0400
Subject: [PATCH 2/2] Document (ice-9 calling)

 * module/ice-9/calling.scm: reformat documentation in a way that
   the build system will understand.
 * doc/ref/standard-library.scm: make the build system pick up
   documentation from (ice-9 calling).
 * doc/ref/standard-library.am: automatically generated from
   standard-library.scm.
---
 doc/ref/standard-library.am  |    2 +-
 doc/ref/standard-library.scm |    2 +
 module/ice-9/calling.scm     |  230 +++++++++++++++++++-----------------------
 3 files changed, 108 insertions(+), 126 deletions(-)

diff --git a/doc/ref/standard-library.am b/doc/ref/standard-library.am
index 56e8755..2ef630a 100644
--- a/doc/ref/standard-library.am
+++ b/doc/ref/standard-library.am
@@ -1,2 +1,2 @@
 # Automatically generated, do not edit.
-standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm $(top_srcdir)/module/ice-9/and-let-star.scm $(top_srcdir)/module/ice-9/binary-ports.scm $(top_srcdir)/module/ice-9/common-list.scm $(top_srcdir)/module/ice-9/documentation.scm $(top_srcdir)/module/ice-9/gap-buffer.scm $(top_srcdir)/module/ice-9/runq.scm $(top_srcdir)/module/ice-9/serialize.scm $(top_srcdir)/module/ice-9/time.scm 
\ No newline at end of file
+standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm $(top_srcdir)/module/ice-9/and-let-star.scm $(top_srcdir)/module/ice-9/binary-ports.scm $(top_srcdir)/module/ice-9/calling.scm $(top_srcdir)/module/ice-9/common-list.scm $(top_srcdir)/module/ice-9/documentation.scm $(top_srcdir)/module/ice-9/gap-buffer.scm $(top_srcdir)/module/ice-9/runq.scm $(top_srcdir)/module/ice-9/serialize.scm $(top_srcdir)/module/ice-9/time.scm 
\ No newline at end of file
diff --git a/doc/ref/standard-library.scm b/doc/ref/standard-library.scm
index ec1491b..dd96e21 100644
--- a/doc/ref/standard-library.scm
+++ b/doc/ref/standard-library.scm
@@ -38,6 +38,8 @@
      "The and-let* syntax")
     ((ice-9 binary-ports)
      "Access to binary ports")
+    ((ice-9 calling)
+     "Syntax for common calling conventions")
     ((ice-9 common-list)
      "List manipulation functions from Common Lisp")
     ((ice-9 documentation)
diff --git a/module/ice-9/calling.scm b/module/ice-9/calling.scm
index f66bba2..835331d 100644
--- a/module/ice-9/calling.scm
+++ b/module/ice-9/calling.scm
@@ -27,109 +27,97 @@
 		  with-delegating-configuration-getter-and-setter
 		  let-with-configuration-getter-and-setter))
 
-;;;;
+;;; Commentary:
 ;;;
-;;; This file contains a number of macros that support 
+;;; This module contains a number of macros that support 
 ;;; common calling conventions.
 
-;;;
-;;; with-excursion-function <vars> proc
-;;;  <vars> is an unevaluated list of names that are bound in the caller.
-;;;  proc is a procedure, called:
-;;;	     (proc excursion)
-;;;
-;;;  excursion is a procedure isolates all changes to <vars>
-;;;  in the dynamic scope of the call to proc.  In other words,
-;;;  the values of <vars> are saved when proc is entered, and when
-;;;  proc returns, those values are restored.   Values are also restored
-;;;  entering and leaving the call to proc non-locally, such as using
-;;;  call-with-current-continuation, error, or throw.
-;;;
+;;; Code:
+
 (defmacro with-excursion-function (vars proc)
+"vars is an unevaluated list of names that are bound in the caller.
+proc is a procedure, called:
+           (proc excursion)
+
+excursion is a procedure isolates all changes to vars
+in the dynamic scope of the call to proc.  In other words,
+the values of vars are saved when proc is entered, and when
+proc returns, those values are restored.   Values are also restored
+entering and leaving the call to proc non-locally, such as using
+call-with-current-continuation, error, or throw."
   `(,proc ,(excursion-function-syntax vars)))
 
+(defmacro with-getter-and-setter (vars proc)
+"vars is an unevaluated list of names that are bound in the caller.
+proc is a procedure, called:
+   (proc getter setter)
+
+getter and setter are procedures used to access
+or modify vars.
 
+setter, called with keywords arguments, modifies the named
+values.   If \"foo\" and \"bar\" are among vars, then:
 
-;;; with-getter-and-setter <vars> proc
-;;;  <vars> is an unevaluated list of names that are bound in the caller.
-;;;  proc is a procedure, called:
-;;;	(proc getter setter)
-;;; 
-;;;  getter and setter are procedures used to access
-;;;  or modify <vars>.
-;;; 
-;;;  setter, called with keywords arguments, modifies the named
-;;;  values.   If "foo" and "bar" are among <vars>, then:
-;;; 
-;;;	(setter :foo 1 :bar 2)
-;;;	== (set! foo 1 bar 2)
-;;; 
-;;;  getter, called with just keywords, returns
-;;;  a list of the corresponding values.  For example,
-;;;  if "foo" and "bar" are among the <vars>, then
-;;; 
-;;;	(getter :foo :bar)
-;;;	=> (<value-of-foo> <value-of-bar>)
-;;; 
-;;;  getter, called with no arguments, returns a list of all accepted 
-;;;  keywords and the corresponding values.  If "foo" and "bar" are
-;;;  the *only* <vars>, then:
-;;; 
-;;;	(getter)
-;;;	=> (:foo <value-of-bar> :bar <value-of-foo>)
-;;; 
-;;;  The unusual calling sequence of a getter supports too handy
-;;;  idioms:
-;;; 
-;;;	(apply setter (getter))		;; save and restore
-;;; 
-;;;	(apply-to-args (getter :foo :bar)		;; fetch and bind
-;;;		    (lambda (foo bar) ....))
-;;; 
-;;;     ;; [ "apply-to-args" is just like two-argument "apply" except that it 
-;;;	;;   takes its arguments in a different order.
-;;; 
-;;;
-(defmacro with-getter-and-setter (vars proc)
+   (setter :foo 1 :bar 2)
+   == (set! foo 1 bar 2)
+
+getter, called with just keywords, returns
+a list of the corresponding values.  For example,
+if \"foo\" and \"bar\" are among the vars, then
+
+   (getter :foo :bar)
+   => (<value-of-foo> <value-of-bar>)
+
+getter, called with no arguments, returns a list of all accepted 
+keywords and the corresponding values.  If \"foo\" and \"bar\" are
+the *only* vars, then:
+
+   (getter)
+   => (:foo <value-of-bar> :bar <value-of-foo>)
+
+The unusual calling sequence of a getter supports two handy
+idioms:
+
+   (apply setter (getter))		;; save and restore
+
+   (apply-to-args (getter :foo :bar)		;; fetch and bind
+   	    (lambda (foo bar) ....))
+
+   ;; [ \"apply-to-args\" is just like two-argument \"apply\" except that it 
+   ;;   takes its arguments in a different order."
   `(,proc ,@ (getter-and-setter-syntax vars)))
 
-;;; with-getter vars proc
-;;;   A short-hand for a call to with-getter-and-setter.
-;;;   The procedure is called:
-;;;		(proc getter)
-;;;
 (defmacro with-getter (vars proc)
+"A short-hand for a call to with-getter-and-setter.
+The procedure is called:
+     (proc getter)"
   `(,proc ,(car (getter-and-setter-syntax vars))))
 
 
-;;; with-delegating-getter-and-setter <vars> get-delegate set-delegate proc
-;;;   Compose getters and setters.
-;;; 
-;;;   <vars> is an unevaluated list of names that are bound in the caller.
-;;;   
-;;;   get-delegate is called by the new getter to extend the set of 
-;;;	gettable variables beyond just <vars>
-;;;   set-delegate is called by the new setter to extend the set of 
-;;;	gettable variables beyond just <vars>
-;;;
-;;;   proc is a procedure that is called
-;;;		(proc getter setter)
-;;;
 (defmacro with-delegating-getter-and-setter (vars get-delegate set-delegate proc)
+"Compose getters and setters.
+
+vars is an unevaluated list of names that are bound in the caller.
+
+get-delegate is called by the new getter to extend the set of 
+	gettable variables beyond just vars
+set-delegate is called by the new setter to extend the set of 
+	gettable variables beyond just vars
+
+proc is a procedure that is called
+	(proc getter setter)"
   `(,proc ,@ (delegating-getter-and-setter-syntax vars get-delegate set-delegate)))
 
 
-;;; with-excursion-getter-and-setter <vars> proc
-;;;   <vars> is an unevaluated list of names that are bound in the caller.
-;;;   proc is called:
-;;;
-;;;		(proc excursion getter setter)
-;;;
-;;;   See also:
-;;;	with-getter-and-setter
-;;;	with-excursion-function
-;;;
 (defmacro with-excursion-getter-and-setter (vars proc)
+"vars is an unevaluated list of names that are bound in the caller.
+proc is called:
+
+	(proc excursion getter setter)
+
+See also:
+	with-getter-and-setter
+	with-excursion-function"
   `(,proc  ,(excursion-function-syntax vars)
 	  ,@ (getter-and-setter-syntax vars)))
 
@@ -229,33 +217,28 @@
 			(,loop-name (cddr ,args-name)))))))))
 
 
+(defmacro with-configuration-getter-and-setter (vars-etc proc)
+"Create a getter and setter that can trigger arbitrary computation.
 
+vars-etc is a list of variable specifiers, explained below.
+proc is called:
 
-;;; with-configuration-getter-and-setter <vars-etc> proc
-;;;
-;;;  Create a getter and setter that can trigger arbitrary computation.
-;;;
-;;;  <vars-etc> is a list of variable specifiers, explained below.
-;;;  proc is called:
-;;;
-;;;		(proc getter setter)
-;;;
-;;;   Each element of the <vars-etc> list is of the form:
-;;;
-;;;	(<var> getter-hook setter-hook)
-;;;
-;;;   Both hook elements are evaluated; the variable name is not.
-;;;   Either hook may be #f or procedure.
-;;;
-;;;   A getter hook is a thunk that returns a value for the corresponding
-;;;   variable.   If omitted (#f is passed), the binding of <var> is
-;;;   returned.
-;;;
-;;;   A setter hook is a procedure of one argument that accepts a new value
-;;;   for the corresponding variable.  If omitted, the binding of <var>
-;;;   is simply set using set!.
-;;;
-(defmacro with-configuration-getter-and-setter (vars-etc proc)
+  	(proc getter setter)
+
+Each element of the vars-etc list is of the form:
+
+	(var getter-hook setter-hook)
+
+Both hook elements are evaluated; the variable name is not.
+Either hook may be #f or procedure.
+
+A getter hook is a thunk that returns a value for the corresponding
+variable.   If omitted (#f is passed), the binding of var is
+returned.
+
+A setter hook is a procedure of one argument that accepts a new value
+for the corresponding variable.  If omitted, the binding of var
+is simply set using set!."
   `((lambda (simpler-get simpler-set body-proc)
       (with-delegating-getter-and-setter ()
 	simpler-get simpler-set body-proc))
@@ -304,23 +287,20 @@
     ,proc))
 
 
-;;; let-configuration-getter-and-setter <vars-etc> proc
-;;;
-;;;   This procedure is like with-configuration-getter-and-setter (q.v.)
-;;;   except that each element of <vars-etc> is:
-;;;
-;;;		(<var> initial-value getter-hook setter-hook)
-;;;
-;;;   Unlike with-configuration-getter-and-setter, let-configuration-getter-and-setter
-;;;   introduces bindings for the variables named in <vars-etc>.
-;;;   It is short-hand for:
-;;;
-;;;		(let ((<var1> initial-value-1)
-;;;		      (<var2> initial-value-2)
-;;;			...)
-;;;		  (with-configuration-getter-and-setter ((<var1> v1-get v1-set) ...) proc))
-;;;
 (defmacro let-with-configuration-getter-and-setter (vars-etc proc)
+"This procedure is like with-configuration-getter-and-setter (q.v.)
+except that each element of vars-etc is:
+
+	(var initial-value getter-hook setter-hook)
+
+Unlike with-configuration-getter-and-setter, let-configuration-getter-and-setter
+introduces bindings for the variables named in vars-etc.
+It is short-hand for:
+
+	(let ((var1 initial-value-1)
+	      (var2 initial-value-2)
+		...)
+	  (with-configuration-getter-and-setter ((var1 v1-get v1-set) ...) proc))"
   `(let ,(map (lambda (v) `(,(car v) ,(cadr v))) vars-etc)
      (with-configuration-getter-and-setter ,(map (lambda (v) `(,(car v) ,(caddr v) ,(cadddr v))) vars-etc)
 					   ,proc)))
-- 
1.7.6

Re: [PATCH] Turn on more documentation

[Ludovic Courtès]

Hi,

Noah Lavine <noah.b.lavine@gmail.com> skribis:

> As part of my investigation into modules that don't have
> documentation, I discovered that several modules in ice-9/ actually
> have usable documentation that we are just not using in our build
> process. (For reference, everything in the "Standard Library" section
> of the manual is snarfed from .scm source files.) This patch makes
> Guile build documentation for (ice-9 binary-ports), (ice-9
> common-list), (ice-9 documentation), (ice-9 gap-buffer), (ice-9 runq),
> (ice-9 serialize), and (ice-9 time). It gets incorporated into the
> manual as part of the "Standard Library" section.

The problem is that the auto-generated “Standard Library” section looks
very poor in comparison to the rest of the manual.  So we should really
try hard to write good doc by hands for these, and come up with a handy
structure (instead of one node per module, all under “Standard
Library”).

However, I believe Thien-Thi’s Guile 1.4 has good doc for at least some
of these modules, and it would be great if it could be incorporated.

WDYT?

Thanks,
Ludo’.

Re: [PATCH] Turn on more documentation

[Noah Lavine]

Hello,

> The problem is that the auto-generated “Standard Library” section looks
> very poor in comparison to the rest of the manual.  So we should really
> try hard to write good doc by hands for these, and come up with a handy
> structure (instead of one node per module, all under “Standard
> Library”).

I could do that pretty easily, but I'm afraid that documentation that
isn't in the same file as the code would tend to be updated less often
than documentation in the same file. It might not be a problem though,
and I'm happy to try.

The other alternative is to make our documentation format more
expressive, but that might be a lot of trouble.

> However, I believe Thien-Thi’s Guile 1.4 has good doc for at least some
> of these modules, and it would be great if it could be incorporated.
>
> WDYT?

That would be ideal, but I was concerned that the documentation wasn't
copyrighted by the FSF. Unless Thien-Thi is interested in contributing
it, of course.

Noah

Re: [PATCH] Turn on more documentation

[Ludovic Courtès]

Hi!

Noah Lavine <noah.b.lavine@gmail.com> skribis:

> Hello,
>
>> The problem is that the auto-generated “Standard Library” section looks
>> very poor in comparison to the rest of the manual.  So we should really
>> try hard to write good doc by hands for these, and come up with a handy
>> structure (instead of one node per module, all under “Standard
>> Library”).
>
> I could do that pretty easily, but I'm afraid that documentation that
> isn't in the same file as the code would tend to be updated less often
> than documentation in the same file.

All of our manual except “Standard Library” is maintained this way.  It
takes discipline to keep up-to-date, but it also leads to a better
manual IMO.

>> However, I believe Thien-Thi’s Guile 1.4 has good doc for at least some
>> of these modules, and it would be great if it could be incorporated.
>>
>> WDYT?
>
> That would be ideal, but I was concerned that the documentation wasn't
> copyrighted by the FSF. Unless Thien-Thi is interested in contributing
> it, of course.

Yes, I was hoping he would be reading us, let’s see.  ;-)

Thanks,
Ludo’.

Re: [PATCH] Turn on more documentation

[Noah Lavine]

Hello,

>>> The problem is that the auto-generated “Standard Library” section looks
>>> very poor in comparison to the rest of the manual.  So we should really
>>> try hard to write good doc by hands for these, and come up with a handy
>>> structure (instead of one node per module, all under “Standard
>>> Library”).
>>
>> I could do that pretty easily, but I'm afraid that documentation that
>> isn't in the same file as the code would tend to be updated less often
>> than documentation in the same file.
>
> All of our manual except “Standard Library” is maintained this way.  It
> takes discipline to keep up-to-date, but it also leads to a better
> manual IMO.

Okay, I can write documentation this way too. I have a question about
this: what is the distinction between the sections "API Reference" and
"Guile Modules"? I need to figure out where documentation for
different modules goes.

>>> However, I believe Thien-Thi’s Guile 1.4 has good doc for at least some
>>> of these modules, and it would be great if it could be incorporated.
>>>
>>> WDYT?
>>
>> That would be ideal, but I was concerned that the documentation wasn't
>> copyrighted by the FSF. Unless Thien-Thi is interested in contributing
>> it, of course.
>
> Yes, I was hoping he would be reading us, let’s see.  ;-)

After almost a week, I think I'll plan on writing it myself. If
someone else happens to contribute documentation, that'll be great
too.

Thanks,
Noah

Re: [PATCH] Turn on more documentation

[Ludovic Courtès]

Hi Noah!

Noah Lavine <noah.b.lavine@gmail.com> skribis:

> Okay, I can write documentation this way too. I have a question about
> this: what is the distinction between the sections "API Reference" and
> "Guile Modules"? I need to figure out where documentation for
> different modules goes.

From “Organisation of this Manual”:

  *Chapter 6: Guile API Reference*
       This part of the manual documents the Guile API in
       functionality-based groups with the Scheme and C interfaces
       presented side by side.

  *Chapter 7: Guile Modules*
       Describes some important modules, distributed as part of the Guile
       distribution, that extend the functionality provided by the Guile
       Scheme core.

So I think the idea is for core functionality to be in Chapter 6, and
“peripheral things” to be in Chapter 7.  The modules you mention would
fall in the second category, I think.

>>>> However, I believe Thien-Thi’s Guile 1.4 has good doc for at least some
>>>> of these modules, and it would be great if it could be incorporated.
>>>>
>>>> WDYT?
>>>
>>> That would be ideal, but I was concerned that the documentation wasn't
>>> copyrighted by the FSF. Unless Thien-Thi is interested in contributing
>>> it, of course.
>>
>> Yes, I was hoping he would be reading us, let’s see.  ;-)
>
> After almost a week, I think I'll plan on writing it myself.

One week is not a lot.  ;-)

Thanks,
Ludo’.

Re: [PATCH] Turn on more documentation

[Noah Lavine]

Hello,

> From “Organisation of this Manual”:
>
>  *Chapter 6: Guile API Reference*
>       This part of the manual documents the Guile API in
>       functionality-based groups with the Scheme and C interfaces
>       presented side by side.
>
>  *Chapter 7: Guile Modules*
>       Describes some important modules, distributed as part of the Guile
>       distribution, that extend the functionality provided by the Guile
>       Scheme core.
>
> So I think the idea is for core functionality to be in Chapter 6, and
> “peripheral things” to be in Chapter 7.  The modules you mention would
> fall in the second category, I think.

That's certainly enough for this project, but I think in general this
distinction is not very clear. How would someone guess what
functionality is considered "core" and what functionality is an
extension? My first guess would be that things in the (guile) module
are core and everything else is an extension, but that is not the
case. Does this come from an earlier time when the Guile core was
distributed separately from the Guile libraries?

Unless there is going to be some other distinction between core and
extensions, it would seem more natural to me to document everything by
functionality, in the same part of the manual. Some sections would
correspond to modules, because modules are also supposed to group
things by functionality, but that would not be the rule for how the
manual worked. What do you think?

Noah

Re: [PATCH] Turn on more documentation

[Ludovic Courtès]

Hi!

Noah Lavine <noah.b.lavine@gmail.com> skribis:

> Unless there is going to be some other distinction between core and
> extensions, it would seem more natural to me to document everything by
> functionality, in the same part of the manual. Some sections would
> correspond to modules, because modules are also supposed to group
> things by functionality, but that would not be the rule for how the
> manual worked. What do you think?

I tend to agree, but then I’m not sure what a better sectioning would be
in practice.  Any ideas?

Perhaps this could be worked out in ‘master’, so that node names don’t
change for 2.0.x.

Thanks,
Ludo’.

Re: [PATCH] Turn on more documentation

[Noah Lavine]

Hello,

>> Unless there is going to be some other distinction between core and
>> extensions, it would seem more natural to me to document everything by
>> functionality, in the same part of the manual. Some sections would
>> correspond to modules, because modules are also supposed to group
>> things by functionality, but that would not be the rule for how the
>> manual worked. What do you think?
>
> I tend to agree, but then I’m not sure what a better sectioning would be
> in practice.  Any ideas?

I think of our current situation as having three top-level lists of
functionality, in API Reference, Guile Modules, and Standard Library.
How about just merging them into one list?

> Perhaps this could be worked out in ‘master’, so that node names don’t
> change for 2.0.x.

Yes, I certainly agree that we shouldn't change this for 2.0.

Thanks,
Noah

Re: [PATCH] Turn on more documentation

[dsmich]

---- Noah Lavine <noah.b.lavine@gmail.com> wrote: 
> Hello,
> 
> > From “Organisation of this Manual”:
> >
> >  *Chapter 6: Guile API Reference*
> >       This part of the manual documents the Guile API in
> >       functionality-based groups with the Scheme and C interfaces
> >       presented side by side.
> >
> >  *Chapter 7: Guile Modules*
> >       Describes some important modules, distributed as part of the Guile
> >       distribution, that extend the functionality provided by the Guile
> >       Scheme core.
> >
> > So I think the idea is for core functionality to be in Chapter 6, and
> > “peripheral things” to be in Chapter 7.  The modules you mention would
> > fall in the second category, I think.
> 
> That's certainly enough for this project, but I think in general this
> distinction is not very clear. How would someone guess what
> functionality is considered "core" and what functionality is an
> extension? My first guess would be that things in the (guile) module
> are core and everything else is an extension, but that is not the
> case. Does this come from an earlier time when the Guile core was
> distributed separately from the Guile libraries?
> 
> Unless there is going to be some other distinction between core and
> extensions, it would seem more natural to me to document everything by
> functionality, in the same part of the manual. Some sections would
> correspond to modules, because modules are also supposed to group
> things by functionality, but that would not be the rule for how the
> manual worked. What do you think?


I have always had a very difficult time trying to locate the documentation for a module by drilling down through the info menus.  I always seem to go to the wrong section.  I have much better results starting from an index.

-Dale

Re: [PATCH] Turn on more documentation

[Andy Wingo]

Howdy,

On Sun 06 May 2012 12:14, ludo@gnu.org (Ludovic Courtès) writes:

> The problem is that the auto-generated “Standard Library” section looks
> very poor in comparison to the rest of the manual.  So we should really
> try hard to write good doc by hands for these, and come up with a handy
> structure (instead of one node per module, all under “Standard
> Library”).

I agree.  I used to think that auto-generation would work as well or
better than .texi files, but I think time has definitely proved me
wrong, and the GCS right
(http://www.gnu.org/prep/standards/html_node/Doc-Strings-and-Manuals.html).
The right thing to do is to rework the "Standard Library" documentation
into .texi files.

Andy
-- 
http://wingolog.org/

Re: [PATCH] Turn on more documentation

[Andy Wingo]

On Mon 14 May 2012 17:14, Noah Lavine <noah.b.lavine@gmail.com> writes:

> I think of our current situation as having three top-level lists of
> functionality, in API Reference, Guile Modules, and Standard Library.
> How about just merging them into one list?

It would be quite a big list.  Would that be OK?

For me the difference is that nodes of "API reference" describe
functionality that is often not segregated in modules, whereas "Guile
Modules" has nodes that describe modules.

What if we merge "Guile Modules" and "Standard Library" into one
"Standard Library" node, and keep "API Reference" as it is?

Andy
-- 
http://wingolog.org/

Re: [PATCH] Turn on more documentation

[Ludovic Courtès]

Hi,

Andy Wingo <wingo@pobox.com> skribis:

> What if we merge "Guile Modules" and "Standard Library" into one
> "Standard Library" node, and keep "API Reference" as it is?

Sounds good to me.  Perhaps “Standard Library” could have sub-sections,
like “Data Structures”, “Web”, “XML”, “Texinfo”, etc.

Ludo’.

Re: [PATCH] Turn on more documentation

[Noah Lavine]

Hi,

On Tue, May 15, 2012 at 5:25 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Hi,
>
> Andy Wingo <wingo@pobox.com> skribis:
>
>> What if we merge "Guile Modules" and "Standard Library" into one
>> "Standard Library" node, and keep "API Reference" as it is?
>
> Sounds good to me.  Perhaps “Standard Library” could have sub-sections,
> like “Data Structures”, “Web”, “XML”, “Texinfo”, etc.

Yes, that sounds good to me too. However,

On Tue, May 15, 2012 at 4:24 PM, Andy Wingo <wingo@pobox.com> wrote:
> For me the difference is that nodes of "API reference" describe
> functionality that is often not segregated in modules, whereas "Guile
> Modules" has nodes that describe modules.

this distinction makes sense to me, but is not actually what is in
place. For example, "LALR parsing", "Line Oriented and Delimited
Text", "Block reading and writing", and "Local evaluation". How about
having "API Reference" be the core module, and "Guile Modules" have
everything else?

I'm still not sure that's the right distinction though.

Noah