From c55cb58ac15b61eac574d8adafb08bc32f2bc8c1 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Fri, 18 Dec 2009 13:31:02 +0100 Subject: [PATCH] integrate guile-lib docs --- .gitignore | 2 ++ Makefile.am | 4 +-- doc/ref/Makefile.am | 18 +++++++++++-- doc/ref/guile.texi | 8 ++++++ doc/ref/make-texinfo.scm | 31 ++++++++++++++++++++++ doc/ref/standard-library.scm | 48 +++++++++++++++++++++++++++++++++++ module/texinfo/reflection.scm | 40 ++++++++++++++++++++++++++++- 7 files changed, 146 insertions(+), 5 deletions(-) create mode 100755 doc/ref/make-texinfo.scm create mode 100644 doc/ref/standard-library.scm diff --git a/.gitignore b/.gitignore index 3db738233..c09924b02 100644 --- a/.gitignore +++ b/.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 diff --git a/Makefile.am b/Makefile.am index c51a61b61..20f03826a 100644 --- a/Makefile.am +++ b/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 \ - module testsuite + srfi examples test-suite benchmark-suite am \ + module doc testsuite include_HEADERS = libguile.h diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index d58b3705a..904124fa3 100644 --- a/doc/ref/Makefile.am +++ b/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 diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 332be361b..a8c51df0f 100644 --- a/doc/ref/guile.texi +++ b/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 diff --git a/doc/ref/make-texinfo.scm b/doc/ref/make-texinfo.scm new file mode 100755 index 000000000..ec59742a6 --- /dev/null +++ b/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 + +;; 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 . + +(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))) diff --git a/doc/ref/standard-library.scm b/doc/ref/standard-library.scm new file mode 100644 index 000000000..7fd17b51f --- /dev/null +++ b/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 diff --git a/module/texinfo/reflection.scm b/module/texinfo/reflection.scm index bda1830ea..d88bd37c8 100644 --- a/module/texinfo/reflection.scm +++ b/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 -- 2.20.1