\input texinfo @c -*- Texinfo -*-
-@finalout
@setfilename gasp.info
@c
@c This file documents the assembly preprocessor "GASP"
@c
-@c Copyright (c) 1994 Free Software Foundation, Inc.
+@c Copyright 1994, 1995, 2000, 2002 Free Software Foundation, Inc.
@c
-@c This text may be freely distributed under the terms of the GNU
-@c General Public License.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.1
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, with no Front-Cover Texts, and with no
+@c Back-Cover Texts. A copy of the license is included in the
+@c section entitled "GNU Free Documentation License".
@ifinfo
@format
START-INFO-DIR-ENTRY
-* gasp:(gasp). The GNU Assembler Preprocessor
+* gasp: (gasp). The GNU Assembler Preprocessor
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@syncodeindex ky cp
@syncodeindex fn cp
+@finalout
@setchapternewpage odd
@settitle GASP
@titlepage
@c FIXME boring title
@title GASP, an assembly preprocessor
-@c FIXME! Get a version number, global-replace '??'
-@subtitle for GASP version ??
+@subtitle for GASP version 1
@sp 1
-@subtitle January 1994
+@subtitle March 1994
@author Roland Pesch
@page
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, with no Front-Cover Texts, and with no
+ Back-Cover Texts. A copy of the license is included in the
+ section entitled "GNU Free Documentation License".
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
@end titlepage
@ifinfo
-Copyright @copyright{} 1994 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc.
@ignore
Permission is granted to process this file through TeX and print the
(this paragraph not being relevant to the printed manual).
@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, with no Front-Cover Texts, and with no
+ Back-Cover Texts. A copy of the license is included in the
+ section entitled "GNU Free Documentation License".
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
@node Top
@top GASP
GASP is a preprocessor for assembly programs.
-This file describes version ?? of GASP.
+This file describes version 1 of GASP.
Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
* Overview:: What is GASP?
* Invoking GASP:: Command line options.
* Commands:: Preprocessor commands.
+* GNU Free Documentation License:: GNU Free Documentation License
* Index:: Index.
@end menu
@end ifinfo
penalty of added complexity in the assembler you use for compiler
output.
+@emph{Note} The use of @sc{gasp} has now been deprecated. Anything
+that it could do can now be done by the macro facilities built into
+@sc{gas} itself. At some point in the future the @{gasp} sources will
+be removed entirely from the binutils distribution.
+
Here is a small example to give the flavor of @sc{gasp}. This input to
@sc{gasp}
@example
.MACRO saveregs from=8 to=14
count .ASSIGNA \from
- ; save r\from..r\to
+ ! save r\from..r\to
.AWHILE \&count LE \to
mov r\&count,@@-sp
count .ASSIGNA \&count + 1
.AENDW
.ENDM
- saveregs from=9
- saveregs 1,5
+ saveregs from=12
- .RADIX Q
-bar: mov #H'dead+12,r0
-foo .SDATAC "hello"<12>
+bar: mov #H'dead+10,r0
+foo .SDATAC "hello"<10>
.END
@end example
@end cartouche
@cartouche
@example
- ; save r9..r14
- mov r9,@@-sp
- mov r10,@@-sp
- mov r11,@@-sp
+ ! save r12..r14
mov r12,@@-sp
mov r13,@@-sp
mov r14,@@-sp
- ; save r1..r5
- mov r1,@@-sp
- mov r2,@@-sp
- mov r3,@@-sp
- mov r4,@@-sp
- mov r5,@@-sp
bar: mov #57005+10,r0
foo: .byte 6,104,101,108,108,111,10
@c FIXME! GASP filename suffix convention?
@example
-$ gasp prog.sp | as -o prog.o
+$ gasp prog.asm | as -o prog.o
@end example
Naturally, there are also a few command-line options to allow you to
possibilities for the @sc{gasp} command line.
@example
-gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ] @var{infile} @dots{}
+gasp [ -a | --alternate ]
+ [ -c @var{char} | --commentchar @var{char} ]
+ [ -d | --debug ] [ -h | --help ] [ -M | --mri ]
+ [ -o @var{outfile} | --output @var{outfile} ]
+ [ -p | --print ] [ -s | --copysource ]
+ [ -u | --unreasonable ] [ -v | --version ]
+ @var{infile} @dots{}
@end example
-@c FIXME!! Aren't all GNU programs supposed to have a -V or --version
-@c option, that reports version info and exits?
-
@ftable @code
@item @var{infile} @dots{}
@c FIXME! Why not stdin as default infile?
Mark the end of each input file with the preprocessor command
@code{.END}. @xref{Other Commands,, Miscellaneous commands}.
-@item -c
-@c FIXME! Shouldn't there be an option to set the prefix char so it can
-@c always be the comment char for whatever assembly version we have?
-Copy the source lines to the output file. Use this option
-to see the effect of each preprocessor line on the @sc{gasp} output.
-@sc{gasp} marks the lines copied from the source file with @samp{!} at
-the beginning, to help you distinguish them from the rest of the output.
+@item -a
+@itemx --alternate
+Use alternative macro syntax. @xref{Alternate,, Alternate macro
+syntax}, for a discussion of how this syntax differs from the default
+@sc{gasp} syntax.
+
+@cindex comment character, changing
+@cindex semicolon, as comment
+@cindex exclamation mark, as comment
+@cindex shriek, as comment
+@cindex bang, as comment
+@cindex @code{!} default comment char
+@cindex @code{;} as comment char
+@item -c '@var{char}'
+@itemx --commentchar '@var{char}'
+Use @var{char} as the comment character. The default comment character
+is @samp{!}. For example, to use a semicolon as the comment character,
+specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since
+assembler command characters often have special significance to command
+shells, it is a good idea to quote or escape @var{char} when you specify
+a comment character.
+
+For the sake of simplicity, all examples in this manual use the default
+comment character @samp{!}.
+
+@item -d
+@itemx --debug
+Show debugging statistics. In this version of @sc{gasp}, this option
+produces statistics about the string buffers that @sc{gasp} allocates
+internally. For each defined buffersize @var{s}, @sc{gasp} shows the
+number of strings @var{n} that it allocated, with a line like this:
+
+@example
+strings size @var{s} : @var{n}
+@end example
+
+@noindent
+@sc{gasp} displays these statistics on the standard error stream, when
+done preprocessing.
+
+@item -h
+@itemx --help
+Display a summary of the @sc{gasp} command line options.
+
+@item -M
+@itemx --mri
+Use MRI compatibility mode. Using this option causes @sc{gasp} to
+accept the syntax and pseudo-ops used by the Microtec Research
+@code{ASM68K} assembler.
@item -o @var{outfile}
+@itemx --output @var{outfile}
Write the output in a file called @var{outfile}. If you do not use the
@samp{-o} option, @sc{gasp} writes its output on the standard output
stream.
@item -p
+@itemx --print
Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
-specify @samp{-c} to copy source lines to its output. With @samp{-c
+specify @samp{-s} to copy source lines to its output. With @samp{-s
-p}, @sc{gasp} displays the line number of each source line copied
-(immediately after the @samp{!} that marks source lines in the output).
+(immediately after the comment character at the beginning of the line).
@item -s
-Show statistics. In this version of @sc{gasp}, this option produces
-statistics about the string buffers that @sc{gasp} allocates internally.
-For each defined buffersize @var{s}, @sc{gasp} shows the number of
-strings @var{n} that it allocated, with a line like this:
-
-@example
-strings size @var{s} : @var{n}
-@end example
-
-@noindent
-@sc{gasp} displays these statistics on the standard error stream, when
-done preprocessing.
+@itemx --copysource
+Copy the source lines to the output file. Use this option
+to see the effect of each preprocessor line on the @sc{gasp} output.
+@sc{gasp} places a comment character (@samp{!} by default) at
+the beginning of each source line it copies, so that you can use this
+option and still assemble the result.
@item -u
+@itemx --unreasonable
Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
macros inside other macro definitions, the preprocessor normally
includes a sanity check. If your program requires more than 1,000
nested expansions, @sc{gasp} normally exits with an error message. Use
this option to turn off this check, allowing unlimited nested
expansions.
+
+@item -v
+@itemx --version
+Display the @sc{gasp} version number.
@end ftable
@node Commands
* Listings::
* Other Commands::
* Syntax Details::
+* Alternate::
@end menu
@node Conditionals
When you compare strings, only two conditional @var{cmp} comparison
operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
-are identical), and @samp{NE} (the converse).
+are identical), and @samp{NE} (the opposite).
When you compare two expressions, @emph{both expressions must be
absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
@itemx .AENDR
If you simply need to repeat the same block of assembly over and over a
fixed number of times, sandwich one instance of the repeated block
-between these @code{.AREPEAT} and @code{.AENDR}. Specify the number of
+between @code{.AREPEAT} and @code{.AENDR}. Specify the number of
copies as @var{aexp} (which must be an absolute expression). For
example, this repeats two assembly statements three times in succession:
@node Variables
@section Preprocessor variables
-You can use variables in @sc{gasp} to represent the results of
-expressions, strings, or registers.
-
-There are two kinds of preprocessor variable:
+You can use variables in @sc{gasp} to represent strings, registers, or
+the results of expressions.
-@c FIXME! Is this crud true about conditional comparisons vs variables?
+You must distinguish two kinds of variables:
@enumerate
@item
Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this
assembly output.
@item
-Variables defined as macro arguments, or with @code{.ASSIGNC} or
-@code{.ASSIGNA}. To evaluate this kind of variable, write @samp{\&} before
-the variable name; for example,
+Variables for use during preprocessing. You can define these
+with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
+kind of variable, write @samp{\&} before the variable name; for example,
@cartouche
@example
.AENDW
@end example
@end cartouche
+
+@sc{gasp} treats macro arguments almost the same way, but to evaluate
+them you use the prefix @samp{\} rather than @samp{\&}.
+@xref{Macros,, Defining your own directives}.
@end enumerate
@ftable @code
name if you wish; the first example above could have started @samp{eg:}
with the same effect.
+@c pagebreak makes for better aesthetics---ensures macro and expansion together
+@page
@node Macros
@section Defining your own directives
The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
-that generate assembly output, and that you can use with a syntax
+that generate assembly output. You can use these macros with a syntax
similar to built-in @sc{gasp} or assembler directives. For example,
this definition specifies a macro @code{SUM} that adds together a range of
consecutive registers:
@cartouche
@example
.MACRO SUM FROM=0, TO=9
- ; \FROM \TO
+ ! \FROM \TO
mov r\FROM,r10
COUNT .ASSIGNA \FROM+1
.AWHILE \&COUNT LE \TO
@cartouche
@example
- ; 0 5
+ ! 0 5
mov r0,r10
add r1,r10
add r2,r10
@item .MACRO PLUS1 P, P1
@itemx .MACRO PLUS1 P P1
Either statement begins the definition of a macro called @code{PLUS1},
-which takes two arguments; within the macro definition, these arguments
-are evaluated as @samp{\&P} and @samp{\&P1}.
+which takes two arguments; within the macro definition, write
+@samp{\P} or @samp{\P1} to evaluate the arguments.
@item .MACRO RESERVE_STR P1=0 P2
Begin the definition of a macro called @code{RESERVE_STR}, with two
arguments. The first argument has a default value, but not the second.
After the definition is complete, you can call the macro either as
-@samp{RESERVE_STR @var{a},@var{b}} (with @samp{\&P1} evaluating to
-@var{a} and @samp{\&P2} evaluating to @var{b}), or as @samp{RESERVE_STR
-,@var{b}} (with @samp{\&P1} evaluating as the default, in this case
-@samp{0}, and @samp{\&P2} evaluating to @var{b}).
+@samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to
+@var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR
+,@var{b}} (with @samp{\P1} evaluating as the default, in this case
+@samp{0}, and @samp{\P2} evaluating to @var{b}).
@end table
-When you call a macro, the values are assigned by position to each
-argument name. Macro arguments are preprocessor variables in the same
-way as variables you define with @samp{.ASSIGNA} or @samp{.ASSIGNC}, and
-you can therefore use them in conditionals or for loop control.
+When you call a macro, you can specify the argument values either by
+position, or by keyword. For example, @samp{SUM 9,17} is equivalent to
+@samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables
+similar to the variables you define with @samp{.ASSIGNA} or
+@samp{.ASSIGNC}; in particular, you can use them in conditionals or for
+loop control. (The only difference is the prefix you write to evaluate
+the variable: for a macro argument, write @samp{\@var{argname}}, but for
+a preprocessor variable, write @samp{\&@var{varname}}.)
@item @var{name} .MACRO
@itemx @var{name} .MACRO ( @var{macargs} @dots{} )
An alternative form of introducing a macro definition: specify the macro
name in the label position, and the arguments (if any) between
parentheses after the name. Defaulting rules and usage work the same
-way as for the alternate macro definition syntax.
+way as for the other macro definition syntax.
@item .ENDM
Mark the end of a macro definition.
@sc{gasp} maintains a counter of how many macros it has
executed in this pseudo-variable; you can copy that number to your
output with @samp{\@@}, but @emph{only within a macro definition}.
+
+@item LOCAL @var{name} [ , @dots{} ]
+@emph{Warning: @code{LOCAL} is only available if you select ``alternate
+macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
+Alternate macro syntax}.
+
+Generate a string replacement for each of the @var{name} arguments, and
+replace any instances of @var{name} in each macro expansion. The
+replacement string is unique in the assembly, and different for each
+separate macro expansion. @code{LOCAL} allows you to write macros that
+define symbols, without fear of conflict between separate macro expansions.
@end ftable
@node Data
@node Listings
@section Assembly listing control
-The @sc{gasp} listing-control directives map straightforwardly to
+The @sc{gasp} listing-control directives correspond to
related @sc{gnu} @code{as} directives.
@ftable @code
@section Miscellaneous commands
@ftable @code
+@item .ALTERNATE
+Use the alternate macro syntax henceforth in the assembly.
+@xref{Alternate,, Alternate macro syntax}.
+
@item .ORG
@c FIXME! This is very strange, since _GAS_ understands .org
This command is recognized, but not yet implemented. @sc{gasp}
@cindex comments
The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
-A comment begins with the first unquoted @samp{;} or @samp{\;}, and
-extends to the end of a line. The two kinds of comment markers lead to
-slightly different treatment:
+A comment begins with the first unquoted comment character (@samp{!} by
+default), or an escaped or doubled comment character (@samp{\!} or
+@samp{!!} by default), and extends to the end of a line. You can
+specify what comment character to use with the @samp{-c} option
+(@pxref{Invoking GASP,, Command Line Options}). The two kinds of
+comment markers lead to slightly different treatment:
@table @code
-@item ;
-Generate an assembly comment in the @sc{gasp} output. @sc{gasp} evaluates any
-preprocessor variables (macro arguments, or variables defined with
-@code{.ASSIGNA} or @code{.ASSIGNC}) present. For example, a macro that
-begins like this
+@item !
+A single, un-escaped comment character generates an assembly comment in
+the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables
+(macro arguments, or variables defined with @code{.ASSIGNA} or
+@code{.ASSIGNC}) present. For example, a macro that begins like this
@example
.MACRO SUM FROM=0, TO=9
- ; \FROM \TO
+ ! \FROM \TO
@end example
@noindent
issues as the first line of output a comment that records the
values you used to call the macro.
-@item \;
-This marks a @sc{gasp} source comment. @sc{gasp} does not copy such
-comments to the assembly output.
+@c comments, preprocessor-only
+@c preprocessor-only comments
+@c GASP-only comments
+@item \!
+@itemx !!
+Either an escaped comment character, or a double comment character,
+marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments
+to the assembly output.
@end table
@cindex continuation character
Occasionally you may want to prevent @sc{gasp} from preprocessing some
particular bit of text. To @emph{copy literally} from the @sc{gasp}
source to its output, place @samp{\(} before the string to copy, and
-@samp{)} at the end. For example, write @samp{\(\;)} if you need the
-characters @samp{\;} in your assembly output.
+@samp{)} at the end. For example, write @samp{\(\!)} if you need the
+characters @samp{\!} in your assembly output.
@cindex symbol separator
@cindex text, separating from symbols
numeric byte value as an absolute expression between angle brackets
(@code{<@var{expr}>}. Directives that output strings allow you to
specify any number of either kind of value, in whatever order is
-convenient, and concatenate the result.
+convenient, and concatenate the result. (Alternate syntax mode
+introduces a number of alternative string notations; @pxref{Alternate,,
+Alternate macro syntax}.)
@c Details of numeric notation, e.g. base prefixes
You can write @dfn{numeric constants} either in a specific base, or in
recent @code{.RADIX}).
To write a number in a @emph{specific base}, use the pattern
-@code{'@var{s}@var{ddd}}: a single quote, followed by a base specifier
-character @var{s}, followed by digits @var{ddd}. The base specifier
+@code{@var{s}'@var{ddd}}: a base specifier character @var{s}, followed
+by a single quote followed by digits @var{ddd}. The base specifier
character matches those you can specify with @code{.RADIX}: @samp{B} for
base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
16. (You can write this character in lower case if you prefer.)
+You can write floating point constants using the same syntax recognised
+by GAS @ref{Flonums,,Flonums,as,The GNU Assembler.}. A constraint is
+that these constants will be interpreted as decimal values irrespective
+of the currently selected base.
+
@c FIXME! What are rules for recognizing number in deflt base? Whatever
@c is left over after parsing other things??
@ftable @code
@item .LEN("@var{str}")
-The length of string @code{"@var{str}"}, as an absolute expression. For
-example, @samp{.RES.B .LEN("sample")} reserves six bytes of memory.
+Calculate the length of string @code{"@var{str}"}, as an absolute
+expression. For example, @samp{.RES.B .LEN("sample")} reserves six
+bytes of memory.
@item .INSTR("@var{string}", "@var{seg}", @var{ix})
Search for the first occurrence of @var{seg} after position @var{ix} of
extending for @var{len} bytes.
@end ftable
+@node Alternate
+@section Alternate macro syntax
+
+If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command
+line, the preprocessor uses somewhat different syntax. This syntax is
+reminiscent of the syntax of Phar Lap macro assembler, but it
+is @emph{not} meant to be a full emulation of Phar Lap or similar
+assemblers. In particular, @sc{gasp} does not support directives such
+as @code{DB} and @code{IRP}, even in alternate syntax mode.
+
+In particular, @samp{-a} (or @samp{--alternate}) elicits these
+differences:
+
+@table @emph
+@item Preprocessor directives
+You can use @sc{gasp} preprocessor directives without a leading @samp{.}
+dot. For example, you can write @samp{SDATA} with the same effect as
+@samp{.SDATA}.
+
+@item LOCAL
+One additional directive, @code{LOCAL}, is available. @xref{Macros,,
+Defining your own directives}, for an explanation of how to use
+@code{LOCAL}.
+
+@need 2000
+@item String delimiters
+You can write strings delimited in these other ways besides
+@code{"@var{string}"}:
+
+@table @code
+@item '@var{string}'
+You can delimit strings with single-quote charaters.
+
+@item <@var{string}>
+You can delimit strings with matching angle brackets.
+@end table
+
+@item single-character string escape
+To include any single character literally in a string (even if the
+character would otherwise have some special meaning), you can prefix the
+character with @samp{!} (an exclamation mark). For example, you can
+write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}.
+
+@item Expression results as strings
+You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
+and use the result as a string.
+@end table
+
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+
+ GNU Free Documentation License
+
+ Version 1.1, March 2000
+
+ Copyright (C) 2000 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.
+
+
+0. PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document "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.
+
+
+1. APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The "Document", below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as "you".
+
+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. (For example, 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.
+
+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 "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+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 has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML designed for human modification. Opaque formats include
+PostScript, PDF, proprietary formats that can be read and edited only
+by proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML 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.
+
+
+2. 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.
+
+
+3. COPYING IN QUANTITY
+
+If you publish printed copies 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 publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. 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.
+
+
+4. 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:
+
+A. 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.
+B. List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has less than five).
+C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+D. Preserve all the copyright notices of the Document.
+E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+F. Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+G. Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+H. Include an unaltered copy of this License.
+I. Preserve the section entitled "History", and its title, and add to
+ it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+K. In any section entitled "Acknowledgements" or "Dedications",
+ preserve the section's title, and preserve in the section all the
+ substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+M. Delete any section entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+N. Do not retitle any existing section as "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+5. COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled "History"
+in the various original documents, forming one section entitled
+"History"; likewise combine any sections entitled "Acknowledgements",
+and any sections entitled "Dedications". You must delete all sections
+entitled "Endorsements."
+
+
+6. COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an "aggregate", and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+
+8. TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+
+9. TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+10. FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+ Copyright (c) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+@end smallexample
+
+If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write "no Front-Cover Texts" instead of
+"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
@node Index
@unnumbered Index
@printindex cp
+
+@contents
@bye