* [PATCH] Turn on more documentation @ 2012-05-03 3:20 Noah Lavine 2012-05-03 22:07 ` Noah Lavine 2012-05-06 10:14 ` Ludovic Courtès 0 siblings, 2 replies; 15+ messages in thread From: Noah Lavine @ 2012-05-03 3:20 UTC (permalink / raw) To: guile-devel [-- 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-03 3:20 [PATCH] Turn on more documentation Noah Lavine @ 2012-05-03 22:07 ` Noah Lavine 2012-05-06 10:14 ` Ludovic Courtès 1 sibling, 0 replies; 15+ messages in thread From: Noah Lavine @ 2012-05-03 22:07 UTC (permalink / raw) To: guile-devel [-- 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-03 3:20 [PATCH] Turn on more documentation Noah Lavine 2012-05-03 22:07 ` Noah Lavine @ 2012-05-06 10:14 ` Ludovic Courtès 2012-05-07 12:30 ` Noah Lavine 2012-05-15 20:19 ` Andy Wingo 1 sibling, 2 replies; 15+ messages in thread From: Ludovic Courtès @ 2012-05-06 10:14 UTC (permalink / raw) To: guile-devel 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’. ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-06 10:14 ` Ludovic Courtès @ 2012-05-07 12:30 ` Noah Lavine 2012-05-07 14:31 ` Ludovic Courtès 2012-05-15 20:19 ` Andy Wingo 1 sibling, 1 reply; 15+ messages in thread From: Noah Lavine @ 2012-05-07 12:30 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-07 12:30 ` Noah Lavine @ 2012-05-07 14:31 ` Ludovic Courtès 2012-05-12 20:56 ` Noah Lavine 0 siblings, 1 reply; 15+ messages in thread From: Ludovic Courtès @ 2012-05-07 14:31 UTC (permalink / raw) To: Noah Lavine; +Cc: guile-devel 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’. ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-07 14:31 ` Ludovic Courtès @ 2012-05-12 20:56 ` Noah Lavine 2012-05-14 12:47 ` Ludovic Courtès 0 siblings, 1 reply; 15+ messages in thread From: Noah Lavine @ 2012-05-12 20:56 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-12 20:56 ` Noah Lavine @ 2012-05-14 12:47 ` Ludovic Courtès 2012-05-14 14:05 ` Noah Lavine 0 siblings, 1 reply; 15+ messages in thread From: Ludovic Courtès @ 2012-05-14 12:47 UTC (permalink / raw) To: Noah Lavine; +Cc: guile-devel 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’. ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-14 12:47 ` Ludovic Courtès @ 2012-05-14 14:05 ` Noah Lavine 2012-05-14 15:00 ` Ludovic Courtès 2012-05-14 21:26 ` dsmich 0 siblings, 2 replies; 15+ messages in thread From: Noah Lavine @ 2012-05-14 14:05 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-14 14:05 ` Noah Lavine @ 2012-05-14 15:00 ` Ludovic Courtès 2012-05-14 15:14 ` Noah Lavine 2012-05-14 21:26 ` dsmich 1 sibling, 1 reply; 15+ messages in thread From: Ludovic Courtès @ 2012-05-14 15:00 UTC (permalink / raw) To: Noah Lavine; +Cc: guile-devel 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’. ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-14 15:00 ` Ludovic Courtès @ 2012-05-14 15:14 ` Noah Lavine 2012-05-15 20:24 ` Andy Wingo 0 siblings, 1 reply; 15+ messages in thread From: Noah Lavine @ 2012-05-14 15:14 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-14 15:14 ` Noah Lavine @ 2012-05-15 20:24 ` Andy Wingo 2012-05-15 21:25 ` Ludovic Courtès 0 siblings, 1 reply; 15+ messages in thread From: Andy Wingo @ 2012-05-15 20:24 UTC (permalink / raw) To: Noah Lavine; +Cc: Ludovic Courtès, guile-devel 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/ ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-15 20:24 ` Andy Wingo @ 2012-05-15 21:25 ` Ludovic Courtès 2012-05-16 0:19 ` Noah Lavine 0 siblings, 1 reply; 15+ messages in thread From: Ludovic Courtès @ 2012-05-15 21:25 UTC (permalink / raw) To: guile-devel 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’. ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-15 21:25 ` Ludovic Courtès @ 2012-05-16 0:19 ` Noah Lavine 0 siblings, 0 replies; 15+ messages in thread From: Noah Lavine @ 2012-05-16 0:19 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-14 14:05 ` Noah Lavine 2012-05-14 15:00 ` Ludovic Courtès @ 2012-05-14 21:26 ` dsmich 1 sibling, 0 replies; 15+ messages in thread From: dsmich @ 2012-05-14 21:26 UTC (permalink / raw) To: Noah Lavine, Ludovic Courtès; +Cc: guile-devel ---- 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Turn on more documentation 2012-05-06 10:14 ` Ludovic Courtès 2012-05-07 12:30 ` Noah Lavine @ 2012-05-15 20:19 ` Andy Wingo 1 sibling, 0 replies; 15+ messages in thread From: Andy Wingo @ 2012-05-15 20:19 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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/ ^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2012-05-16 0:19 UTC | newest] Thread overview: 15+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2012-05-03 3:20 [PATCH] Turn on more documentation Noah Lavine 2012-05-03 22:07 ` Noah Lavine 2012-05-06 10:14 ` Ludovic Courtès 2012-05-07 12:30 ` Noah Lavine 2012-05-07 14:31 ` Ludovic Courtès 2012-05-12 20:56 ` Noah Lavine 2012-05-14 12:47 ` Ludovic Courtès 2012-05-14 14:05 ` Noah Lavine 2012-05-14 15:00 ` Ludovic Courtès 2012-05-14 15:14 ` Noah Lavine 2012-05-15 20:24 ` Andy Wingo 2012-05-15 21:25 ` Ludovic Courtès 2012-05-16 0:19 ` Noah Lavine 2012-05-14 21:26 ` dsmich 2012-05-15 20:19 ` Andy Wingo
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).