integrate guile-lib docs

.gitignore

@@ -119,3 +119,5 @@ INSTALL
 /meta/guile-config
 /lib/locale.h
 /module/ice-9/eval.go.stamp
+/doc/ref/standard-library.texi
+/doc/ref/standard-libraryscmfiles

Makefile.am

@@ -25,8 +25,8 @@
 AUTOMAKE_OPTIONS = 1.10
 
 SUBDIRS = lib meta libguile guile-readline emacs \
-	  srfi doc examples test-suite benchmark-suite am \
+	  srfi examples test-suite benchmark-suite am \
-	  module testsuite
+	  module doc testsuite
 
 include_HEADERS = libguile.h
 

doc/ref/Makefile.am

@@ -1,6 +1,6 @@
 ## Process this file with Automake to create Makefile.in
 ##
-##  	Copyright (C) 1998, 2004, 2006, 2008 Free Software Foundation, Inc.
+##  	Copyright (C) 1998, 2004, 2006, 2008, 2009 Free Software Foundation, Inc.
 ##
 ##   This file is part of GUILE.
 ##
@@ -21,7 +21,7 @@
 
 AUTOMAKE_OPTIONS = gnu
 
-BUILT_SOURCES = lib-version.texi
+BUILT_SOURCES = lib-version.texi standard-library.texi
 
 info_TEXINFOS = guile.texi
 
@@ -128,3 +128,17 @@ EXTRA_DIST += lib-version.texi
 # But when we want to get back to a clean tree, lib-version.texi
 # should be cleaned.
 CLEANFILES = lib-version.texi
+
+# Support for snarfing docs out of Scheme modules.
+snarf_doc=standard-library
+$(snarf_doc)scmfiles:
+	$(preinstguile) -l $(srcdir)/$(snarf_doc).scm \
+	 -c '(for-each (lambda (m) (format #t "~a.scm\n" (string-join (map symbol->string m) "/"))) (map car *modules*))' \
+	 > $@
+depfiles=$(addprefix $(top_srcdir)/module/,$(shell test ! -f $(snarf_doc)scmfiles || cat $(snarf_doc)scmfiles))
+
+$(snarf_doc).texi: $(srcdir)/$(snarf_doc).scm $(snarf_doc)scmfiles $(depfiles)
+	$(top_builddir)/meta/uninstalled-env $(srcdir)/make-texinfo.scm $(srcdir)/$(snarf_doc).scm >$@
+
+CLEANFILES+=$(snarf_doc).texi $(snarf_doc)scmfiles
+EXTRA_DIST+=$(snarf_doc).scm make-texinfo.scm $(snarf_doc).texi $(snarf_doc)scmfiles

doc/ref/guile.texi

@@ -175,6 +175,7 @@ x
 * API Reference::
 
 * Guile Modules::
+* Standard Library::
 
 * GOOPS::
 
@@ -366,6 +367,13 @@ available through both Scheme and C interfaces.
 @include scsh.texi
 @include scheme-debugging.texi
 
+@node Standard Library
+@chapter Standard Library
+
+@lowersections
+@include standard-library.texi
+@raisesections
+
 @include goops.texi
 
 @node Guile Implementation

doc/ref/make-texinfo.scm

@@ -0,0 +1,31 @@
+#!/usr/bin/env guile
+!#
+
+;; make-texinfo.scm -- document a set of scheme modules as texinfo
+;; Copyright (C) 2006,2007,2009  Andy Wingo <wingo at pobox dot com>
+
+;; This program 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.
+;;
+;; This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+(use-modules (texinfo reflection)
+             (texinfo serialize))
+
+(define (main config-scm)
+  (load config-scm)
+  (display
+   (stexi->texi
+    (package-stexi-documentation-for-include
+     (map car *modules*)
+     (map cdr *modules*)))))
+
+(apply main (cdr (command-line)))

doc/ref/standard-library.scm

