From 58c4a39d9824d021994754181a369d1daa30f588 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Wed, 16 Jan 2013 10:03:44 +0100 Subject: [PATCH] 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. --- 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 201ab6b3f..260bb1448 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*))" > "$@.tmp" - mv "$@.tmp" "$@" - -# 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" > "$@.tmp" - mv "$@.tmp" "$@" - -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 a1b3fe60c..a6e3e7d0c 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 -@node Standard Library -@chapter Standard Library - -@lowersections -@include standard-library.texi -@raisesections +@include statprof.texi +@include sxml.texi +@include texinfo.texi @include goops.texi diff --git a/doc/ref/make-texinfo.scm b/doc/ref/make-texinfo.scm deleted file mode 100644 index c967bc163..000000000 --- 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 - -;; 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.am b/doc/ref/standard-library.am deleted file mode 100644 index 27246f4ff..000000000 --- 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 7fd17b51f..000000000 --- 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 000000000..c481ac72e --- /dev/null +++ b/doc/ref/statprof.texi @@ -0,0 +1,283 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 2013 Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@node Statprof +@section Statprof + +@code{(statprof)} is a fairly simple statistical profiler for Guile. + +A simple use of statprof would look like this: + +@example +(statprof-reset 0 50000 #t) +(statprof-start) +(do-something) +(statprof-stop) +(statprof-display) +@end 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: + +@example + % 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 + ... +@end 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. + +@table @asis +@item % time +The percent of the time spent inside the procedure itself (not counting +children). + +@item cumulative seconds +The total number of seconds spent in the procedure, including children. + +@item self seconds +The total number of seconds spent in the procedure itself (not counting +children). + +@item calls +The total number of times the procedure was called. + +@item self ms/call +The average time taken by the procedure itself on each call, in ms. + +@item total ms/call +The average time taken by each call to the procedure, including time +spent in child functions. + +@item name +The name of the procedure. + +@end 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 :-) + +@section Implementation notes +The profiler works by setting the unix profiling signal +@code{ITIMER_PROF} 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 +@code{ITIMER_PROF} 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. + +@section Usage +@anchor{statprof statprof-active?}@defun statprof-active? +Returns @code{#t} if @code{statprof-start} has been called more times +than @code{statprof-stop}, @code{#f} otherwise. + +@end defun + +@anchor{statprof statprof-start}@defun statprof-start +Start the profiler.@code{} + +@end defun + +@anchor{statprof statprof-stop}@defun statprof-stop +Stop the profiler.@code{} + +@end defun + +@anchor{statprof statprof-reset}@defun statprof-reset sample-seconds sample-microseconds count-calls? [full-stacks?] +Reset the statprof sampler interval to @var{sample-seconds} and +@var{sample-microseconds}. 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. + +@end defun + +@anchor{statprof statprof-accumulated-time}@defun statprof-accumulated-time +Returns the time accumulated during the last statprof run.@code{} + +@end defun + +@anchor{statprof statprof-sample-count}@defun statprof-sample-count +Returns the number of samples taken during the last statprof run.@code{} + +@end defun + +@anchor{statprof statprof-fold-call-data}@defun 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, +@code{(@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. + +@end defun + +@anchor{statprof statprof-proc-call-data}@defun statprof-proc-call-data proc +Returns the call-data associated with @var{proc}, or @code{#f} if none +is available. + +@end defun + +@anchor{statprof statprof-call-data-name}@defun statprof-call-data-name cd +@end defun + +@anchor{statprof statprof-call-data-calls}@defun statprof-call-data-calls cd +@end defun + +@anchor{statprof statprof-call-data-cum-samples}@defun statprof-call-data-cum-samples cd +@end defun + +@anchor{statprof statprof-call-data-self-samples}@defun statprof-call-data-self-samples cd +@end defun + +@anchor{statprof statprof-call-data->stats}@defun statprof-call-data->stats call-data +Returns an object of type @code{statprof-stats}. + +@end defun + +@anchor{statprof statprof-stats-proc-name}@defun statprof-stats-proc-name stats +@end defun + +@anchor{statprof statprof-stats-%-time-in-proc}@defun statprof-stats-%-time-in-proc stats +@end defun + +@anchor{statprof statprof-stats-cum-secs-in-proc}@defun statprof-stats-cum-secs-in-proc stats +@end defun + +@anchor{statprof statprof-stats-self-secs-in-proc}@defun statprof-stats-self-secs-in-proc stats +@end defun + +@anchor{statprof statprof-stats-calls}@defun statprof-stats-calls stats +@end defun + +@anchor{statprof statprof-stats-self-secs-per-call}@defun statprof-stats-self-secs-per-call stats +@end defun + +@anchor{statprof statprof-stats-cum-secs-per-call}@defun statprof-stats-cum-secs-per-call stats +@end defun + +@anchor{statprof statprof-display}@defun statprof-display . _ +Displays a gprof-like summary of the statistics collected. Unless an +optional @var{port} argument is passed, uses the current output port. + +@end defun + +@anchor{statprof statprof-display-anomolies}@defun statprof-display-anomolies +A sanity check that attempts to detect anomolies in statprof's +statistics.@code{} + +@end defun + +@anchor{statprof statprof-fetch-stacks}@defun statprof-fetch-stacks +Returns a list of stacks, as they were captured since the last call to +@code{statprof-reset}. + +Note that stacks are only collected if the @var{full-stacks?} argument +to @code{statprof-reset} is true. + +@end defun + +@anchor{statprof statprof-fetch-call-tree}@defun statprof-fetch-call-tree +@verbatim +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 ::= (@@var@{proc@} @@var@{count@} . @@var@{nodes@}) +@@end code +@end verbatim + +@end defun + +@anchor{statprof statprof}@defun 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 +@code{statprof-fetch-stacks} or @code{statprof-fetch-call-tree} to +retrieve the last-stored stacks. + +@end defun + +@anchor{statprof with-statprof}@defspec with-statprof args +Profiles the expressions in its body. + +Keyword arguments: + +@table @code +@item #:loop +Execute the body @var{loop} number of times, or @code{#f} for no looping + +default: @code{#f} + +@item #:hz +Sampling rate + +default: @code{20} + +@item #:count-calls? +Whether to instrument each function call (expensive) + +default: @code{#f} + +@item #:full-stacks? +Whether to collect away all sampled stacks into a list + +default: @code{#f} + +@end table + +@end defspec + +@anchor{statprof gcprof}@defun 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 +@var{loop} 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 +@code{statprof-fetch-stacks} or @code{statprof-fetch-call-tree} to +retrieve the last-stored stacks. + +@end defun diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi new file mode 100644 index 000000000..3ce6062f4 --- /dev/null +++ b/doc/ref/sxml.texi @@ -0,0 +1,733 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 2013 Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@node SXML +@section SXML + +@menu +* 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 +@end menu + +@node sxml apply-templates +@subsection (sxml apply-templates) +@subsubsection Overview +Pre-order traversal of a tree and creation of a new tree: + +@smallexample + apply-templates:: tree x -> +@end smallexample + +where + +@smallexample + ::= (