diff options
Diffstat (limited to 'gas/doc/gasp.texi')
| -rw-r--r-- | gas/doc/gasp.texi | 1456 |
1 files changed, 0 insertions, 1456 deletions
diff --git a/gas/doc/gasp.texi b/gas/doc/gasp.texi deleted file mode 100644 index 889e997..0000000 --- a/gas/doc/gasp.texi +++ /dev/null @@ -1,1456 +0,0 @@ -\input texinfo @c -*- Texinfo -*- -@setfilename gasp.info -@c -@c This file documents the assembly preprocessor "GASP" -@c -@c Copyright 1994, 1995, 2000, 2002 Free Software Foundation, Inc. -@c -@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 -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 -@subtitle for GASP version 1 -@sp 1 -@subtitle March 1994 -@author Roland Pesch -@page - -@tex -{\parskip=0pt \hfill Cygnus Support\par -} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc. - - 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". - -@end titlepage - -@ifinfo -Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore - - 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". - - -@node Top -@top GASP - -GASP is a preprocessor for assembly programs. - -This file describes version 1 of GASP. - -Steve Chamberlain wrote GASP; Roland Pesch wrote this manual. - -@menu -* 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 - -@node Overview -@chapter What is GASP? - -The primary purpose of the @sc{gnu} assembler is to assemble the output of -other programs---notably compilers. When you have to hand-code -specialized routines in assembly, that means the @sc{gnu} assembler is -an unfriendly processor: it has no directives for macros, conditionals, -or many other conveniences that you might expect. - -In some cases you can simply use the C preprocessor, or a generalized -preprocessor like @sc{m4}; but this can be awkward, since none of these -things are designed with assembly in mind. - -@sc{gasp} fills this need. It is expressly designed to provide the -facilities you need with hand-coded assembly code. Implementing it as a -preprocessor, rather than part of the assembler, allows the maximum -flexibility: you can use it with hand-coded assembly, without paying a -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 @sc{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} - -@cartouche -@example - .MACRO saveregs from=8 to=14 -count .ASSIGNA \from - ! save r\from..r\to - .AWHILE \&count LE \to - mov r\&count,@@-sp -count .ASSIGNA \&count + 1 - .AENDW - .ENDM - - saveregs from=12 - -bar: mov #H'dead+10,r0 -foo .SDATAC "hello"<10> - .END -@end example -@end cartouche - -@noindent -generates this assembly program: - -@cartouche -@example - ! save r12..r14 - mov r12,@@-sp - mov r13,@@-sp - mov r14,@@-sp - -bar: mov #57005+10,r0 -foo: .byte 6,104,101,108,108,111,10 -@end example -@end cartouche - -@node Invoking GASP -@chapter Command Line Options - -@c FIXME! Or is there a simpler way, calling from GAS option? -The simplest way to use @sc{gasp} is to run it as a filter and assemble -its output. In Unix and its ilk, you can do this, for example: - -@c FIXME! GASP filename suffix convention? -@example -$ gasp prog.asm | as -o prog.o -@end example - -Naturally, there are also a few command-line options to allow you to -request variations on this basic theme. Here is the full set of -possibilities for the @sc{gasp} command line. - -@example -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 - -@ftable @code -@item @var{infile} @dots{} -@c FIXME! Why not stdin as default infile? -The input file names. You must specify at least one input file; if you -specify more, @sc{gasp} preprocesses them all, concatenating the output -in the order you list the @var{infile} arguments. - -Mark the end of each input file with the preprocessor command -@code{.END}. @xref{Other Commands,, Miscellaneous commands}. - -@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{-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 comment character at the beginning of the line). - -@item -s -@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 -@chapter Preprocessor Commands - -@sc{gasp} commands have a straightforward syntax that fits in well with -assembly conventions. In general, a command extends for a line, and may -have up to three fields: an optional label, the command itself, and -optional arguments to the command. You can write commands in upper or -lower case, though this manual shows them in upper case. @xref{Syntax -Details,, Details of the GASP syntax}, for more information. - -@menu -* Conditionals:: -* Loops:: -* Variables:: -* Macros:: -* Data:: -* Listings:: -* Other Commands:: -* Syntax Details:: -* Alternate:: -@end menu - -@node Conditionals -@section Conditional assembly - -The conditional-assembly directives allow you to include or exclude -portions of an assembly depending on how a pair of expressions, or a -pair of strings, compare. - -The overall structure of conditionals is familiar from many other -contexts. @code{.AIF} marks the start of a conditional, and precedes -assembly for the case when the condition is true. An optional -@code{.AELSE} precedes assembly for the converse case, and an -@code{.AENDI} marks the end of the condition. - -@c FIXME! Why doesn't -u turn off this check? -You may nest conditionals up to a depth of 100; @sc{gasp} rejects -nesting beyond that, because it may indicate a bug in your macro -structure. - -@c FIXME! Why isn't there something like cpp's -D option? Conditionals -@c would be much more useful if there were. -Conditionals are primarily useful inside macro definitions, where you -often need different effects depending on argument values. -@xref{Macros,, Defining your own directives}, for details about defining -macros. - -@ftable @code -@item .AIF @var{expra} @var{cmp} @var{exprb} -@itemx .AIF "@var{stra}" @var{cmp} "@var{strb}" - -The governing condition goes on the same line as the @code{.AIF} -preprocessor command. You may compare either two strings, or two -expressions. - -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 opposite). - -When you compare two expressions, @emph{both expressions must be -absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You -can use these @var{cmp} comparison operators with expressions: - -@ftable @code -@item EQ -Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and -@var{strb} identical?) - -@item NE -Are @var{expra} and @var{exprb} different? (For strings, are @var{stra} -and @var{strb} different? - -@item LT -Is @var{expra} less than @var{exprb}? (Not allowed for strings.) - -@item LE -Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.) - -@item GT -Is @var{expra} greater than @var{exprb}? (Not allowed for strings.) - -@item GE -Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for -strings.) -@end ftable - -@item .AELSE -Marks the start of assembly code to be included if the condition fails. -Optional, and only allowed within a conditional (between @code{.AIF} and -@code{.AENDI}). - -@item .AENDI -Marks the end of a conditional assembly. -@end ftable - -@node Loops -@section Repetitive sections of assembly - -Two preprocessor directives allow you to repeatedly issue copies of the -same block of assembly code. - -@ftable @code -@item .AREPEAT @var{aexp} -@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 @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: - -@cartouche -@example - .AREPEAT 3 - rotcl r2 - div1 r0,r1 - .AENDR -@end example -@end cartouche - -@item .AWHILE @var{expra} @var{cmp} @var{exprb} -@itemx .AENDW -@itemx .AWHILE @var{stra} @var{cmp} @var{strb} -@itemx .AENDW -To repeat a block of assembly depending on a conditional test, rather -than repeating it for a specific number of times, use @code{.AWHILE}. -@code{.AENDW} marks the end of the repeated block. The conditional -comparison works exactly the same way as for @code{.AIF}, with the same -comparison operators (@pxref{Conditionals,, Conditional assembly}). - -Since the terms of the comparison must be absolute expression, -@code{.AWHILE} is primarily useful within macros. @xref{Macros,, -Defining your own directives}. -@end ftable - -@cindex loops, breaking out of -@cindex breaking out of loops -You can use the @code{.EXITM} preprocessor directive to break out of -loops early (as well as to break out of macros). @xref{Macros,, -Defining your own directives}. - -@node Variables -@section Preprocessor variables - -You can use variables in @sc{gasp} to represent strings, registers, or -the results of expressions. - -You must distinguish two kinds of variables: -@enumerate -@item -Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this -kind of variable in your assembly output, simply mention its name. For -example, these two lines define and use a variable @samp{eg}: - -@cartouche -@example -eg .EQU FLIP-64 - @dots{} - mov.l eg,r0 -@end example -@end cartouche - -@emph{Do not use} this kind of variable in conditional expressions or -while loops; @sc{gasp} only evaluates these variables when writing -assembly output. - -@item -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 -opcit .ASSIGNA 47 - @dots{} - .AWHILE \&opcit GT 0 - @dots{} - .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 -@item @var{pvar} .EQU @var{expr} -@c FIXME! Anything to beware of re GAS directive of same name? -Assign preprocessor variable @var{pvar} the value of the expression -@var{expr}. There are no restrictions on redefinition; use @samp{.EQU} -with the same @var{pvar} as often as you find it convenient. - -@item @var{pvar} .ASSIGN @var{expr} -Almost the same as @code{.EQU}, save that you may not redefine -@var{pvar} using @code{.ASSIGN} once it has a value. -@c FIXME!! Supposed to work this way, apparently, but on 9feb94 works -@c just like .EQU - -@item @var{pvar} .ASSIGNA @var{aexpr} -Define a variable with a numeric value, for use during preprocessing. -@var{aexpr} must be an absolute expression. You can redefine variables -with @code{.ASSIGNA} at any time. - -@item @var{pvar} .ASSIGNC "@var{str}" -Define a variable with a string value, for use during preprocessing. -You can redefine variables with @code{.ASSIGNC} at any time. - -@item @var{pvar} .REG (@var{register}) -Use @code{.REG} to define a variable that represents a register. In -particular, @var{register} is @emph{not evaluated} as an expression. -You may use @code{.REG} at will to redefine register variables. -@end ftable - -All these directives accept the variable name in the ``label'' position, -that is at the left margin. You may specify a colon after the variable -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. 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 - mov r\FROM,r10 -COUNT .ASSIGNA \FROM+1 - .AWHILE \&COUNT LE \TO - add r\&COUNT,r10 -COUNT .ASSIGNA \&COUNT+1 - .AENDW - .ENDM -@end example -@end cartouche - -@noindent -With that definition, @samp{SUM 0,5} generates this assembly output: - -@cartouche -@example - ! 0 5 - mov r0,r10 - add r1,r10 - add r2,r10 - add r3,r10 - add r4,r10 - add r5,r10 -@end example -@end cartouche - -@ftable @code -@item .MACRO @var{macname} -@itemx .MACRO @var{macname} @var{macargs} @dots{} -Begin the definition of a macro called @var{macname}. If your macro -definition requires arguments, specify their names after the macro name, -separated by commas or spaces. You can supply a default value for any -macro argument by following the name with @samp{=@var{deflt}}. For -example, these are all valid @code{.MACRO} statements: - -@table @code -@item .MACRO COMM -Begin the definition of a macro called @code{COMM}, which takes no -arguments. - -@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, 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}). -@end table - -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{} ) -@c FIXME check: I think no error _and_ no args recognized if I use form -@c NAME .MACRO ARG ARG -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 other macro definition syntax. - -@item .ENDM -Mark the end of a macro definition. - -@item .EXITM -Exit early from the current macro definition, @code{.AREPEAT} loop, or -@code{.AWHILE} loop. - -@cindex number of macros executed -@cindex macros, count executed -@item \@@ -@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 -@section Data output - -In assembly code, you often need to specify working areas of memory; -depending on the application, you may want to initialize such memory or -not. @sc{gasp} provides preprocessor directives to help you avoid -repetitive coding for both purposes. - -You can use labels as usual to mark the data areas. - -@menu -* Initialized:: -* Uninitialized:: -@end menu - -@node Initialized -@subsection Initialized data - -These are the @sc{gasp} directives for initialized data, and the standard -@sc{gnu} assembler directives they expand to: - -@ftable @code -@item .DATA @var{expr}, @var{expr}, @dots{} -@itemx .DATA.B @var{expr}, @var{expr}, @dots{} -@itemx .DATA.W @var{expr}, @var{expr}, @dots{} -@itemx .DATA.L @var{expr}, @var{expr}, @dots{} -Evaluate arithmetic expressions @var{expr}, and emit the corresponding -@code{as} directive (labelled with @var{lab}). The unqualified -@code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte}; -@code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits -@samp{.long}. - -For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}. - -@item .DATAB @var{repeat}, @var{expr} -@itemx .DATAB.B @var{repeat}, @var{expr} -@itemx .DATAB.W @var{repeat}, @var{expr} -@itemx .DATAB.L @var{repeat}, @var{expr} -@c FIXME! Looks like gasp accepts and ignores args after 2nd. -Make @code{as} emit @var{repeat} copies of the value of the expression -@var{expr} (using the @code{as} directive @code{.fill}). -@samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats -two-byte values; and @samp{.DATAB.L} repeats four-byte values. -@samp{.DATAB} without a suffix repeats four-byte values, just like -@samp{.DATAB.L}. - -@c FIXME! Allowing zero might be useful for edge conditions in macros. -@var{repeat} must be an absolute expression with a positive value. - -@item .SDATA "@var{str}" @dots{} -String data. Emits a concatenation of bytes, precisely as you specify -them (in particular, @emph{nothing is added to mark the end} of the -string). @xref{Constants,, String and numeric constants}, for details -about how to write strings. @code{.SDATA} concatenates multiple -arguments, making it easy to switch between string representations. You -can use commas to separate the individual arguments for clarity, if you -choose. - -@item .SDATAB @var{repeat}, "@var{str}" @dots{} -Repeated string data. The first argument specifies how many copies of -the string to emit; the remaining arguments specify the string, in the -same way as the arguments to @code{.SDATA}. - -@item .SDATAZ "@var{str}" @dots{} -Zero-terminated string data. Just like @code{.SDATA}, except that -@code{.SDATAZ} writes a zero byte at the end of the string. - -@item .SDATAC "@var{str}" @dots{} -Count-prefixed string data. Just like @code{.SDATA}, except that -@sc{gasp} precedes the string with a leading one-byte count. For -example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the -count field is only one byte, you can only use @code{.SDATAC} for -strings less than 256 bytes in length. -@end ftable - -@node Uninitialized -@subsection Uninitialized data - -@c FIXME! .space different on some platforms, notably HPPA. Config? -Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ} -directives to reserve memory and leave it uninitialized. @sc{gasp} -resolves these directives to appropriate calls of the @sc{gnu} -@code{as} @code{.space} directive. - -@ftable @code -@item .RES @var{count} -@itemx .RES.B @var{count} -@itemx .RES.W @var{count} -@itemx .RES.L @var{count} -Reserve room for @var{count} uninitialized elements of data. The -suffix specifies the size of each element: @code{.RES.B} reserves -@var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes, -and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a -suffix is equivalent to @code{.RES.L}. - -@item .SRES @var{count} -@itemx .SRES.B @var{count} -@itemx .SRES.W @var{count} -@itemx .SRES.L @var{count} -@c FIXME! This is boring. Shouldn't it at least have a different -@c default size? (e.g. the "S" suggests "string", for which .B -@c would be more appropriate) -@code{.SRES} is a synonym for @samp{.RES}. - -@item .SRESC @var{count} -@itemx .SRESC.B @var{count} -@itemx .SRESC.W @var{count} -@itemx .SRESC.L @var{count} -Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. - -@item .SRESZ @var{count} -@itemx .SRESZ.B @var{count} -@itemx .SRESZ.W @var{count} -@itemx .SRESZ.L @var{count} -Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. -@end ftable - -@node Listings -@section Assembly listing control - -The @sc{gasp} listing-control directives correspond to -related @sc{gnu} @code{as} directives. - -@ftable @code -@item .PRINT LIST -@itemx .PRINT NOLIST -Print control. This directive emits the @sc{gnu} @code{as} directive -@code{.list} or @code{.nolist}, according to its argument. @xref{List,, -@code{.list}, as.info, Using as}, for details on how these directives -interact. - -@item .FORM LIN=@var{ln} -@itemx .FORM COL=@var{cols} -@itemx .FORM LIN=@var{ln} COL=@var{cols} -Specify the page size for assembly listings: @var{ln} represents the -number of lines, and @var{cols} the number of columns. You may specify -either page dimension independently, or both together. If you do not -specify the number of lines, @sc{gasp} assumes 60 lines; if you do not -specify the number of columns, @sc{gasp} assumes 132 columns. -(Any values you may have specified in previous instances of @code{.FORM} -do @emph{not} carry over as defaults.) Emits the @code{.psize} -assembler directive. - -@item .HEADING @var{string} -Specify @var{string} as the title of your assembly listings. Emits -@samp{.title "@var{string}"}. - -@item .PAGE -Force a new page in assembly listings. Emits @samp{.eject}. -@end ftable - -@node Other Commands -@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} -generates an error message for programs that use @code{.ORG}. - -@item .RADIX @var{s} -@c FIXME no test cases in testsuite/gasp -@sc{gasp} understands numbers in any of base two, eight, ten, or -sixteen. You can encode the base explicitly in any numeric constant -(@pxref{Constants,, String and numeric constants}). If you write -numbers without an explicit indication of the base, the most recent -@samp{.RADIX @var{s}} command determines how they are interpreted. -@var{s} is a single letter, one of the following: - -@table @code -@item .RADIX B -Base 2. - -@item .RADIX Q -Base 8. - -@item .RADIX D -Base 10. This is the original default radix. - -@item .RADIX H -Base 16. -@end table - -You may specify the argument @var{s} in lower case (any of @samp{bqdh}) -with the same effects. - -@item .EXPORT @var{name} -@itemx .GLOBAL @var{name} -@c FIXME! No test cases in testsuite/gasp -Declare @var{name} global (emits @samp{.global @var{name}}). The two -directives are synonymous. - -@item .PROGRAM -No effect: @sc{gasp} accepts this directive, and silently ignores it. - -@item .END -Mark end of each preprocessor file. @sc{gasp} issues a warning if it -reaches end of file without seeing this command. - -@item .INCLUDE "@var{str}" -Preprocess the file named by @var{str}, as if its contents appeared -where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum -limit of 30 stacked include files, as a sanity check. -@c FIXME! Why is include depth not affected by -u? - -@item .ALIGN @var{size} -@c FIXME! Why is this not utterly pointless? -Evaluate the absolute expression @var{size}, and emit the assembly -instruction @samp{.align @var{size}} using the result. -@end ftable - -@node Syntax Details -@section Details of the GASP syntax - -Since @sc{gasp} is meant to work with assembly code, its statement -syntax has no surprises for the assembly programmer. - -@cindex whitespace -@emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially -significant, in that it delimits up to three fields in a line. The -amount of whitespace does not matter; you may line up fields in separate -lines if you wish, but @sc{gasp} does not require that. - -@cindex fields of @sc{gasp} source line -@cindex label field -The @emph{first field}, an optional @dfn{label}, must be flush left in a -line (with no leading whitespace) if it appears at all. You may use a -colon after the label if you wish; @sc{gasp} neither requires the colon -nor objects to it (but will not include it as part of the label name). - -@cindex directive field -The @emph{second field}, which must appear after some whitespace, -contains a @sc{gasp} or assembly @dfn{directive}. - -@cindex argument fields -Any @emph{further fields} on a line are @dfn{arguments} to the -directive; you can separate them from one another using either commas or -whitespace. - -@menu -* Markers:: -* Constants:: -* Symbols:: -* Expressions:: -* String Builtins:: -@end menu - -@node Markers -@subsection Special syntactic markers - -@sc{gasp} recognizes a few special markers: to delimit comments, to -continue a statement on the next line, to separate symbols from other -characters, and to copy text to the output literally. (One other -special marker, @samp{\@@}, works only within macro definitions; -@pxref{Macros,, Defining your own directives}.) - -@cindex comments -The trailing part of any @sc{gasp} source line may be a @dfn{comment}. -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 ! -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 -@end example - -@noindent -issues as the first line of output a comment that records the -values you used to call the macro. - -@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 -@kindex + -To @emph{continue a statement} on the next line of the file, begin the -second line with the character @samp{+}. - -@cindex literal copy to output -@cindex copying literally to output -@cindex preprocessing, avoiding -@cindex avoiding preprocessing -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. - -@cindex symbol separator -@cindex text, separating from symbols -@cindex symbols, separating from text -To @emph{separate a preprocessor variable} from text to appear -immediately after its value, write a single quote (@code{'}). For -example, @samp{.SDATA "\P'1"} writes a string built by concatenating the -value of @code{P} and the digit @samp{1}. (You cannot achieve this by -writing just @samp{\P1}, since @samp{P1} is itself a valid name for a -preprocessor variable.) - -@node Constants -@subsection String and numeric constants - -There are two ways of writing @dfn{string constants} in @sc{gasp}: as -literal text, and by numeric byte value. Specify a string literal -between double quotes (@code{"@var{str}"}). Specify an individual -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. (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 -whatever base is currently selected (either 10, or selected by the most -recent @code{.RADIX}). - -To write a number in a @emph{specific base}, use the pattern -@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?? - -@node Symbols -@subsection Symbols - -@sc{gasp} recognizes symbol names that start with any alphabetic character, -@samp{_}, or @samp{$}, and continue with any of the same characters or -with digits. Label names follow the same rules. - -@node Expressions -@subsection Arithmetic expressions in GASP - -@cindex absolute expressions -@cindex relocatable expressions -There are two kinds of expressions, depending on their result: -@dfn{absolute} expressions, which resolve to a constant (that is, they -do not involve any values unknown to @sc{gasp}), and @dfn{relocatable} -expressions, which must reduce to the form - -@example -@var{addsym}+@var{const}-@var{subsym} -@end example - -@noindent -where @var{addsym} and @var{subsym} are assembly symbols of unknown -value, and @var{const} is a constant. - -Arithmetic for @sc{gasp} expressions follows very similar rules to C. -You can use parentheses to change precedence; otherwise, arithmetic -primitives have decreasing precedence in the order of the following -list. - -@enumerate -@item -Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or -@code{~} (bitwise negation). @emph{The argument must be an absolute -expression.} - -@item -@code{*} (multiplication) and @code{/} (division). @emph{Both arguments -must be absolute expressions.} - -@item -@code{+} (addition) and @code{-} (subtraction). @emph{At least one argument -must be absolute.} -@c FIXME! Actually, subtraction doesn't check for this. - -@item -@code{&} (bitwise and). @emph{Both arguments must be absolute.} - -@item -@c FIXME! I agree ~ is a better notation than ^ for xor, but is the -@c improvement worth differing from C? -@code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in -C). @emph{Both arguments must be absolute.} -@end enumerate - -@node String Builtins -@subsection String primitives - -You can use these primitives to manipulate strings (in the argument -field of @sc{gasp} statements): - -@ftable @code -@item .LEN("@var{str}") -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 -@var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates -to the absolute result @code{2}. - -The result is @code{-1} if @var{seg} does not occur in @var{string} -after position @var{ix}. - -@item .SUBSTR("@var{string}",@var{start},@var{len}) -The substring of @var{string} beginning at byte number @var{start} and -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 |