@@ -0,0 +1,48 @@
+;; The modules to document
+(define *modules*
+  '(((statprof)
+     "Statistical profiler")
+    ((sxml apply-templates)
+     "A more XSLT-like approach to SXML transformations")
+    ((sxml fold)
+     "Fold-based SXML transformation operators")
+    ((sxml simple)
+     "Convenient XML parsing and serializing")
+    ((sxml ssax)
+     "Functional-style XML parsing for Scheme")
+    ((sxml ssax input-parse)
+     "The SSAX tokenizer, optimized for Guile")
+    ((sxml transform)
+     "A higher-order SXML transformation operator, "
+     (code "pre-post-order"))
+    ((sxml xpath)
+     "XPath for SXML")
+    ((texinfo)
+     "Parse texinfo files or fragments into " (code "stexi") ", a "
+     "scheme representation")
+    ((texinfo docbook)
+     "Transform a subset of docbook into " (code "stexi"))
+    ((texinfo html)
+     "Transform " (code "stexi") " into HTML")
+    ((texinfo indexing)
+     "Extract an index from a piece of " (code "stexi"))
+    ((texinfo string-utils)
+     "String utility functions used by the texinfo processor")
+    ((texinfo plain-text)
+     "Render " (code "stexi") " as plain text")
+    ((texinfo serialize)
+     "Render " (code "stexi") " as texinfo")
+    ((texinfo reflection)
+     "Enable texinfo across Guile's help system")))
+
+(define *module-sources*
+  '(((sxml ssax) . "http://ssax.sourceforge.net/")
+    ((sxml xpath) . "http://ssax.sourceforge.net/")
+    ((sxml transform) . "http://ssax.sourceforge.net/")
+    ((sxml apply-templates) . "http://ssax.sourceforge.net/")
+    ((sxml ssax input-parse) . "http://ssax.sourceforge.net/")
+    ((htmlprag) . "http://neilvandyke.org/htmlprag/")))
+
+(define *scripts* '())
+
+;; arch-tag: e493ad42-ad58-451c-a2d6-b17ba6c1d1d0

module/texinfo/reflection.scm

@@ -47,7 +47,8 @@
             package-stexi-standard-menu
             package-stexi-extended-menu
             package-stexi-standard-prologue
-            package-stexi-documentation))
+            package-stexi-documentation
+            package-stexi-documentation-for-include))
 
 ;; List for sorting the definitions in a module
 (define defs
@@ -525,4 +526,41 @@ useful to define a @code{#:docs-resolver} argument."
                   scripts)
     ,@epilogue))
 
+(define* (package-stexi-documentation-for-include modules module-descriptions
+                                                  #:key
+                                                  (module-stexi-documentation-args '()))
+  "Create stexi documentation for a @dfn{package}, where a
+package is a set of modules that is released together.
+
+@var{modules} is expected to be a list of module names, where a
+module name is a list of symbols. Returns an stexinfo fragment.
+
+Unlike @code{package-stexi-documentation}, this function simply produces
+a menu and the module documentations instead of producing a full texinfo
+document. This can be useful if you write part of your manual by hand,
+and just use @code{@@include} to pull in the automatically generated
+parts.
+
+@var{module-stexi-documentation-args} is an optional argument that, if
+given, will be added to the argument list when
+@code{module-texi-documentation} is called. For example, it might be
+useful to define a @code{#:docs-resolver} argument."
+  (define (make-entry node description)
+    `("* " ,node "::"
+      ,(make-string (max (- 21 (string-length node)) 2) #\space)
+      ,@description "\n"))
+  `(*fragment*
+    (menu
+     ,@(append-map (lambda (modname desc)
+                     (make-entry (module-name->node-name modname)
+                                 desc))
+                   modules
+                   module-descriptions))
+    ,@(append-map (lambda (modname)
+                    (stexi->chapter
+                     (apply module-stexi-documentation 
+                            modname
+                            module-stexi-documentation-args)))
+                  modules)))
+
 ;;; arch-tag: bbe2bc03-e16d-4a9e-87b9-55225dc9836c