[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.7-31-g58c4a3
|
From: |
Andy Wingo |
|
Subject: |
[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.7-31-g58c4a39 |
|
Date: |
Wed, 16 Jan 2013 09:04:09 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".
http://git.savannah.gnu.org/cgit/guile.git/commit/?id=58c4a39d9824d021994754181a369d1daa30f588
The branch, stable-2.0 has been updated
via 58c4a39d9824d021994754181a369d1daa30f588 (commit)
from 5156f4d7454b21ae287c1707e8fa12d2c67ba2b0 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 58c4a39d9824d021994754181a369d1daa30f588
Author: Andy Wingo <address@hidden>
Date: Wed Jan 16 10:03:44 2013 +0100
an end to the generated-documentation experiment
* doc/ref/statprof.texi:
* doc/ref/sxml.texi:
* doc/ref/texinfo.texi: New files, containing the documentation that was
previously generated from source and rendered into
standard-library.texi. The documentation is still horrible, but at
least now it is user-editable.
-----------------------------------------------------------------------
Summary of changes:
doc/ref/Makefile.am | 36 +--
doc/ref/guile.texi | 15 +-
doc/ref/make-texinfo.scm | 28 --
doc/ref/standard-library.am | 2 -
doc/ref/standard-library.scm | 48 ---
doc/ref/statprof.texi | 283 ++++++++++++++++
doc/ref/sxml.texi | 733 ++++++++++++++++++++++++++++++++++++++++++
doc/ref/texinfo.texi | 588 +++++++++++++++++++++++++++++++++
8 files changed, 1615 insertions(+), 118 deletions(-)
delete mode 100644 doc/ref/make-texinfo.scm
delete mode 100644 doc/ref/standard-library.am
delete mode 100644 doc/ref/standard-library.scm
create mode 100644 doc/ref/statprof.texi
create mode 100644 doc/ref/sxml.texi
create mode 100644 doc/ref/texinfo.texi
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 201ab6b..260bb14 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -1,7 +1,7 @@
## Process this file with Automake to create Makefile.in
##
## Copyright (C) 1998, 2004, 2006, 2008, 2009, 2010,
-## 2011 Free Software Foundation, Inc.
+## 2011, 2013 Free Software Foundation, Inc.
##
## This file is part of GUILE.
##
@@ -22,8 +22,6 @@
AUTOMAKE_OPTIONS = gnu
-BUILT_SOURCES = standard-library.texi
-
info_TEXINFOS = guile.texi
guile_TEXINFOS = preface.texi \
@@ -90,6 +88,9 @@ guile_TEXINFOS = preface.texi \
libguile-extensions.texi \
api-init.texi \
mod-getopt-long.texi \
+ statprof.texi \
+ sxml.texi \
+ texinfo.texi \
goops.texi \
goops-tutorial.texi \
guile-invoke.texi \
@@ -123,35 +124,6 @@ autoconf-macros.texi: $(top_srcdir)/meta/guile.m4
MAINTAINERCLEANFILES = autoconf-macros.texi
-# Support for snarfing docs out of Scheme modules.
-snarf_doc = standard-library
-
-$(snarf_doc).am: $(snarf_doc).scm
- GUILE_AUTO_COMPILE=0 ;
\
- variable="`echo $(snarf_doc) | tr - _`_scm_files" ;
\
- "$(top_builddir_absolute)/meta/guile" -l "$(srcdir)/$(snarf_doc).scm"
\
- -c "
\
- (format #t \"# Automatically generated, do not edit.~%\")
\
- (format #t \"$$variable = \")
\
- (for-each (lambda (m)
\
- (format #t \"$$""(top_srcdir)/module/~a.scm \"
\
- (string-join (map symbol->string m) \"/\")))
\
- (map car *modules*))" > "address@hidden"
- mv "address@hidden" "$@"
-
-# The following line leads to the definition of $(standard_library_scm_files).
-include standard-library.am
-
-$(snarf_doc).texi: $(standard_library_scm_files)
- GUILE_AUTO_COMPILE=0 \
- "$(top_builddir_absolute)/meta/guile" "$(srcdir)/make-texinfo.scm"
\
- "$(abs_srcdir)/$(snarf_doc).scm" > "address@hidden"
- mv "address@hidden" "$@"
-
-DISTCLEANFILES = $(snarf_doc).texi
-EXTRA_DIST += $(snarf_doc).scm make-texinfo.scm $(snarf_doc).texi
$(snarf_doc).am
-
-
www-commit: html
cd guile.html; \
cvs -d :ext:cvs.sv.gnu.org:/web/guile \
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index a1b3fe6..a6e3e7d 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -14,7 +14,7 @@
This manual documents Guile version @value{VERSION}.
Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009,
-2010, 2011, 2012 Free Software Foundation.
+2010, 2011, 2012, 2013 Free Software Foundation.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -177,7 +177,6 @@ x
* API Reference::
* Guile Modules::
-* Standard Library::
* GOOPS::
@@ -371,6 +370,9 @@ available through both Scheme and C interfaces.
* sxml-match:: Pattern matching of SXML.
* The Scheme shell (scsh):: Using scsh interfaces in Guile.
* Curried Definitions:: Extended @code{define} syntax.
+* Statprof:: An easy-to-use statistical profiler.
+* SXML:: Parsing, transforming, and serializing XML.
+* Texinfo:: Munging documents written in Texinfo.
@end menu
@include slib.texi
@@ -390,12 +392,9 @@ available through both Scheme and C interfaces.
@include scsh.texi
@include curried.texi
address@hidden Standard Library
address@hidden Standard Library
-
address@hidden
address@hidden standard-library.texi
address@hidden
address@hidden statprof.texi
address@hidden sxml.texi
address@hidden texinfo.texi
@include goops.texi
diff --git a/doc/ref/make-texinfo.scm b/doc/ref/make-texinfo.scm
deleted file mode 100644
index c967bc1..0000000
--- a/doc/ref/make-texinfo.scm
+++ /dev/null
@@ -1,28 +0,0 @@
-;; 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)))
diff --git a/doc/ref/standard-library.am b/doc/ref/standard-library.am
deleted file mode 100644
index 27246f4..0000000
--- a/doc/ref/standard-library.am
+++ /dev/null
@@ -1,2 +0,0 @@
-# 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
diff --git a/doc/ref/standard-library.scm b/doc/ref/standard-library.scm
deleted file mode 100644
index 7fd17b5..0000000
--- a/doc/ref/standard-library.scm
+++ /dev/null
@@ -1,48 +0,0 @@
-;; 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/doc/ref/statprof.texi b/doc/ref/statprof.texi
new file mode 100644
index 0000000..c481ac7
--- /dev/null
+++ b/doc/ref/statprof.texi
@@ -0,0 +1,283 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 2013 Free Software Foundation, Inc.
address@hidden See the file guile.texi for copying conditions.
+
address@hidden Statprof
address@hidden Statprof
+
address@hidden(statprof)} is a fairly simple statistical profiler for Guile.
+
+A simple use of statprof would look like this:
+
address@hidden
+(statprof-reset 0 50000 #t)
+(statprof-start)
+(do-something)
+(statprof-stop)
+(statprof-display)
address@hidden example
+
+This would reset statprof, clearing all accumulated statistics, then
+start profiling, run some code, stop profiling, and finally display a
+gprof flat-style table of statistics which will look something like
+this:
+
address@hidden
+ % cumulative self self total
+ time seconds seconds calls ms/call ms/call name
+ 35.29 0.23 0.23 2002 0.11 0.11 -
+ 23.53 0.15 0.15 2001 0.08 0.08 positive?
+ 23.53 0.15 0.15 2000 0.08 0.08 +
+ 11.76 0.23 0.08 2000 0.04 0.11 do-nothing
+ 5.88 0.64 0.04 2001 0.02 0.32 loop
+ 0.00 0.15 0.00 1 0.00 150.59 do-something
+ ...
address@hidden example
+
+All of the numerical data with the exception of the calls column is
+statistically approximate. In the following column descriptions, and in
+all of statprof, "time" refers to execution time (both user and system),
+not wall clock time.
+
address@hidden @asis
address@hidden % time
+The percent of the time spent inside the procedure itself (not counting
+children).
+
address@hidden cumulative seconds
+The total number of seconds spent in the procedure, including children.
+
address@hidden self seconds
+The total number of seconds spent in the procedure itself (not counting
+children).
+
address@hidden calls
+The total number of times the procedure was called.
+
address@hidden self ms/call
+The average time taken by the procedure itself on each call, in ms.
+
address@hidden total ms/call
+The average time taken by each call to the procedure, including time
+spent in child functions.
+
address@hidden name
+The name of the procedure.
+
address@hidden table
+
+The profiler uses @code{eq?} and the procedure object itself to identify
+the procedures, so it won't confuse different procedures with the same
+name. They will show up as two different rows in the output.
+
+Right now the profiler is quite simplistic. I cannot provide call-graphs
+or other higher level information. What you see in the table is pretty
+much all there is. Patches are welcome :-)
+
address@hidden Implementation notes
+The profiler works by setting the unix profiling signal
address@hidden to go off after the interval you define in the call
+to @code{statprof-reset}. When the signal fires, a sampling routine is
+run which looks at the current procedure that's executing, and then
+crawls up the stack, and for each procedure encountered, increments that
+procedure's sample count. Note that if a procedure is encountered
+multiple times on a given stack, it is only counted once. After the
+sampling is complete, the profiler resets profiling timer to fire again
+after the appropriate interval.
+
+Meanwhile, the profiler keeps track, via @code{get-internal-run-time},
+how much CPU time (system and user -- which is also what
address@hidden tracks), has elapsed while code has been executing
+within a statprof-start/stop block.
+
+The profiler also tries to avoid counting or timing its own code as much
+as possible.
+
address@hidden Usage
address@hidden address@hidden statprof-active?
+Returns @code{#t} if @code{statprof-start} has been called more times
+than @code{statprof-stop}, @code{#f} otherwise.
+
address@hidden defun
+
address@hidden address@hidden statprof-start
+Start the address@hidden
+
address@hidden defun
+
address@hidden address@hidden statprof-stop
+Stop the address@hidden
+
address@hidden defun
+
address@hidden address@hidden statprof-reset sample-seconds sample-microseconds
count-calls? [full-stacks?]
+Reset the statprof sampler interval to @var{sample-seconds} and
address@hidden If @var{count-calls?} is true, arrange to
+instrument procedure calls as well as collecting statistical profiling
+data. If @var{full-stacks?} is true, collect all sampled stacks into a
+list for later analysis.
+
+Enables traps and debugging as necessary.
+
address@hidden defun
+
address@hidden address@hidden statprof-accumulated-time
+Returns the time accumulated during the last statprof address@hidden
+
address@hidden defun
+
address@hidden address@hidden statprof-sample-count
+Returns the number of samples taken during the last statprof address@hidden
+
address@hidden defun
+
address@hidden address@hidden statprof-fold-call-data proc init
+Fold @var{proc} over the call-data accumulated by statprof. Cannot be
+called while statprof is active. @var{proc} should take two arguments,
address@hidden(@var{call-data} @var{prior-result})}.
+
+Note that a given proc-name may appear multiple times, but if it does,
+it represents different functions with the same name.
+
address@hidden defun
+
address@hidden address@hidden statprof-proc-call-data proc
+Returns the call-data associated with @var{proc}, or @code{#f} if none
+is available.
+
address@hidden defun
+
address@hidden address@hidden statprof-call-data-name cd
address@hidden defun
+
address@hidden address@hidden statprof-call-data-calls cd
address@hidden defun
+
address@hidden address@hidden statprof-call-data-cum-samples cd
address@hidden defun
+
address@hidden address@hidden statprof-call-data-self-samples cd
address@hidden defun
+
address@hidden statprof-call-data->address@hidden statprof-call-data->stats
call-data
+Returns an object of type @code{statprof-stats}.
+
address@hidden defun
+
address@hidden address@hidden statprof-stats-proc-name stats
address@hidden defun
+
address@hidden address@hidden statprof-stats-%-time-in-proc stats
address@hidden defun
+
address@hidden address@hidden statprof-stats-cum-secs-in-proc stats
address@hidden defun
+
address@hidden address@hidden statprof-stats-self-secs-in-proc stats
address@hidden defun
+
address@hidden address@hidden statprof-stats-calls stats
address@hidden defun
+
address@hidden address@hidden statprof-stats-self-secs-per-call stats
address@hidden defun
+
address@hidden address@hidden statprof-stats-cum-secs-per-call stats
address@hidden defun
+
address@hidden address@hidden statprof-display . _
+Displays a gprof-like summary of the statistics collected. Unless an
+optional @var{port} argument is passed, uses the current output port.
+
address@hidden defun
+
address@hidden address@hidden statprof-display-anomolies
+A sanity check that attempts to detect anomolies in statprof's
address@hidden
+
address@hidden defun
+
address@hidden address@hidden statprof-fetch-stacks
+Returns a list of stacks, as they were captured since the last call to
address@hidden
+
+Note that stacks are only collected if the @var{full-stacks?} argument
+to @code{statprof-reset} is true.
+
address@hidden defun
+
address@hidden address@hidden statprof-fetch-call-tree
address@hidden
+Return a call tree for the previous statprof run.
+
+The return value is a list of nodes, each of which is of the type:
+@@code
+ node ::= (@@address@hidden@} @@address@hidden@} . @@address@hidden@})
+@@end code
address@hidden verbatim
+
address@hidden defun
+
address@hidden address@hidden statprof thunk [#:loop] [#:hz] [#:count-calls?]
[#:full-stacks?]
+Profiles the execution of @var{thunk}.
+
+The stack will be sampled @var{hz} times per second, and the thunk
+itself will be called @var{loop} times.
+
+If @var{count-calls?} is true, all procedure calls will be recorded.
+This operation is somewhat expensive.
+
+If @var{full-stacks?} is true, at each sample, statprof will store away
+the whole call tree, for later analysis. Use
address@hidden or @code{statprof-fetch-call-tree} to
+retrieve the last-stored stacks.
+
address@hidden defun
+
address@hidden address@hidden with-statprof args
+Profiles the expressions in its body.
+
+Keyword arguments:
+
address@hidden @code
address@hidden #:loop
+Execute the body @var{loop} number of times, or @code{#f} for no looping
+
+default: @code{#f}
+
address@hidden #:hz
+Sampling rate
+
+default: @code{20}
+
address@hidden #:count-calls?
+Whether to instrument each function call (expensive)
+
+default: @code{#f}
+
address@hidden #:full-stacks?
+Whether to collect away all sampled stacks into a list
+
+default: @code{#f}
+
address@hidden table
+
address@hidden defspec
+
address@hidden address@hidden gcprof thunk [#:loop] [#:full-stacks?]
+Do an allocation profile of the execution of @var{thunk}.
+
+The stack will be sampled soon after every garbage collection, yielding
+an approximate idea of what is causing allocation in your program.
+
+Since GC does not occur very frequently, you may need to use the
address@hidden parameter, to cause @var{thunk} to be called @var{loop}
+times.
+
+If @var{full-stacks?} is true, at each sample, statprof will store away
+the whole call tree, for later analysis. Use
address@hidden or @code{statprof-fetch-call-tree} to
+retrieve the last-stored stacks.
+
address@hidden defun
diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi
new file mode 100644
index 0000000..3ce6062
--- /dev/null
+++ b/doc/ref/sxml.texi
@@ -0,0 +1,733 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 2013 Free Software Foundation, Inc.
address@hidden See the file guile.texi for copying conditions.
+
address@hidden SXML
address@hidden SXML
+
address@hidden
+* 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
address@hidden menu
+
address@hidden sxml apply-templates
address@hidden (sxml apply-templates)
address@hidden Overview
+Pre-order traversal of a tree and creation of a new tree:
+
address@hidden
+ apply-templates:: tree x <templates> -> <new-tree>
address@hidden smallexample
+
+where
+
address@hidden
+ <templates> ::= (<template> ...)
+ <template> ::= (<node-test> <node-test> ... <node-test> . <handler>)
+ <node-test> ::= an argument to node-typeof? above
+ <handler> ::= <tree> -> <new-tree>
address@hidden smallexample
+
+This procedure does a @emph{normal}, pre-order traversal of an SXML
+tree. It walks the tree, checking at each node against the list of
+matching templates.
+
+If the match is found (which must be unique, i.e., unambiguous), the
+corresponding handler is invoked and given the current node as an
+argument. The result from the handler, which must be a @code{<tree>},
+takes place of the current node in the resulting tree. The name of the
+function is not accidental: it resembles rather closely an
address@hidden function of XSLT.
+
address@hidden Usage
address@hidden apply-templates address@hidden apply-templates tree templates
address@hidden defun
+
address@hidden sxml fold
address@hidden (sxml fold)
address@hidden Overview
address@hidden(sxml fold)} defines a number of variants of the @dfn{fold}
+algorithm for use in transforming SXML trees. Additionally it defines
+the layout operator, @code{fold-layout}, which might be described as a
+context-passing variant of SSAX's @code{pre-post-order}.
+
address@hidden Usage
address@hidden fold address@hidden foldt fup fhere tree
+The standard multithreaded tree fold.
+
address@hidden is of type [a] -> a. @var{fhere} is of type object -> a.
+
address@hidden defun
+
address@hidden fold address@hidden foldts fdown fup fhere seed tree
+The single-threaded tree fold originally defined in SSAX. @xref{sxml
+ssax,,(sxml ssax)}, for more information.
+
address@hidden defun
+
address@hidden fold address@hidden foldts* fdown fup fhere seed tree
+A variant of @ref{sxml fold foldts,,foldts} that allows pre-order tree
+rewrites. Originally defined in Andy Wingo's 2007 paper,
address@hidden of fold to XML transformation}.
+
address@hidden defun
+
address@hidden fold address@hidden fold-values proc list . seeds
+A variant of @ref{SRFI-1 Fold and Map,fold} that allows multi-valued
+seeds. Note that the order of the arguments differs from that of
address@hidden
+
address@hidden defun
+
address@hidden fold address@hidden foldts*-values fdown fup fhere tree . seeds
+A variant of @ref{sxml fold foldts*,,foldts*} that allows multi-valued
+seeds. Originally defined in Andy Wingo's 2007 paper, @emph{Applications
+of fold to XML transformation}.
+
address@hidden defun
+
address@hidden fold address@hidden fold-layout tree bindings params layout
stylesheet
+A traversal combinator in the spirit of SSAX's @ref{sxml transform
+pre-post-order,,pre-post-order}.
+
address@hidden was originally presented in Andy Wingo's 2007 paper,
address@hidden of fold to XML transformation}.
+
address@hidden
+bindings := (<binding>...)
+binding := (<tag> <bandler-pair>...)
+ | (*default* . <post-handler>)
+ | (*text* . <text-handler>)
+tag := <symbol>
+handler-pair := (pre-layout . <pre-layout-handler>)
+ | (post . <post-handler>)
+ | (bindings . <bindings>)
+ | (pre . <pre-handler>)
+ | (macro . <macro-handler>)
address@hidden example
+
address@hidden @var
address@hidden pre-layout-handler
+A function of three arguments:
+
address@hidden @var
address@hidden kids
+the kids of the current node, before traversal
+
address@hidden params
+the params of the current node
+
address@hidden layout
+the layout coming into this node
+
address@hidden table
+
address@hidden is expected to use this information to return a
+layout to pass to the kids. The default implementation returns the
+layout given in the arguments.
+
address@hidden post-handler
+A function of five arguments:
+
address@hidden @var
address@hidden tag
+the current tag being processed
+
address@hidden params
+the params of the current node
+
address@hidden layout
+the layout coming into the current node, before any kids were processed
+
address@hidden klayout
+the layout after processing all of the children
+
address@hidden kids
+the already-processed child nodes
+
address@hidden table
+
address@hidden should return two values, the layout to pass to the
+next node and the final tree.
+
address@hidden text-handler
address@hidden is a function of three arguments:
+
address@hidden @var
address@hidden text
+the string
+
address@hidden params
+the current params
+
address@hidden layout
+the current layout
+
address@hidden table
+
address@hidden should return two values, the layout to pass to the
+next node and the value to which the string should transform.
+
address@hidden table
+
address@hidden defun
+
address@hidden sxml simple
address@hidden (sxml simple)
address@hidden Overview
+A simple interface to XML parsing and serialization.
+
address@hidden Usage
address@hidden simple xml->address@hidden xml->sxml [port]
+Use SSAX to parse an XML document into SXML. Takes one optional
+argument, @var{port}, which defaults to the current input port.
+
address@hidden defun
+
address@hidden simple sxml->address@hidden sxml->xml tree [port]
+Serialize the sxml tree @var{tree} as XML. The output will be written to
+the current output port, unless the optional argument @var{port} is
+present.
+
address@hidden defun
+
address@hidden simple sxml->address@hidden sxml->string sxml
+Detag an sxml tree @var{sxml} into a string. Does not perform any
+formatting.
+
address@hidden defun
+
address@hidden sxml ssax
address@hidden (sxml ssax)
address@hidden Overview
address@hidden Functional XML parsing framework
address@hidden SAX/DOM and SXML parsers with support for XML Namespaces and
validation
+This is a package of low-to-high level lexing and parsing procedures
+that can be combined to yield a SAX, a DOM, a validating parser, or a
+parser intended for a particular document type. The procedures in the
+package can be used separately to tokenize or parse various pieces of
+XML documents. The package supports XML Namespaces, internal and
+external parsed entities, user-controlled handling of whitespace, and
+validation. This module therefore is intended to be a framework, a set
+of "Lego blocks" you can use to build a parser following any discipline
+and performing validation to any degree. As an example of the parser
+construction, this file includes a semi-validating SXML parser.
+
+The present XML framework has a "sequential" feel of SAX yet a
+"functional style" of DOM. Like a SAX parser, the framework scans the
+document only once and permits incremental processing. An application
+that handles document elements in order can run as efficiently as
+possible. @emph{Unlike} a SAX parser, the framework does not require an
+application register stateful callbacks and surrender control to the
+parser. Rather, it is the application that can drive the framework --
+calling its functions to get the current lexical or syntax element.
+These functions do not maintain or mutate any state save the input port.
+Therefore, the framework permits parsing of XML in a pure functional
+style, with the input port being a monad (or a linear, read-once
+parameter).
+
+Besides the @var{port}, there is another monad -- @var{seed}. Most of
+the middle- and high-level parsers are single-threaded through the
address@hidden The functions of this framework do not process or affect the
address@hidden in any way: they simply pass it around as an instance of an
+opaque datatype. User functions, on the other hand, can use the seed to
+maintain user's state, to accumulate parsing results, etc. A user can
+freely mix his own functions with those of the framework. On the other
+hand, the user may wish to instantiate a high-level parser:
address@hidden:make-elem-parser} or @code{SSAX:make-parser}. In the latter
+case, the user must provide functions of specific signatures, which are
+called at predictable moments during the parsing: to handle character
+data, element data, or processing instructions (PI). The functions are
+always given the @var{seed}, among other parameters, and must return the
+new @var{seed}.
+
+From a functional point of view, XML parsing is a combined
+pre-post-order traversal of a "tree" that is the XML document itself.
+This down-and-up traversal tells the user about an element when its
+start tag is encountered. The user is notified about the element once
+more, after all element's children have been handled. The process of XML
+parsing therefore is a fold over the raw XML document. Unlike a fold
+over trees defined in [1], the parser is necessarily single-threaded --
+obviously as elements in a text XML document are laid down sequentially.
+The parser therefore is a tree fold that has been transformed to accept
+an accumulating parameter [1,2].
+
+Formally, the denotational semantics of the parser can be expressed as
+
address@hidden
+ parser:: (Start-tag -> Seed -> Seed) ->
+ (Start-tag -> Seed -> Seed -> Seed) ->
+ (Char-Data -> Seed -> Seed) ->
+ XML-text-fragment -> Seed -> Seed
+ parser fdown fup fchar "<elem attrs> content </elem>" seed
+ = fup "<elem attrs>" seed
+ (parser fdown fup fchar "content" (fdown "<elem attrs>" seed))
+
+ parser fdown fup fchar "char-data content" seed
+ = parser fdown fup fchar "content" (fchar "char-data" seed)
+
+ parser fdown fup fchar "elem-content content" seed
+ = parser fdown fup fchar "content" (
+ parser fdown fup fchar "elem-content" seed)
address@hidden smallexample
+
+Compare the last two equations with the left fold
+
address@hidden
+ fold-left kons elem:list seed = fold-left kons list (kons elem seed)
address@hidden smallexample
+
+The real parser created by @code{SSAX:make-parser} is slightly more
+complicated, to account for processing instructions, entity references,
+namespaces, processing of document type declaration, etc.
+
+The XML standard document referred to in this module
address@hidden://www.w3.org/TR/1998/REC-xml-19980210.html}
+
+The present file also defines a procedure that parses the text of an XML
+document or of a separate element into SXML, an S-expression-based model
+of an XML Information Set. SXML is also an Abstract Syntax Tree of an
+XML document. SXML is similar but not identical to DOM; SXML is
+particularly suitable for Scheme-based XML/HTML authoring, SXPath
+queries, and tree transformations. See SXML.html for more details. SXML
+is a term implementation of evaluation of the XML document [3]. The
+other implementation is context-passing.
+
+The present frameworks fully supports the XML Namespaces
+Recommendation:@uref{http://www.w3.org/TR/REC-xml-names/} Other links:
+
address@hidden @asis
address@hidden [1]
+Jeremy Gibbons, Geraint Jones, "The Under-appreciated Unfold," Proc.
+ICFP'98, 1998, pp. 273-279.
+
address@hidden [2]
+Richard S. Bird, The promotion and accumulation strategies in
+transformational programming, ACM Trans. Progr. Lang. Systems,
+6(4):487-504, October 1984.
+
address@hidden [3]
+Ralf Hinze, "Deriving Backtracking Monad Transformers," Functional
+Pearl. Proc ICFP'00, pp. 186-197.
+
address@hidden table
+
address@hidden Usage
address@hidden ssax address@hidden current-ssax-error-port
address@hidden defun
+
address@hidden ssax address@hidden with-ssax-error-to-port port thunk
address@hidden defun
+
address@hidden ssax address@hidden xml-token? _
address@hidden
+ -- Scheme Procedure: pair? x
+ Return `#t' if X is a pair; otherwise return `#f'.
+
+
address@hidden verbatim
+
address@hidden defun
+
address@hidden ssax address@hidden xml-token-kind token
address@hidden defspec
+
address@hidden ssax address@hidden xml-token-head token
address@hidden defspec
+
address@hidden ssax address@hidden make-empty-attlist
address@hidden defun
+
address@hidden ssax address@hidden attlist-add attlist name-value
address@hidden defun
+
address@hidden ssax address@hidden attlist-null? _
address@hidden
+ -- Scheme Procedure: null? x
+ Return `#t' iff X is the empty list, else `#f'.
+
+
address@hidden verbatim
+
address@hidden defun
+
address@hidden ssax address@hidden attlist-remove-top attlist
address@hidden defun
+
address@hidden ssax attlist->address@hidden attlist->alist attlist
address@hidden defun
+
address@hidden ssax address@hidden attlist-fold kons knil lis1
address@hidden defun
+
address@hidden ssax address@hidden define-parsed-entity! entity str
+Define a new parsed entity. @var{entity} should be a symbol.
+
+Instances of &@var{entity}; in XML text will be replaced with the string
address@hidden, which will then be parsed.
+
address@hidden defun
+
address@hidden ssax address@hidden reset-parsed-entity-definitions!
+Restore the set of parsed entity definitions to its initial state.
+
address@hidden defun
+
address@hidden ssax ssax:uri-string->address@hidden ssax:uri-string->symbol
uri-str
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:skip-internal-dtd port
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-pi-body-as-string port
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:reverse-collect-str-drop-ws
fragments
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-markup-token port
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-cdata-body port str-handler
seed
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-char-ref port
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-attributes port entities
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:complete-start-tag tag-head port
elems entities namespaces
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-external-id port
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:read-char-data port expect-eof?
str-handler seed
address@hidden defun
+
address@hidden ssax ssax:xml->address@hidden ssax:xml->sxml port
namespace-prefix-assig
address@hidden defun
+
address@hidden ssax ssax:address@hidden ssax:make-parser . kw-val-pairs
address@hidden defspec
+
address@hidden ssax ssax:address@hidden ssax:make-pi-parser orig-handlers
address@hidden defspec
+
address@hidden ssax ssax:address@hidden ssax:make-elem-parser my-new-level-seed
my-finish-element my-char-data-handler my-pi-handlers
address@hidden defspec
+
address@hidden sxml ssax input-parse
address@hidden (sxml ssax input-parse)
address@hidden Overview
+A simple lexer.
+
+The procedures in this module surprisingly often suffice to parse an
+input stream. They either skip, or build and return tokens, according to
+inclusion or delimiting semantics. The list of characters to expect,
+include, or to break at may vary from one invocation of a function to
+another. This allows the functions to easily parse even
+context-sensitive languages.
+
+EOF is generally frowned on, and thrown up upon if encountered.
+Exceptions are mentioned specifically. The list of expected characters
+(characters to skip until, or break-characters) may include an EOF
+"character", which is to be coded as the symbol, @code{*eof*}.
+
+The input stream to parse is specified as a @dfn{port}, which is usually
+the last (and optional) argument. It defaults to the current input port
+if omitted.
+
+If the parser encounters an error, it will throw an exception to the key
address@hidden The arguments will be of the form @code{(@var{port}
address@hidden @var{specialising-msg}*)}.
+
+The first argument is a port, which typically points to the offending
+character or its neighborhood. You can then use @code{port-column} and
address@hidden to query the current position. @var{message} is the
+description of the error. Other arguments supply more details about the
+problem.
+
address@hidden Usage
address@hidden ssax input-parse address@hidden peek-next-char [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden assert-curr-char expected-chars
comment [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden skip-until arg [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden skip-while skip-chars [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden next-token prefix-skipped-chars
break-chars [comment] [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden next-token-of incl-list/pred
[port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden read-text-line [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden read-string n [port]
address@hidden defun
+
address@hidden ssax input-parse address@hidden find-string-from-port? _ _ . _
+Looks for @var{str} in @var{<input-port>}, optionally within the first
address@hidden characters.
+
address@hidden defun
+
address@hidden sxml transform
address@hidden (sxml transform)
address@hidden Overview
address@hidden SXML expression tree transformers
address@hidden Pre-Post-order traversal of a tree and creation of a new tree
address@hidden
+pre-post-order:: <tree> x <bindings> -> <new-tree>
address@hidden smallexample
+
+where
+
address@hidden
+ <bindings> ::= (<binding> ...)
+ <binding> ::= (<trigger-symbol> *preorder* . <handler>) |
+ (<trigger-symbol> *macro* . <handler>) |
+ (<trigger-symbol> <new-bindings> . <handler>) |
+ (<trigger-symbol> . <handler>)
+ <trigger-symbol> ::= XMLname | *text* | *default*
+ <handler> :: <trigger-symbol> x [<tree>] -> <new-tree>
address@hidden smallexample
+
+The pre-post-order function visits the nodes and nodelists
+pre-post-order (depth-first). For each @code{<Node>} of the form
address@hidden(@var{name} <Node> ...)}, it looks up an association with the
+given @var{name} among its @var{<bindings>}. If failed,
address@hidden tries to locate a @code{*default*} binding. It's
+an error if the latter attempt fails as well. Having found a binding,
+the @code{pre-post-order} function first checks to see if the binding is
+of the form
+
address@hidden
+ (<trigger-symbol> *preorder* . <handler>)
address@hidden smallexample
+
+If it is, the handler is 'applied' to the current node. Otherwise, the
+pre-post-order function first calls itself recursively for each child of
+the current node, with @var{<new-bindings>} prepended to the
address@hidden<bindings>} in effect. The result of these calls is passed to the
address@hidden<handler>} (along with the head of the current @var{<Node>}). To
be
+more precise, the handler is _applied_ to the head of the current node
+and its processed children. The result of the handler, which should also
+be a @code{<tree>}, replaces the current @var{<Node>}. If the current
address@hidden<Node>} is a text string or other atom, a special binding with a
+symbol @code{*text*} is looked up.
+
+A binding can also be of a form
+
address@hidden
+ (<trigger-symbol> *macro* . <handler>)
address@hidden smallexample
+
+This is equivalent to @code{*preorder*} described above. However, the
+result is re-processed again, with the current stylesheet.
+
address@hidden Usage
address@hidden transform SRV:address@hidden SRV:send-reply . fragments
+Output the @var{fragments} to the current output port.
+
+The fragments are a list of strings, characters, numbers, thunks,
address@hidden, @code{#t} -- and other fragments. The function traverses the
+tree depth-first, writes out strings and characters, executes thunks,
+and ignores @code{#f} and @code{'()}. The function returns @code{#t} if
+anything was written at all; otherwise the result is @code{#f} If
address@hidden occurs among the fragments, it is not written out but causes
+the result of @code{SRV:send-reply} to be @code{#t}.
+
address@hidden defun
+
address@hidden transform address@hidden foldts fdown fup fhere seed tree
address@hidden defun
+
address@hidden transform address@hidden post-order tree bindings
address@hidden defun
+
address@hidden transform address@hidden pre-post-order tree bindings
address@hidden defun
+
address@hidden transform address@hidden replace-range beg-pred end-pred forest
address@hidden defun
+
address@hidden sxml xpath
address@hidden (sxml xpath)
address@hidden Overview
address@hidden SXPath: SXML Query Language
+SXPath is a query language for SXML, an instance of XML Information set
+(Infoset) in the form of s-expressions. See @code{(sxml ssax)} for the
+definition of SXML and more details. SXPath is also a translation into
+Scheme of an XML Path Language, @uref{http://www.w3.org/TR/xpath,XPath}.
+XPath and SXPath describe means of selecting a set of Infoset's items or
+their properties.
+
+To facilitate queries, XPath maps the XML Infoset into an explicit tree,
+and introduces important notions of a location path and a current,
+context node. A location path denotes a selection of a set of nodes
+relative to a context node. Any XPath tree has a distinguished, root
+node -- which serves as the context node for absolute location paths.
+Location path is recursively defined as a location step joined with a
+location path. A location step is a simple query of the database
+relative to a context node. A step may include expressions that further
+filter the selected set. Each node in the resulting set is used as a
+context node for the adjoining location path. The result of the step is
+a union of the sets returned by the latter location paths.
+
+The SXML representation of the XML Infoset (see SSAX.scm) is rather
+suitable for querying as it is. Bowing to the XPath specification, we
+will refer to SXML information items as 'Nodes':
+
address@hidden
+ <Node> ::= <Element> | <attributes-coll> | <attrib>
+ | "text string" | <PI>
address@hidden example
+
+This production can also be described as
+
address@hidden
+ <Node> ::= (name . <Nodeset>) | "text string"
address@hidden example
+
+An (ordered) set of nodes is just a list of the constituent nodes:
+
address@hidden
+ <Nodeset> ::= (<Node> ...)
address@hidden example
+
+Nodesets, and Nodes other than text strings are both lists. A <Nodeset>
+however is either an empty list, or a list whose head is not a symbol. A
+symbol at the head of a node is either an XML name (in which case it's a
+tag of an XML element), or an administrative name such as '@@'. This
+uniform list representation makes processing rather simple and elegant,
+while avoiding confusion. The multi-branch tree structure formed by the
+mutually-recursive datatypes <Node> and <Nodeset> lends itself well to
+processing by functional languages.
+
+A location path is in fact a composite query over an XPath tree or its
+branch. A singe step is a combination of a projection, selection or a
+transitive closure. Multiple steps are combined via join and union
+operations. This insight allows us to @emph{elegantly} implement XPath
+as a sequence of projection and filtering primitives -- converters --
+joined by @dfn{combinators}. Each converter takes a node and returns a
+nodeset which is the result of the corresponding query relative to that
+node. A converter can also be called on a set of nodes. In that case it
+returns a union of the corresponding queries over each node in the set.
+The union is easily implemented as a list append operation as all nodes
+in a SXML tree are considered distinct, by XPath conventions. We also
+preserve the order of the members in the union. Query combinators are
+high-order functions: they take converter(s) (which is a Node|Nodeset ->
+Nodeset function) and compose or otherwise combine them. We will be
+concerned with only relative location paths [XPath]: an absolute
+location path is a relative path applied to the root node.
+
+Similarly to XPath, SXPath defines full and abbreviated notations for
+location paths. In both cases, the abbreviated notation can be
+mechanically expanded into the full form by simple rewriting rules. In
+case of SXPath the corresponding rules are given as comments to a sxpath
+function, below. The regression test suite at the end of this file shows
+a representative sample of SXPaths in both notations, juxtaposed with
+the corresponding XPath expressions. Most of the samples are borrowed
+literally from the XPath specification, while the others are adjusted
+for our running example, tree1.
+
address@hidden Usage
address@hidden xpath address@hidden nodeset? x
address@hidden defun
+
address@hidden xpath address@hidden node-typeof? crit
address@hidden defun
+
address@hidden xpath address@hidden node-eq? other
address@hidden defun
+
address@hidden xpath address@hidden node-equal? other
address@hidden defun
+
address@hidden xpath address@hidden node-pos n
address@hidden defun
+
address@hidden xpath address@hidden filter pred?
address@hidden
+ -- Scheme Procedure: filter pred list
+ Return all the elements of 2nd arg LIST that satisfy predicate
+ PRED. The list is not disordered - elements that appear in the
+ result list occur in the same order as they occur in the argument
+ list. The returned list may share a common tail with the argument
+ list. The dynamic order in which the various applications of pred
+ are made is not specified.
+
+ (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
+
+
address@hidden verbatim
+
address@hidden defun
+
address@hidden xpath address@hidden take-until pred?
address@hidden defun
+
address@hidden xpath address@hidden take-after pred?
address@hidden defun
+
address@hidden xpath address@hidden map-union proc lst
address@hidden defun
+
address@hidden xpath address@hidden node-reverse node-or-nodeset
address@hidden defun
+
address@hidden xpath address@hidden node-trace title
address@hidden defun
+
address@hidden xpath address@hidden select-kids test-pred?
address@hidden defun
+
address@hidden xpath address@hidden node-self pred?
address@hidden
+ -- Scheme Procedure: filter pred list
+ Return all the elements of 2nd arg LIST that satisfy predicate
+ PRED. The list is not disordered - elements that appear in the
+ result list occur in the same order as they occur in the argument
+ list. The returned list may share a common tail with the argument
+ list. The dynamic order in which the various applications of pred
+ are made is not specified.
+
+ (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
+
+
address@hidden verbatim
+
address@hidden defun
+
address@hidden xpath address@hidden node-join . selectors
address@hidden defun
+
address@hidden xpath address@hidden node-reduce . converters
address@hidden defun
+
address@hidden xpath address@hidden node-or . converters
address@hidden defun
+
address@hidden xpath address@hidden node-closure test-pred?
address@hidden defun
+
address@hidden xpath address@hidden node-parent rootnode
address@hidden defun
+
address@hidden xpath address@hidden sxpath path
address@hidden defun
diff --git a/doc/ref/texinfo.texi b/doc/ref/texinfo.texi
new file mode 100644
index 0000000..b2947fc
--- /dev/null
+++ b/doc/ref/texinfo.texi
@@ -0,0 +1,588 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 2013 Free Software Foundation, Inc.
address@hidden See the file guile.texi for copying conditions.
+
address@hidden Texinfo
address@hidden Texinfo
+
address@hidden
+* 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
address@hidden menu
+
address@hidden texinfo
address@hidden (texinfo)
address@hidden Overview
address@hidden Texinfo processing in scheme
+This module parses texinfo into SXML. TeX will always be the processor
+of choice for print output, of course. However, although @code{makeinfo}
+works well for info, its output in other formats is not very
+customizable, and the program is not extensible as a whole. This module
+aims to provide an extensible framework for texinfo processing that
+integrates texinfo into the constellation of SXML processing tools.
+
address@hidden Notes on the SXML vocabulary
+Consider the following texinfo fragment:
+
address@hidden
+ @@deffn Primitive set-car! pair value
+ This function...
+ @@end deffn
address@hidden example
+
+Logically, the category (Primitive), name (set-car!), and arguments
+(pair value) are ``attributes'' of the deffn, with the description as
+the content. However, texinfo allows for @@-commands within the
+arguments to an environment, like @code{@@deffn}, which means that
+texinfo ``attributes'' are PCDATA. XML attributes, on the other hand,
+are CDATA. For this reason, ``attributes'' of texinfo @@-commands are
+called ``arguments'', and are grouped under the special element, `%'.
+
+Because `%' is not a valid NCName, stexinfo is a superset of SXML. In
+the interests of interoperability, this module provides a conversion
+function to replace the `%' with `texinfo-arguments'.
+
address@hidden Usage
address@hidden address@hidden call-with-file-and-dir filename proc
+Call the one-argument procedure @var{proc} with an input port that reads
+from @var{filename}. During the dynamic extent of @var{proc}'s
+execution, the current directory will be @code{(dirname
address@hidden)}. This is useful for parsing documents that can include
+files by relative path name.
+
address@hidden defun
+
address@hidden address@hidden texi-command-specs
address@hidden defvar
+
address@hidden address@hidden texi-command-depth command max-depth
+Given the texinfo command @var{command}, return its nesting level, or
address@hidden if it nests too deep for @var{max-depth}.
+
+Examples:
+
address@hidden
+ (texi-command-depth 'chapter 4) @result{} 1
+ (texi-command-depth 'top 4) @result{} 0
+ (texi-command-depth 'subsection 4) @result{} 3
+ (texi-command-depth 'appendixsubsec 4) @result{} 3
+ (texi-command-depth 'subsection 2) @result{} #f
address@hidden example
+
address@hidden defun
+
address@hidden texi-fragment->address@hidden texi-fragment->stexi string-or-port
+Parse the texinfo commands in @var{string-or-port}, and return the
+resultant stexi tree. The head of the tree will be the special command,
address@hidden
+
address@hidden defun
+
address@hidden texi->address@hidden texi->stexi port
+Read a full texinfo document from @var{port} and return the parsed stexi
+tree. The parsing will start at the @code{@@settitle} and end at
address@hidden@@bye} or EOF.
+
address@hidden defun
+
address@hidden stexi->address@hidden stexi->sxml tree
+Transform the stexi tree @var{tree} into sxml. This involves replacing
+the @code{%} element that keeps the texinfo arguments with an element
+for each argument.
+
+FIXME: right now it just changes % to @code{texinfo-arguments} -- that
+doesn't hang with the idea of making a dtd at some point
+
address@hidden defun
+
address@hidden texinfo docbook
address@hidden (texinfo docbook)
address@hidden Overview
address@hidden
+This module exports procedures for transforming a limited subset of the
+SXML representation of docbook into stexi. It is not complete by any
+means. The intention is to gather a number of routines and stylesheets
+so that external modules can parse specific subsets of docbook, for
+example that set generated by certain tools.
+
address@hidden Usage
address@hidden docbook *sdocbook->address@hidden *sdocbook->stexi-rules*
address@hidden defvar
+
address@hidden docbook address@hidden *sdocbook-block-commands*
address@hidden defvar
+
address@hidden docbook address@hidden sdocbook-flatten sdocbook
+"Flatten" a fragment of sdocbook so that block elements do not nest
+inside each other.
+
+Docbook is a nested format, where e.g. a @code{refsect2} normally
+appears inside a @code{refsect1}. Logical divisions in the document are
+represented via the tree topology; a @code{refsect2} element
address@hidden all of the elements in its section.
+
+On the contrary, texinfo is a flat format, in which sections are marked
+off by standalone section headers like @code{@@subsection}, and block
+elements do not nest inside each other.
+
+This function takes a nested sdocbook fragment @var{sdocbook} and
+flattens all of the sections, such that e.g.
+
address@hidden
+ (refsect1 (refsect2 (para "Hello")))
address@hidden example
+
+becomes
+
address@hidden
+ ((refsect1) (refsect2) (para "Hello"))
address@hidden example
+
+Oftentimes (always?) sectioning elements have @code{<title>} as their
+first element child; users interested in processing the @code{refsect*}
+elements into proper sectioning elements like @code{chapter} might be
+interested in @code{replace-titles} and @code{filter-empty-elements}.
address@hidden docbook replace-titles,,replace-titles}, and @ref{texinfo
+docbook filter-empty-elements,,filter-empty-elements}.
+
+Returns a nodeset, as described in @ref{sxml xpath}. That is to say,
+this function returns an untagged list of stexi elements.
+
address@hidden defun
+
address@hidden docbook address@hidden filter-empty-elements sdocbook
+Filters out empty elements in an sdocbook nodeset. Mostly useful after
+running @code{sdocbook-flatten}.
+
address@hidden defun
+
address@hidden docbook address@hidden replace-titles sdocbook-fragment
+Iterate over the sdocbook nodeset @var{sdocbook-fragment}, transforming
+contiguous @code{refsect} and @code{title} elements into the appropriate
+texinfo sectioning command. Most useful after having run
address@hidden
+
+For example:
+
address@hidden
+ (replace-titles '((refsect1) (title "Foo") (para "Bar.")))
+ @result{} '((chapter "Foo") (para "Bar."))
address@hidden example
+
address@hidden defun
+
address@hidden texinfo html
address@hidden (texinfo html)
address@hidden Overview
+This module implements transformation from @code{stexi} to HTML. Note
+that the output of @code{stexi->shtml} is actually SXML with the HTML
+vocabulary. This means that the output can be further processed, and
+that it must eventually be serialized by @ref{sxml simple
+sxml->xml,sxml->xml}. References (i.e., the @code{@@ref} family of
+commands) are resolved by a @dfn{ref-resolver}. @xref{texinfo html
+add-ref-resolver!,add-ref-resolver!}, for more information.
+
address@hidden Usage
address@hidden html address@hidden add-ref-resolver! proc
+Add @var{proc} to the head of the list of ref-resolvers. @var{proc} will
+be expected to take the name of a node and the name of a manual and
+return the URL of the referent, or @code{#f} to pass control to the next
+ref-resolver in the list.
+
+The default ref-resolver will return the concatenation of the manual
+name, @code{#}, and the node name.
+
address@hidden defun
+
address@hidden html stexi->address@hidden stexi->shtml tree
+Transform the stexi @var{tree} into shtml, resolving references via
+ref-resolvers. See the module commentary for more details.
+
address@hidden defun
+
address@hidden html address@hidden urlify str
address@hidden defun
+
address@hidden texinfo indexing
address@hidden (texinfo indexing)
address@hidden Overview
address@hidden texinfo formatting
+Given a piece of stexi, return an index of a specified variety.
+
+Note that currently, @code{stexi-extract-index} doesn't differentiate
+between different kinds of index entries. That's a bug ;)
+
address@hidden Usage
address@hidden indexing address@hidden stexi-extract-index tree manual-name kind
+Given an stexi tree @var{tree}, index all of the entries of type
address@hidden @var{kind} can be one of the predefined texinfo indices
+(@code{concept}, @code{variable}, @code{function}, @code{key},
address@hidden, @code{type}) or one of the special symbols @code{auto}
+or @code{all}. @code{auto} will scan the stext for a @code{(printindex)}
+statement, and @code{all} will generate an index from all entries,
+regardless of type.
+
+The returned index is a list of pairs, the @sc{car} of which is the
+entry (a string) and the @sc{cdr} of which is a node name (a string).
+
address@hidden defun
+
address@hidden texinfo string-utils
address@hidden (texinfo string-utils)
address@hidden Overview
+Module @samp{(texinfo string-utils)} provides various string-related
+functions useful to Guile's texinfo support.
+
address@hidden Usage
address@hidden string-utils address@hidden escape-special-chars str
special-chars escape-char
+Returns a copy of @var{str} with all given special characters preceded
+by the given @var{escape-char}.
+
address@hidden can either be a single character, or a string
+consisting of all the special characters.
+
address@hidden
+;; make a string regexp-safe...
+ (escape-special-chars "***(Example String)***"
+ "[]()/*."
+ #\\)
+=> "\\*\\*\\*\\(Example String\\)\\*\\*\\*"
+
+;; also can escape a singe char...
+ (escape-special-chars "richardt@@vzavenue.net"
+ #\@@
+ #\@@)
+=> "richardt@@@@vzavenue.net"
address@hidden lisp
+
address@hidden defun
+
address@hidden string-utils address@hidden transform-string str match? replace
[start] [end]
+Uses @var{match?} against each character in @var{str}, and performs a
+replacement on each character for which matches are found.
+
address@hidden may either be a function, a character, a string, or
address@hidden If @var{match?} is a function, then it takes a single
+character as input, and should return @samp{#t} for matches.
address@hidden is a character, it is compared to each string character
+using @code{char=?}. If @var{match?} is a string, then any character in
+that string will be considered a match. @code{#t} will cause every
+character to be a match.
+
+If @var{replace} is a function, it is called with the matched character
+as an argument, and the returned value is sent to the output string via
address@hidden If @var{replace} is anything else, it is sent through
+the output string via @samp{display}.
+
+Note that te replacement for the matched characters does not need to be
+a single character. That is what differentiates this function from
address@hidden, and what makes it useful for applications such as
+converting @samp{#\&} to @samp{"&"} in web page text. Some other
+functions in this module are just wrappers around common uses of
address@hidden Transformations not possible with this function
+should probably be done with regular expressions.
+
+If @var{start} and @var{end} are given, they control which portion of
+the string undergoes transformation. The entire input string is still
+output, though. So, if @var{start} is @samp{5}, then the first five
+characters of @var{str} will still appear in the returned string.
+
address@hidden
+; these two are equivalent...
+ (transform-string str #\space #\-) ; change all spaces to -'s
+ (transform-string str (lambda (c) (char=? #\space c)) #\-)
address@hidden lisp
+
address@hidden defun
+
address@hidden string-utils address@hidden expand-tabs str [tab-size]
+Returns a copy of @var{str} with all tabs expanded to spaces.
address@hidden defaults to 8.
+
+Assuming tab size of 8, this is equivalent to:
+
address@hidden
+ (transform-string str #\tab " ")
address@hidden lisp
+
address@hidden defun
+
address@hidden string-utils address@hidden center-string str [width] [chr]
[rchr]
+Returns a copy of @var{str} centered in a field of @var{width}
+characters. Any needed padding is done by character @var{chr}, which
+defaults to @samp{#\space}. If @var{rchr} is provided, then the padding
+to the right will use it instead. See the examples below. left and
address@hidden on the right. The default @var{width} is 80. The default
address@hidden and @var{rchr} is @samp{#\space}. The string is never
+truncated.
+
address@hidden
+ (center-string "Richard Todd" 24)
+=> " Richard Todd "
+
+ (center-string " Richard Todd " 24 #\=)
+=> "===== Richard Todd ====="
+
+ (center-string " Richard Todd " 24 #\< #\>)
+=> "<<<<< Richard Todd >>>>>"
address@hidden lisp
+
address@hidden defun
+
address@hidden string-utils address@hidden left-justify-string str [width] [chr]
address@hidden str [width chr]}. Returns a copy of @var{str}
+padded with @var{chr} such that it is left justified in a field of
address@hidden characters. The default @var{width} is 80. Unlike
address@hidden from srfi-13, the string is never truncated.
+
address@hidden defun
+
address@hidden string-utils address@hidden right-justify-string str [width]
[chr]
+Returns a copy of @var{str} padded with @var{chr} such that it is right
+justified in a field of @var{width} characters. The default @var{width}
+is 80. The default @var{chr} is @samp{#\space}. Unlike @samp{string-pad}
+from srfi-13, the string is never truncated.
+
address@hidden defun
+
address@hidden string-utils address@hidden collapse-repeated-chars str [chr]
[num]
+Returns a copy of @var{str} with all repeated instances of @var{chr}
+collapsed down to at most @var{num} instances. The default value for
address@hidden is @samp{#\space}, and the default value for @var{num} is 1.
+
address@hidden
+ (collapse-repeated-chars "H e l l o")
+=> "H e l l o"
+ (collapse-repeated-chars "H--e--l--l--o" #\-)
+=> "H-e-l-l-o"
+ (collapse-repeated-chars "H-e--l---l----o" #\- 2)
+=> "H-e--l--l--o"
address@hidden lisp
+
address@hidden defun
+
address@hidden string-utils address@hidden make-text-wrapper [#:line-width]
[#:expand-tabs?] [#:tab-width] [#:collapse-whitespace?] [#:subsequent-indent]
[#:initial-indent] [#:break-long-words?]
+Returns a procedure that will split a string into lines according to the
+given parameters.
+
address@hidden @code
address@hidden #:line-width
+This is the target length used when deciding where to wrap lines.
+Default is 80.
+
address@hidden #:expand-tabs?
+Boolean describing whether tabs in the input should be expanded. Default
+is #t.
+
address@hidden #:tab-width
+If tabs are expanded, this will be the number of spaces to which they
+expand. Default is 8.
+
address@hidden #:collapse-whitespace?
+Boolean describing whether the whitespace inside the existing text
+should be removed or not. Default is #t.
+
+If text is already well-formatted, and is just being wrapped to fit in a
+different width, then set this to @samp{#f}. This way, many common text
+conventions (such as two spaces between sentences) can be preserved if
+in the original text. If the input text spacing cannot be trusted, then
+leave this setting at the default, and all repeated whitespace will be
+collapsed down to a single space.
+
address@hidden #:initial-indent
+Defines a string that will be put in front of the first line of wrapped
+text. Default is the empty string, ``''.
+
address@hidden #:subsequent-indent
+Defines a string that will be put in front of all lines of wrapped text,
+except the first one. Default is the empty string, ``''.
+
address@hidden #:break-long-words?
+If a single word is too big to fit on a line, this setting tells the
+wrapper what to do. Defaults to #t, which will break up long words. When
+set to #f, the line will be allowed, even though it is longer than the
+defined @code{#:line-width}.
+
address@hidden table
+
+The return value is a procedure of one argument, the input string, which
+returns a list of strings, where each element of the list is one line.
+
address@hidden defun
+
address@hidden string-utils address@hidden fill-string str . kwargs
+Wraps the text given in string @var{str} according to the parameters
+provided in @var{kwargs}, or the default setting if they are not given.
+Returns a single string with the wrapped text. Valid keyword arguments
+are discussed in @code{make-text-wrapper}.
+
address@hidden defun
+
address@hidden string-utils string->address@hidden string->wrapped-lines str .
kwargs
address@hidden>wrapped-lines str keywds ...}. Wraps the text given in
+string @var{str} according to the parameters provided in @var{keywds},
+or the default setting if they are not given. Returns a list of strings
+representing the formatted lines. Valid keyword arguments are discussed
+in @code{make-text-wrapper}.
+
address@hidden defun
+
address@hidden texinfo plain-text
address@hidden (texinfo plain-text)
address@hidden Overview
+Transformation from stexi to plain-text. Strives to re-create the output
+from @code{info}; comes pretty damn close.
+
address@hidden Usage
address@hidden plain-text stexi->address@hidden stexi->plain-text tree
+Transform @var{tree} into plain text. Returns a string.
+
address@hidden defun
+
address@hidden texinfo serialize
address@hidden (texinfo serialize)
address@hidden Overview
+Serialization of @code{stexi} to plain texinfo.
+
address@hidden Usage
address@hidden serialize stexi->address@hidden stexi->texi tree
+Serialize the stexi @var{tree} into plain texinfo.
+
address@hidden defun
+
address@hidden texinfo reflection
address@hidden (texinfo reflection)
address@hidden Overview
+Routines to generare @code{stexi} documentation for objects and modules.
+
+Note that in this context, an @dfn{object} is just a value associated
+with a location. It has nothing to do with GOOPS.
+
address@hidden Usage
address@hidden reflection address@hidden module-stexi-documentation sym-name
[%docs-resolver] [#:docs-resolver]
+Return documentation for the module named @var{sym-name}. The
+documentation will be formatted as @code{stexi}
+(@pxref{texinfo,texinfo}).
+
address@hidden defun
+
address@hidden reflection address@hidden script-stexi-documentation scriptpath
+Return documentation for given script. The documentation will be taken
+from the script's commentary, and will be returned in the @code{stexi}
+format (@pxref{texinfo,texinfo}).
+
address@hidden defun
+
address@hidden reflection address@hidden object-stexi-documentation _ [_]
[#:force]
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-standard-copying name
version updated years copyright-holder permissions
+Create a standard texinfo @code{copying} section.
+
address@hidden is a list of years (as integers) in which the modules being
+documented were released. All other arguments are strings.
+
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-standard-titlepage name
version updated authors
+Create a standard GNU title page.
+
address@hidden is a list of @code{(@var{name} . @var{email})} pairs. All
+other arguments are strings.
+
+Here is an example of the usage of this procedure:
+
address@hidden
+ (package-stexi-standard-titlepage
+ "Foolib"
+ "3.2"
+ "26 September 2006"
+ '(("Alyssa P Hacker" . "alyssa@@example.com"))
+ '(2004 2005 2006)
+ "Free Software Foundation, Inc."
+ "Standard GPL permissions blurb goes here")
address@hidden smallexample
+
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-generic-menu name entries
+Create a menu from a generic alist of entries, the car of which should
+be the node name, and the cdr the description. As an exception, an entry
+of @code{#f} will produce a separator.
+
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-standard-menu name
modules module-descriptions extra-entries
+Create a standard top node and menu, suitable for processing by
+makeinfo.
+
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-extended-menu name
module-pairs script-pairs extra-entries
+Create an "extended" menu, like the standard menu but with a section for
+scripts.
+
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-standard-prologue name
filename category description copying titlepage menu
+Create a standard prologue, suitable for later serialization to texinfo
+and .info creation with makeinfo.
+
+Returns a list of stexinfo forms suitable for passing to
address@hidden as the prologue. @xref{texinfo
+reflection package-stexi-documentation}, @ref{texinfo reflection
+package-stexi-standard-titlepage,package-stexi-standard-titlepage},
address@hidden reflection
+package-stexi-standard-copying,package-stexi-standard-copying}, and
address@hidden reflection
+package-stexi-standard-menu,package-stexi-standard-menu}.
+
address@hidden defun
+
address@hidden reflection address@hidden package-stexi-documentation modules
name filename prologue epilogue [#:module-stexi-documentation-args] [#:scripts]
+Create stexi documentation for a @dfn{package}, where a package is a set
+of modules that is released together.
+
address@hidden is expected to be a list of module names, where a module
+name is a list of symbols. The stexi that is returned will be titled
address@hidden and a texinfo filename of @var{filename}.
+
address@hidden and @var{epilogue} are lists of stexi forms that will be
+spliced into the output document before and after the generated modules
+documentation, respectively. @xref{texinfo reflection
+package-stexi-standard-prologue}, to create a conventional GNU texinfo
+prologue.
+
address@hidden is an optional argument that, if
+given, will be added to the argument list when
address@hidden is called. For example, it might be
+useful to define a @code{#:docs-resolver} argument.
+
address@hidden defun
+
address@hidden reflection address@hidden
package-stexi-documentation-for-include modules module-descriptions
[#:module-stexi-documentation-args]
+Create stexi documentation for a @dfn{package}, where a package is a set
+of modules that is released together.
+
address@hidden 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.
+
address@hidden is an optional argument that, if
+given, will be added to the argument list when
address@hidden is called. For example, it might be
+useful to define a @code{#:docs-resolver} argument.
+
address@hidden defun
hooks/post-receive
--
GNU Guile
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.7-31-g58c4a39,
Andy Wingo <=