diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-03-15 16:40:39 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-03-15 17:08:46 +0200 |
commit | 04b9cd97aa9287668ce41e3db7e273324d3136bc (patch) | |
tree | f5df013d2eb3f594914ccbc40c42c776e5a12e98 | |
parent | e3fcfbbc3b488928f8cb53c7ab76af8de7fec4ce (diff) | |
download | gamma-04b9cd97aa9287668ce41e3db7e273324d3136bc.tar.gz gamma-04b9cd97aa9287668ce41e3db7e273324d3136bc.tar.bz2 |
Add documentation.
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | NEWS | 4 | ||||
-rw-r--r-- | README | 88 | ||||
-rw-r--r-- | README-alpha | 75 | ||||
-rw-r--r-- | README-hacking | 2 | ||||
-rw-r--r-- | am/guile.m4 | 2 | ||||
-rw-r--r-- | configure.ac | 36 | ||||
-rw-r--r-- | doc/.gitignore | 21 | ||||
-rw-r--r-- | doc/Makefile.am | 130 | ||||
-rw-r--r-- | doc/expat.texi | 285 | ||||
-rw-r--r-- | doc/fdl.texi | 449 | ||||
-rw-r--r-- | doc/gamma.texi | 125 | ||||
-rwxr-xr-x | doc/gendocs_template | 78 | ||||
-rw-r--r-- | doc/macros.texi | 3 | ||||
-rw-r--r-- | doc/mastermenu.el | 90 | ||||
-rw-r--r-- | doc/rendition.texi | 94 | ||||
-rw-r--r-- | doc/sql.texi | 131 | ||||
-rw-r--r-- | doc/syslog.texi | 136 | ||||
-rw-r--r-- | doc/untabify.el | 13 | ||||
-rw-r--r-- | src/syslog.c | 27 |
20 files changed, 1763 insertions, 28 deletions
diff --git a/Makefile.am b/Makefile.am index 5419ad7..19cb54b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -16,7 +16,7 @@ ACLOCAL_AMFLAGS = -I m4 -I am -SUBDIRS = src scripts examples +SUBDIRS = src scripts examples doc # Define the following variables in order to use the ChangeLog rule below: # prev_change_log [optional] Name of the previous ChangeLog file. @@ -1,10 +1,12 @@ -Gamma NEWS -- history of user-visible changes. 2010-03-13 +Gamma NEWS -- history of user-visible changes. 2010-03-15 Copyright (C) 2004, 2007, 2010 Sergey Poznyakoff See the end of file for copying conditions. Please send radius bug reports to <gray@gnu.org.ua> +Version 1.99.99 + * New modules: expat and syslog @@ -1,36 +1,71 @@ -GAMMA = Guile Archive of Multiple Modules with 'A' just for the 'A' of it. +Gamma README +Copyright (C) 2002, 2004, 2007, 2010 Sergey Poznyakoff +See end of file for copying conditions * Introduction -It is a set of possibly useful modules. Currently it includes +This file contains brief information about configuring, testing +and running Gamma. It is provided as a brief reference only. +More specifically, is *not* intended as a replacement for the +documentation. The complete documentation for Gamma is available +in the doc/ subdirectory. To read it without installing the package +run `info -f doc/gamma.info'. After the package is installed +the documentation can be accessed running `info gamma'. -** interfaces for two SQL DBMS: MySQL and PostgreSQL -** interfaces to Expat -** interfaces to syslog +An online copy of the documentation in various formats is available +at http://gamma.man.gnu.org.ua. -Both are extensively used by Ellinika (http://ellinika.farlep.net) -and Runasimi (http://www.runasimi.org). +* Overview -* Installation +Gamma is a set of assorted modules for Guile. It includes: -Please see the INSTALL file in this directory for the generic instructions -on how to use configure. The list of GAMMA-specific options follows: +** (gamma sql) -** --without-mysql +This module provides interfaces for two SQL DBMS: MySQL and PostgreSQL. -Configure to work without MySQL +** (gamma expat) -** --without-postgres +Interfaces to Expat: a library for parsing XML documents. -Configure to work without Postgres +** (gamma syslog) + +Interfaces to syslog(2). + +* Uses + +Gamma is the main working horse for xmltools[1], a parser engine +powering Ellinika[2] and Runasimi[3] web projects. + +For more info on these, see: + +[1] http://puszcza.gnu.org.ua/projects/xmltools/ +[2] http://ellinika.gnu.org.ua +[3] http://www.runasimi.org + +* Installation + +For generic instructions on how to use configure, see the INSTALL file +in this directory. The following is a list of Gamma-specific options: + +** --disable-expat + +Disables building of the expat module ** --disable-sql -Disable both SQL interfaces. +Disables building of the sql module ** --disable-syslog -Do not compile syslog bindings. +Disables building of the syslog module + +** --without-mysql + +Configure to work without MySQL + +** --without-postgres + +Configure to work without Postgres ** --with-guiledir=DIR @@ -68,6 +103,25 @@ is equivalent to running ./configure LDFLAGS="-L/usr/mysql/lib -L/usr/pgsql/lib" +* Bug reporting. + +Send bug reports to <gray+gamma@gnu.org.ua>. + + +* Copyright information: + +Copyright (C) 2002, 2004, 2007, 2010 Sergey Poznyakoff + + Permission is granted to anyone to make or distribute verbatim copies + of this document as received, in any medium, provided that the + copyright notice and this permission notice are preserved, + thus giving the recipient permission to redistribute in turn. + + Permission is granted to distribute modified versions + of this document, or of portions of it, + under the above conditions, provided also that they + carry prominent notices stating who last changed them. + Local Variables: mode: outline @@ -77,4 +131,4 @@ End: -
\ No newline at end of file + diff --git a/README-alpha b/README-alpha new file mode 100644 index 0000000..58303ef --- /dev/null +++ b/README-alpha @@ -0,0 +1,75 @@ +This file is part of Gamma package. +See end of file for copying conditions. + +* Introduction + +This is a *pre-release* version, and not ready for production use yet. +If you are taking source from GIT, you will need to have several +special tools to help contribute. See the file README-hacking for more +information, See chapter `Bootstrapping' for the detailed instructions on +how to build the package. + +Please, note that the accompanying documentation may be inaccurate +or incomplete. The Git logs are the authoritative documentation of +all recent changes. To convert them to the traditional ChangeLog +format, run `make ChangeLog'. + +Please send comments and problem reports to <gray+gamma@gnu.org.ua>. + +* Checking Out the Sources + +The following instructions apply if you wish to obtain sources from +the GIT repository: + +To clone the Gamma repository, issue the following command: + + git clone git://git.gnu.org.ua/gamma.git + +or + + git clone http://git.gnu.org.ua/repo/gamma.git + +This will create a directory named `gamma' and populate it with the +sources. + +If you are not interested in the entire development history, you can +abridge it by giving the `--depth' option to clone. For example, + + git clone --depth 2 git://git.gnu.org.ua/repo/gamma.git + +will clone only two recent revisions from the repository. + +For more information about GIT access, visit +http://puszcza.gnu.org.ua/git/?group=gamma + +* Building + +The usual procedures apply: + + ./configure + make + make install + +See INSTALL and README for the detailed instructions. + +* Copyright information: + +Copyright (C) 2002, 2004, 2007, 2010 Sergey Poznyakoff + + Permission is granted to anyone to make or distribute verbatim copies + of this document as received, in any medium, provided that the + copyright notice and this permission notice are preserved, + thus giving the recipient permission to redistribute in turn. + + Permission is granted to distribute modified versions + of this document, or of portions of it, + under the above conditions, provided also that they + carry prominent notices stating who last changed them. + + +Local Variables: +mode: outline +paragraph-separate: "[ ]*$" +version-control: never +End: + diff --git a/README-hacking b/README-hacking index a668241..f9a5c99 100644 --- a/README-hacking +++ b/README-hacking @@ -31,7 +31,7 @@ You do this as follows: scripts/bootstrap --moddir modules --parents Once done, proceed as described in the file README (section -INSTALLATION). +"Installation"). For more information about `bootstrap', run `bootstrap --help'. diff --git a/am/guile.m4 b/am/guile.m4 index 2aa25c9..43e08c1 100644 --- a/am/guile.m4 +++ b/am/guile.m4 @@ -42,7 +42,7 @@ AC_DEFUN([MU_CHECK_GUILE], GUILE_INCLUDES=`guile-config compile` GUILE_LIBS=`guile-config link` fi - gpath=`bindir $GUILE_CONFIG`:$PATH + gpath=`dirname $GUILE_CONFIG`:$PATH AC_PATH_PROG(GUILE_SNARF, guile-snarf, no, $gpath) if test $GUILE_CONFIG != no; then diff --git a/configure.ac b/configure.ac index 4f3b6e4..483b882 100644 --- a/configure.ac +++ b/configure.ac @@ -16,12 +16,12 @@ dnl along with Gamma. If not, see <http://www.gnu.org/licenses/>. AC_PREREQ(2.63) -AC_INIT(gamma, 1.99, [gray@gnu.org.ua]) +AC_INIT(gamma, [1.99.99], [gray+gamma@gnu.org.ua]) AC_CONFIG_SRCDIR(src/guile-sql.h) AC_CONFIG_AUX_DIR([build-aux]) AC_CONFIG_MACRO_DIR([m4]) AC_CANONICAL_SYSTEM -AM_INIT_AUTOMAKE([1.11.1 gnu tar-ustar silent-rules]) +AM_INIT_AUTOMAKE([1.11.1 gnu tar-ustar readme-alpha silent-rules]) AC_CONFIG_HEADERS([config.h]) # Enable silent rules by default: @@ -74,6 +74,36 @@ if test -z "$GAMMA_LIB_LIST"; then AC_MSG_ERROR([Nothing to build!]) fi -AC_CONFIG_FILES(Makefile src/Makefile scripts/Makefile examples/Makefile) +# Doc hints. +# Select a rendition level: +# DISTRIB for stable releases (at most one dot in the version number) +# and maintenance releases (two dots, patchlevel < 50) +# PROOF for alpha releases. +# PUBLISH can only be required manually when running make in doc/ +AC_SUBST(RENDITION) +case `echo $VERSION|sed 's/[[^.]]//g'` in +""|".") RENDITION=DISTRIB;; +"..") if test `echo $VERSION | sed 's/.*\.//'` -lt 50; then + RENDITION=DISTRIB + else + RENDITION=PROOF + fi;; +*) RENDITION=PROOF;; +esac + +if test $RENDITION = "PROOF"; then + if test -r $srcdir/git-describe; then + GIT_DESCRIBE=`sed '2,$d' $srcdir/git-describe` + AC_DEFINE_UNQUOTED([GIT_DESCRIBE], "$GIT_DESCRIBE", + [The most recent git tag]) + fi +fi + + +AC_CONFIG_FILES(Makefile + src/Makefile + scripts/Makefile + examples/Makefile + doc/Makefile) AC_OUTPUT diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..f985f1a --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,21 @@ +gamma.info* +stamp-vti +version.texi +gamma.aux +gamma.cp +gamma.cps +gamma.dvi +gamma.fl +gamma.fn +gamma.kw +gamma.ky +gamma.log +gamma.mt +gamma.op +gamma.pg +gamma.pr +gamma.ps +gamma.toc +gamma.tp +gamma.vr + diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..bb3d940 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,130 @@ +# This file is part of Gamma. +# Copyright (C) 2002, 2007, 2010 Sergey Poznyakoff +# +# Gamma 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, or (at your option) +# any later version. +# +# Gamma 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 Gamma. If not, see <http://www.gnu.org/licenses/>. + +info_TEXINFOS=gamma.texi +gamma_TEXINFOS=\ + fdl.texi\ + macros.texi\ + rendition.texi\ + expat.texi\ + syslog.texi\ + sql.texi + +EXTRA_DIST = \ + gendocs_template\ + mastermenu.el\ + untabify.el + +clean-local: + @rm -rf manual + +# Checking +check-format: + @if test -n "`cat $(info_TEXINFOS) $(gamma_TEXINFOS) | tr -d -c '\t'`"; then \ + echo "Sources contain tabs; run make untabify"; \ + false; \ + fi + +check-refs: + @for file in $(info_TEXINFOS) $(gamma_TEXINFOS); \ + do \ + sed -e = $$file | \ + sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/'$$file':\1: \2/gp}'; \ + done > $@-t; \ + if [ -s $@-t ]; then \ + echo "Unresolved cross-references:"; \ + cat $@-t;\ + rm $@-t; \ + else \ + rm -f $@-t; \ + fi + +check-fixmes: + @for file in $(info_TEXINFOS) $(gamma_TEXINFOS); \ + do \ + sed -e = $$file | \ + sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \ + done > $@-t; \ + if [ -s $@-t ]; then \ + echo "Unresolved FIXMEs:"; \ + cat $@-t; \ + rm $@-t; \ + false; \ + else \ + rm -f $@-t; \ + fi + +check-writeme: + @grep -Hn @WRITEME $(info_TEXINFOS) $(gamma_TEXINFOS) > $@-t; \ + if [ -s $@-t ]; then \ + echo "Empty nodes:"; \ + cat $@-t; \ + rm $@-t; \ + false;\ + else \ + rm $@-t; \ + fi + +check-unrevised: + @grep -Hn @UNREVISED $(info_TEXINFOS) $(gamma_TEXINFOS) > $@-t; \ + if [ -s $@-t ]; then \ + echo "Unrevised nodes:"; \ + cat $@-t; \ + rm $@-t; \ + false;\ + else \ + rm $@-t; \ + fi + +all-check-docs: check-format \ + check-refs check-fixmes check-writeme check-unrevised + +check-docs: + @$(MAKE) -k all-check-docs + +# + +master-menu: + -$(AM_V_GEN)grep -q '^@detailmenu' $(info_TEXINFOS) && \ + emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS) + +untabify: + @emacs -batch -l untabify.el $(info_TEXINFOS) $(gamma_TEXINFOS) + +final: untabify master-menu + +# The rendering level is one of PUBLISH, DISTRIB or PROOF. +# Just call `make RENDITION=PROOF [target]' if you want PROOF rendition. + +MAKEINFOFLAGS=-D$(RENDITION) + +GENDOCS=gendocs.sh + +TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E + +# Make sure you set TEXINPUTS. +# TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions +.PHONY: manual +manual: + TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \ + MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \ + TEXI2DVI="$(TEXI2DVI) -t @finalout" \ + $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual' + +manual.tar.bz2: manual + tar cfj manual.tar.bz2 manual + +man-tar: manual.tar.bz2 diff --git a/doc/expat.texi b/doc/expat.texi new file mode 100644 index 0000000..e52a636 --- /dev/null +++ b/doc/expat.texi @@ -0,0 +1,285 @@ +@c This file is part of the Gamma manual. +@c Copyright (C) 2010 Sergey Poznyakoff +@c See gamma.texi for copying conditions. +@c ******************************************************************* +@WRITEME + +The @samp{(gamma expat)} module provides interface with +@command{libexpat}, a library for parsing @acronym{XML} documents. + +Usage: + +@lisp +(use-modules ((gamma expat))) +@end lisp + +@menu +* primitives:: Expat Primitives +* handlers:: +@end menu + +@node primitives +@section Expat Primitives +@WRITEME + +@deffn {Scheme procedure} xml-primitive-make-parser enc sep +Return a new @acronym{XML} parser. If @var{enc} is given, it must be one of: +@samp{US-ASCII}, @samp{UTF-8}, @samp{UTF-16}, @samp{ISO-8859-1}. If @var{sep} +is given, the returned parser has namespace processing in effect. In +that case, @var{sep} is a character which is used as a separator +between the namespace @acronym{URI} and the local part of the name in +returned namespace element and attribute names. +@end deffn + +@deffn {Scheme procedure} xml-set-encoding parser enc +Set the encoding to be used by the @var{parser}. The latter must be a +value returned from a previous call to +@code{xml-primitive-make-parser} or @code{xml-make-parser}. + +The sequence: + +@lisp +@group + (let ((parser (xml-primitive-make-parser))) + (xml-set-encoding parser encoding) + @dots{} +@end group +@end lisp + +@noindent +is equivalent to: + +@lisp + (let ((parser (xml-primitive-make-parser encoding))) + @dots{} +@end lisp + +@noindent +and to: + +@lisp + (let ((parser (xml-make-parser encoding))) + @dots{} +@end lisp +@end deffn + +@deffn {Scheme procedure} xml-primitive-parse parser input isfinal +Parse next piece of input. Arguments are: + +@table @var +@item parser +A parser returned from a previous call to +@code{xml-primitive-make-parser} or @code{xml-make-parser}. + +@item input +A piece of input text. + +@item isfinal +Boolean value indicating whether @var{input} is the last part of +input. +@end table +@end deffn + +@deffn {Scheme procedure} xml-primitive-set-handler parser key handler +Set @acronym{XML} handler for an event. Arguments are: + +@table @var +@item parser +A valid @acronym{XML} parser + +@item key +A key, identifying an event. + +@table @asis +@kwindex start-element-handler +@item #:start-element-handler + +@kwindex end-element-handler +@item #:end-element-handler + +@kwindex character-data-handler +@item #:character-data-handler + +@kwindex processing-instruction-handler +@item #:processing-instruction-handler + +@kwindex comment-handler +@item #:comment-handler + +@kwindex start-cdata-section-handler +@item #:start-cdata-section-handler + +@kwindex end-cdata-section-handler +@item #:end-cdata-section-handler + +@kwindex default-handler +@item #:default-handler + +@kwindex default-handler-expand +@item #:default-handler-expand + +@kwindex external-entity-ref-handler +@item #:external-entity-ref-handler + +@kwindex skipped-entity-handler +@item #:skipped-entity-handler + +@kwindex unknown-encoding-handler +@item #:unknown-encoding-handler + +@kwindex start-namespace-decl-handler +@item #:start-namespace-decl-handler + +@kwindex end-namespace-decl-handler +@item #:end-namespace-decl-handler + +@kwindex xml-decl-handler +@item #:xml-decl-handler + +@kwindex start-doctype-decl-handler +@item #:start-doctype-decl-handler + +@kwindex end-doctype-decl-handler +@item #:end-doctype-decl-handler + +@kwindex element-decl-handler +@item #:element-decl-handler + +@kwindex attlist-decl-handler +@item #:attlist-decl-handler + +@kwindex entity-decl-handler +@item #:entity-decl-handler + +@kwindex unparsed-entity-decl-handler +@item #:unparsed-entity-decl-handler + +@kwindex notation-decl-handler +@item #:notation-decl-handler + +@kwindex not-standalone-handler +@item #:not-standalone-handler +@end table + + +@item handler +Handler procedure. +@end table +@end deffn + +@deffn {Scheme function} xml-make-parser args@dots{} +@FIXME +@end deffn + +@deffn {Scheme function} xml-parse-more parser input +Equivalent to: + +@lisp +(xml-primitive-parse parser input #f) +@end lisp + +@noindent +unless @var{input} is an end-of-file object, in which case it +is equivalent to: + +@lisp +(xml-primitive-parse parser "" #t) +@end lisp +@end deffn + +@deffn {Scheme function} xml-parse parser +@FIXME +@end deffn + +@deffn {Scheme function} xml-set-handler parser args@dots{} +@FIXME +@end deffn + +@node handlers +@section Expat Handlers +@WRITEME + +@deffn {Handler prototype} start-element name attrs +@FIXME +@end deffn + +@deffn {Handler prototype} end-element name +@FIXME +@end deffn + +@deffn {Handler prototype} character-data text +@FIXME +@end deffn + +@deffn {Handler prototype} processing-instruction target data +@FIXME +@end deffn + +@deffn {Handler prototype} comment text +@FIXME +@end deffn + +@deffn {Handler prototype} start-cdata-section +@FIXME +@end deffn + +@deffn {Handler prototype} end-cdata-section +@FIXME +@end deffn + +@deffn {Handler prototype} default text +@FIXME +@end deffn + +@deffn {Handler prototype} default-expand text +@FIXME +@end deffn + +@deffn {Handler prototype} unparsed-entity-decl entity-name base @ + system-id public-id notation-name +@FIXME +@end deffn + +@deffn {Handler prototype} notation-decl notation-name base @ + system-id public-id +@FIXME +@end deffn + +@deffn {Handler prototype} start-namespace prefix uri +@FIXME +@end deffn + +@deffn {Handler prototype} end-namespace prefix +@FIXME +@end deffn + +@deffn {Handler prototype} skipped-entity entity-name parameter? +@FIXME +@end deffn + +@deffn {Handler prototype} not-standalone +@FIXME +@end deffn + +@deffn {Handler prototype} xml-decl version encoding detail +@FIXME +@end deffn + +@deffn {Handler prototype} start-doctype-decl name sysid pubid @ + has-internal-subset? +@FIXME +@end deffn + +@deffn {Handler prototype} end-doctype-decl +@FIXME +@end deffn + +@deffn {Handler prototype} attlist-decl el-name att-name att-type detail +@FIXME +@end deffn + +@deffn {Handler prototype} entity-decl name param? value base sys-id pub-id @ + notation +@FIXME +@end deffn + diff --git a/doc/fdl.texi b/doc/fdl.texi new file mode 100644 index 0000000..7da8738 --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,449 @@ +@setfilename fdl.info +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page |