Commit | Line | Data |
---|---|---|
252b5132 RH |
1 | \input texinfo @c -*- Texinfo -*- |
2 | @setfilename gasp.info | |
3 | @c | |
4 | @c This file documents the assembly preprocessor "GASP" | |
5 | @c | |
f7e42eb4 | 6 | @c Copyright 1994, 1995, 2000 Free Software Foundation, Inc. |
252b5132 | 7 | @c |
cf055d54 NC |
8 | @c Permission is granted to copy, distribute and/or modify this document |
9 | @c under the terms of the GNU Free Documentation License, Version 1.1 | |
10 | @c or any later version published by the Free Software Foundation; | |
11 | @c with no Invariant Sections, with no Front-Cover Texts, and with no | |
12 | @c Back-Cover Texts. A copy of the license is included in the | |
13 | @c section entitled "GNU Free Documentation License". | |
252b5132 RH |
14 | |
15 | @ifinfo | |
16 | @format | |
17 | START-INFO-DIR-ENTRY | |
18 | * gasp: (gasp). The GNU Assembler Preprocessor | |
19 | END-INFO-DIR-ENTRY | |
20 | @end format | |
21 | @end ifinfo | |
22 | ||
23 | @syncodeindex ky cp | |
24 | @syncodeindex fn cp | |
25 | ||
26 | @finalout | |
27 | @setchapternewpage odd | |
28 | @settitle GASP | |
29 | @titlepage | |
30 | @c FIXME boring title | |
31 | @title GASP, an assembly preprocessor | |
32 | @subtitle for GASP version 1 | |
33 | @sp 1 | |
34 | @subtitle March 1994 | |
35 | @author Roland Pesch | |
36 | @page | |
37 | ||
38 | @tex | |
39 | {\parskip=0pt \hfill Cygnus Support\par | |
40 | } | |
41 | @end tex | |
42 | ||
43 | @vskip 0pt plus 1filll | |
cf055d54 | 44 | Copyright @copyright{} 1994, 1995, 2000 Free Software Foundation, Inc. |
252b5132 | 45 | |
cf055d54 NC |
46 | Permission is granted to copy, distribute and/or modify this document |
47 | under the terms of the GNU Free Documentation License, Version 1.1 | |
48 | or any later version published by the Free Software Foundation; | |
49 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
50 | Back-Cover Texts. A copy of the license is included in the | |
51 | section entitled "GNU Free Documentation License". | |
252b5132 | 52 | |
252b5132 RH |
53 | @end titlepage |
54 | ||
55 | @ifinfo | |
cf055d54 | 56 | Copyright @copyright{} 1994, 1995, 2000 Free Software Foundation, Inc. |
252b5132 RH |
57 | |
58 | @ignore | |
59 | Permission is granted to process this file through TeX and print the | |
60 | results, provided the printed document carries a copying permission | |
61 | notice identical to this one except for the removal of this paragraph | |
62 | (this paragraph not being relevant to the printed manual). | |
63 | @end ignore | |
64 | ||
cf055d54 NC |
65 | Permission is granted to copy, distribute and/or modify this document |
66 | under the terms of the GNU Free Documentation License, Version 1.1 | |
67 | or any later version published by the Free Software Foundation; | |
68 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
69 | Back-Cover Texts. A copy of the license is included in the | |
70 | section entitled "GNU Free Documentation License". | |
252b5132 | 71 | |
252b5132 RH |
72 | |
73 | @node Top | |
74 | @top GASP | |
75 | ||
76 | GASP is a preprocessor for assembly programs. | |
77 | ||
78 | This file describes version 1 of GASP. | |
79 | ||
80 | Steve Chamberlain wrote GASP; Roland Pesch wrote this manual. | |
81 | ||
82 | @menu | |
83 | * Overview:: What is GASP? | |
84 | * Invoking GASP:: Command line options. | |
85 | * Commands:: Preprocessor commands. | |
cf055d54 | 86 | * GNU Free Documentation License:: GNU Free Documentation License |
252b5132 RH |
87 | * Index:: Index. |
88 | @end menu | |
89 | @end ifinfo | |
90 | ||
91 | @node Overview | |
92 | @chapter What is GASP? | |
93 | ||
94 | The primary purpose of the @sc{gnu} assembler is to assemble the output of | |
95 | other programs---notably compilers. When you have to hand-code | |
96 | specialized routines in assembly, that means the @sc{gnu} assembler is | |
97 | an unfriendly processor: it has no directives for macros, conditionals, | |
98 | or many other conveniences that you might expect. | |
99 | ||
100 | In some cases you can simply use the C preprocessor, or a generalized | |
101 | preprocessor like @sc{m4}; but this can be awkward, since none of these | |
102 | things are designed with assembly in mind. | |
103 | ||
104 | @sc{gasp} fills this need. It is expressly designed to provide the | |
105 | facilities you need with hand-coded assembly code. Implementing it as a | |
106 | preprocessor, rather than part of the assembler, allows the maximum | |
107 | flexibility: you can use it with hand-coded assembly, without paying a | |
108 | penalty of added complexity in the assembler you use for compiler | |
109 | output. | |
110 | ||
111 | Here is a small example to give the flavor of @sc{gasp}. This input to | |
112 | @sc{gasp} | |
113 | ||
114 | @cartouche | |
115 | @example | |
116 | .MACRO saveregs from=8 to=14 | |
117 | count .ASSIGNA \from | |
118 | ! save r\from..r\to | |
119 | .AWHILE \&count LE \to | |
120 | mov r\&count,@@-sp | |
121 | count .ASSIGNA \&count + 1 | |
122 | .AENDW | |
123 | .ENDM | |
124 | ||
125 | saveregs from=12 | |
126 | ||
127 | bar: mov #H'dead+10,r0 | |
128 | foo .SDATAC "hello"<10> | |
129 | .END | |
130 | @end example | |
131 | @end cartouche | |
132 | ||
133 | @noindent | |
134 | generates this assembly program: | |
135 | ||
136 | @cartouche | |
137 | @example | |
138 | ! save r12..r14 | |
139 | mov r12,@@-sp | |
140 | mov r13,@@-sp | |
141 | mov r14,@@-sp | |
142 | ||
143 | bar: mov #57005+10,r0 | |
144 | foo: .byte 6,104,101,108,108,111,10 | |
145 | @end example | |
146 | @end cartouche | |
147 | ||
148 | @node Invoking GASP | |
149 | @chapter Command Line Options | |
150 | ||
151 | @c FIXME! Or is there a simpler way, calling from GAS option? | |
152 | The simplest way to use @sc{gasp} is to run it as a filter and assemble | |
153 | its output. In Unix and its ilk, you can do this, for example: | |
154 | ||
155 | @c FIXME! GASP filename suffix convention? | |
156 | @example | |
157 | $ gasp prog.asm | as -o prog.o | |
158 | @end example | |
159 | ||
160 | Naturally, there are also a few command-line options to allow you to | |
161 | request variations on this basic theme. Here is the full set of | |
162 | possibilities for the @sc{gasp} command line. | |
163 | ||
164 | @example | |
165 | gasp [ -a | --alternate ] | |
166 | [ -c @var{char} | --commentchar @var{char} ] | |
167 | [ -d | --debug ] [ -h | --help ] [ -M | --mri ] | |
168 | [ -o @var{outfile} | --output @var{outfile} ] | |
169 | [ -p | --print ] [ -s | --copysource ] | |
170 | [ -u | --unreasonable ] [ -v | --version ] | |
171 | @var{infile} @dots{} | |
172 | @end example | |
173 | ||
174 | @ftable @code | |
175 | @item @var{infile} @dots{} | |
176 | @c FIXME! Why not stdin as default infile? | |
177 | The input file names. You must specify at least one input file; if you | |
178 | specify more, @sc{gasp} preprocesses them all, concatenating the output | |
179 | in the order you list the @var{infile} arguments. | |
180 | ||
181 | Mark the end of each input file with the preprocessor command | |
182 | @code{.END}. @xref{Other Commands,, Miscellaneous commands}. | |
183 | ||
184 | @item -a | |
185 | @itemx --alternate | |
186 | Use alternative macro syntax. @xref{Alternate,, Alternate macro | |
187 | syntax}, for a discussion of how this syntax differs from the default | |
188 | @sc{gasp} syntax. | |
189 | ||
190 | @cindex comment character, changing | |
191 | @cindex semicolon, as comment | |
192 | @cindex exclamation mark, as comment | |
193 | @cindex shriek, as comment | |
194 | @cindex bang, as comment | |
195 | @cindex @code{!} default comment char | |
196 | @cindex @code{;} as comment char | |
197 | @item -c '@var{char}' | |
198 | @itemx --commentchar '@var{char}' | |
199 | Use @var{char} as the comment character. The default comment character | |
200 | is @samp{!}. For example, to use a semicolon as the comment character, | |
201 | specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since | |
202 | assembler command characters often have special significance to command | |
203 | shells, it is a good idea to quote or escape @var{char} when you specify | |
204 | a comment character. | |
205 | ||
206 | For the sake of simplicity, all examples in this manual use the default | |
207 | comment character @samp{!}. | |
208 | ||
209 | @item -d | |
210 | @itemx --debug | |
211 | Show debugging statistics. In this version of @sc{gasp}, this option | |
212 | produces statistics about the string buffers that @sc{gasp} allocates | |
213 | internally. For each defined buffersize @var{s}, @sc{gasp} shows the | |
214 | number of strings @var{n} that it allocated, with a line like this: | |
215 | ||
216 | @example | |
217 | strings size @var{s} : @var{n} | |
218 | @end example | |
219 | ||
220 | @noindent | |
221 | @sc{gasp} displays these statistics on the standard error stream, when | |
222 | done preprocessing. | |
223 | ||
224 | @item -h | |
225 | @itemx --help | |
226 | Display a summary of the @sc{gasp} command line options. | |
227 | ||
228 | @item -M | |
229 | @itemx --mri | |
230 | Use MRI compatibility mode. Using this option causes @sc{gasp} to | |
231 | accept the syntax and pseudo-ops used by the Microtec Research | |
232 | @code{ASM68K} assembler. | |
233 | ||
234 | @item -o @var{outfile} | |
235 | @itemx --output @var{outfile} | |
236 | Write the output in a file called @var{outfile}. If you do not use the | |
237 | @samp{-o} option, @sc{gasp} writes its output on the standard output | |
238 | stream. | |
239 | ||
240 | @item -p | |
241 | @itemx --print | |
242 | Print line numbers. @sc{gasp} obeys this option @emph{only} if you also | |
243 | specify @samp{-s} to copy source lines to its output. With @samp{-s | |
244 | -p}, @sc{gasp} displays the line number of each source line copied | |
245 | (immediately after the comment character at the beginning of the line). | |
246 | ||
247 | @item -s | |
248 | @itemx --copysource | |
249 | Copy the source lines to the output file. Use this option | |
250 | to see the effect of each preprocessor line on the @sc{gasp} output. | |
251 | @sc{gasp} places a comment character (@samp{!} by default) at | |
252 | the beginning of each source line it copies, so that you can use this | |
253 | option and still assemble the result. | |
254 | ||
255 | @item -u | |
256 | @itemx --unreasonable | |
257 | Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp} | |
258 | macros inside other macro definitions, the preprocessor normally | |
259 | includes a sanity check. If your program requires more than 1,000 | |
260 | nested expansions, @sc{gasp} normally exits with an error message. Use | |
261 | this option to turn off this check, allowing unlimited nested | |
262 | expansions. | |
263 | ||
264 | @item -v | |
265 | @itemx --version | |
266 | Display the @sc{gasp} version number. | |
267 | @end ftable | |
268 | ||
269 | @node Commands | |
270 | @chapter Preprocessor Commands | |
271 | ||
272 | @sc{gasp} commands have a straightforward syntax that fits in well with | |
273 | assembly conventions. In general, a command extends for a line, and may | |
274 | have up to three fields: an optional label, the command itself, and | |
275 | optional arguments to the command. You can write commands in upper or | |
276 | lower case, though this manual shows them in upper case. @xref{Syntax | |
277 | Details,, Details of the GASP syntax}, for more information. | |
278 | ||
279 | @menu | |
280 | * Conditionals:: | |
281 | * Loops:: | |
282 | * Variables:: | |
283 | * Macros:: | |
284 | * Data:: | |
285 | * Listings:: | |
286 | * Other Commands:: | |
287 | * Syntax Details:: | |
288 | * Alternate:: | |
289 | @end menu | |
290 | ||
291 | @node Conditionals | |
292 | @section Conditional assembly | |
293 | ||
294 | The conditional-assembly directives allow you to include or exclude | |
295 | portions of an assembly depending on how a pair of expressions, or a | |
296 | pair of strings, compare. | |
297 | ||
298 | The overall structure of conditionals is familiar from many other | |
299 | contexts. @code{.AIF} marks the start of a conditional, and precedes | |
300 | assembly for the case when the condition is true. An optional | |
301 | @code{.AELSE} precedes assembly for the converse case, and an | |
302 | @code{.AENDI} marks the end of the condition. | |
303 | ||
304 | @c FIXME! Why doesn't -u turn off this check? | |
305 | You may nest conditionals up to a depth of 100; @sc{gasp} rejects | |
306 | nesting beyond that, because it may indicate a bug in your macro | |
307 | structure. | |
308 | ||
309 | @c FIXME! Why isn't there something like cpp's -D option? Conditionals | |
310 | @c would be much more useful if there were. | |
311 | Conditionals are primarily useful inside macro definitions, where you | |
312 | often need different effects depending on argument values. | |
313 | @xref{Macros,, Defining your own directives}, for details about defining | |
314 | macros. | |
315 | ||
316 | @ftable @code | |
317 | @item .AIF @var{expra} @var{cmp} @var{exprb} | |
318 | @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}" | |
319 | ||
320 | The governing condition goes on the same line as the @code{.AIF} | |
321 | preprocessor command. You may compare either two strings, or two | |
322 | expressions. | |
323 | ||
324 | When you compare strings, only two conditional @var{cmp} comparison | |
325 | operators are available: @samp{EQ} (true if @var{stra} and @var{strb} | |
326 | are identical), and @samp{NE} (the opposite). | |
327 | ||
328 | When you compare two expressions, @emph{both expressions must be | |
329 | absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You | |
330 | can use these @var{cmp} comparison operators with expressions: | |
331 | ||
332 | @ftable @code | |
333 | @item EQ | |
334 | Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and | |
335 | @var{strb} identical?) | |
336 | ||
337 | @item NE | |
338 | Are @var{expra} and @var{exprb} different? (For strings, are @var{stra} | |
339 | and @var{strb} different? | |
340 | ||
341 | @item LT | |
342 | Is @var{expra} less than @var{exprb}? (Not allowed for strings.) | |
343 | ||
344 | @item LE | |
345 | Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.) | |
346 | ||
347 | @item GT | |
348 | Is @var{expra} greater than @var{exprb}? (Not allowed for strings.) | |
349 | ||
350 | @item GE | |
351 | Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for | |
352 | strings.) | |
353 | @end ftable | |
354 | ||
355 | @item .AELSE | |
356 | Marks the start of assembly code to be included if the condition fails. | |
357 | Optional, and only allowed within a conditional (between @code{.AIF} and | |
358 | @code{.AENDI}). | |
359 | ||
360 | @item .AENDI | |
361 | Marks the end of a conditional assembly. | |
362 | @end ftable | |
363 | ||
364 | @node Loops | |
365 | @section Repetitive sections of assembly | |
366 | ||
367 | Two preprocessor directives allow you to repeatedly issue copies of the | |
368 | same block of assembly code. | |
369 | ||
370 | @ftable @code | |
371 | @item .AREPEAT @var{aexp} | |
372 | @itemx .AENDR | |
373 | If you simply need to repeat the same block of assembly over and over a | |
374 | fixed number of times, sandwich one instance of the repeated block | |
375 | between @code{.AREPEAT} and @code{.AENDR}. Specify the number of | |
376 | copies as @var{aexp} (which must be an absolute expression). For | |
377 | example, this repeats two assembly statements three times in succession: | |
378 | ||
379 | @cartouche | |
380 | @example | |
381 | .AREPEAT 3 | |
382 | rotcl r2 | |
383 | div1 r0,r1 | |
384 | .AENDR | |
385 | @end example | |
386 | @end cartouche | |
387 | ||
388 | @item .AWHILE @var{expra} @var{cmp} @var{exprb} | |
389 | @itemx .AENDW | |
390 | @itemx .AWHILE @var{stra} @var{cmp} @var{strb} | |
391 | @itemx .AENDW | |
392 | To repeat a block of assembly depending on a conditional test, rather | |
393 | than repeating it for a specific number of times, use @code{.AWHILE}. | |
394 | @code{.AENDW} marks the end of the repeated block. The conditional | |
395 | comparison works exactly the same way as for @code{.AIF}, with the same | |
396 | comparison operators (@pxref{Conditionals,, Conditional assembly}). | |
397 | ||
398 | Since the terms of the comparison must be absolute expression, | |
399 | @code{.AWHILE} is primarily useful within macros. @xref{Macros,, | |
400 | Defining your own directives}. | |
401 | @end ftable | |
402 | ||
403 | @cindex loops, breaking out of | |
404 | @cindex breaking out of loops | |
405 | You can use the @code{.EXITM} preprocessor directive to break out of | |
406 | loops early (as well as to break out of macros). @xref{Macros,, | |
407 | Defining your own directives}. | |
408 | ||
409 | @node Variables | |
410 | @section Preprocessor variables | |
411 | ||
412 | You can use variables in @sc{gasp} to represent strings, registers, or | |
413 | the results of expressions. | |
414 | ||
415 | You must distinguish two kinds of variables: | |
416 | @enumerate | |
417 | @item | |
418 | Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this | |
419 | kind of variable in your assembly output, simply mention its name. For | |
420 | example, these two lines define and use a variable @samp{eg}: | |
421 | ||
422 | @cartouche | |
423 | @example | |
424 | eg .EQU FLIP-64 | |
425 | @dots{} | |
426 | mov.l eg,r0 | |
427 | @end example | |
428 | @end cartouche | |
429 | ||
430 | @emph{Do not use} this kind of variable in conditional expressions or | |
431 | while loops; @sc{gasp} only evaluates these variables when writing | |
432 | assembly output. | |
433 | ||
434 | @item | |
435 | Variables for use during preprocessing. You can define these | |
436 | with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this | |
437 | kind of variable, write @samp{\&} before the variable name; for example, | |
438 | ||
439 | @cartouche | |
440 | @example | |
441 | opcit .ASSIGNA 47 | |
442 | @dots{} | |
443 | .AWHILE \&opcit GT 0 | |
444 | @dots{} | |
445 | .AENDW | |
446 | @end example | |
447 | @end cartouche | |
448 | ||
449 | @sc{gasp} treats macro arguments almost the same way, but to evaluate | |
450 | them you use the prefix @samp{\} rather than @samp{\&}. | |
451 | @xref{Macros,, Defining your own directives}. | |
452 | @end enumerate | |
453 | ||
454 | @ftable @code | |
455 | @item @var{pvar} .EQU @var{expr} | |
456 | @c FIXME! Anything to beware of re GAS directive of same name? | |
457 | Assign preprocessor variable @var{pvar} the value of the expression | |
458 | @var{expr}. There are no restrictions on redefinition; use @samp{.EQU} | |
459 | with the same @var{pvar} as often as you find it convenient. | |
460 | ||
461 | @item @var{pvar} .ASSIGN @var{expr} | |
462 | Almost the same as @code{.EQU}, save that you may not redefine | |
463 | @var{pvar} using @code{.ASSIGN} once it has a value. | |
464 | @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works | |
465 | @c just like .EQU | |
466 | ||
467 | @item @var{pvar} .ASSIGNA @var{aexpr} | |
468 | Define a variable with a numeric value, for use during preprocessing. | |
469 | @var{aexpr} must be an absolute expression. You can redefine variables | |
470 | with @code{.ASSIGNA} at any time. | |
471 | ||
472 | @item @var{pvar} .ASSIGNC "@var{str}" | |
473 | Define a variable with a string value, for use during preprocessing. | |
474 | You can redefine variables with @code{.ASSIGNC} at any time. | |
475 | ||
476 | @item @var{pvar} .REG (@var{register}) | |
477 | Use @code{.REG} to define a variable that represents a register. In | |
478 | particular, @var{register} is @emph{not evaluated} as an expression. | |
479 | You may use @code{.REG} at will to redefine register variables. | |
480 | @end ftable | |
481 | ||
482 | All these directives accept the variable name in the ``label'' position, | |
483 | that is at the left margin. You may specify a colon after the variable | |
484 | name if you wish; the first example above could have started @samp{eg:} | |
485 | with the same effect. | |
486 | ||
487 | @c pagebreak makes for better aesthetics---ensures macro and expansion together | |
488 | @page | |
489 | @node Macros | |
490 | @section Defining your own directives | |
491 | ||
492 | The commands @code{.MACRO} and @code{.ENDM} allow you to define macros | |
493 | that generate assembly output. You can use these macros with a syntax | |
494 | similar to built-in @sc{gasp} or assembler directives. For example, | |
495 | this definition specifies a macro @code{SUM} that adds together a range of | |
496 | consecutive registers: | |
497 | ||
498 | @cartouche | |
499 | @example | |
500 | .MACRO SUM FROM=0, TO=9 | |
501 | ! \FROM \TO | |
502 | mov r\FROM,r10 | |
503 | COUNT .ASSIGNA \FROM+1 | |
504 | .AWHILE \&COUNT LE \TO | |
505 | add r\&COUNT,r10 | |
506 | COUNT .ASSIGNA \&COUNT+1 | |
507 | .AENDW | |
508 | .ENDM | |
509 | @end example | |
510 | @end cartouche | |
511 | ||
512 | @noindent | |
513 | With that definition, @samp{SUM 0,5} generates this assembly output: | |
514 | ||
515 | @cartouche | |
516 | @example | |
517 | ! 0 5 | |
518 | mov r0,r10 | |
519 | add r1,r10 | |
520 | add r2,r10 | |
521 | add r3,r10 | |
522 | add r4,r10 | |
523 | add r5,r10 | |
524 | @end example | |
525 | @end cartouche | |
526 | ||
527 | @ftable @code | |
528 | @item .MACRO @var{macname} | |
529 | @itemx .MACRO @var{macname} @var{macargs} @dots{} | |
530 | Begin the definition of a macro called @var{macname}. If your macro | |
531 | definition requires arguments, specify their names after the macro name, | |
532 | separated by commas or spaces. You can supply a default value for any | |
533 | macro argument by following the name with @samp{=@var{deflt}}. For | |
534 | example, these are all valid @code{.MACRO} statements: | |
535 | ||
536 | @table @code | |
537 | @item .MACRO COMM | |
538 | Begin the definition of a macro called @code{COMM}, which takes no | |
539 | arguments. | |
540 | ||
541 | @item .MACRO PLUS1 P, P1 | |
542 | @itemx .MACRO PLUS1 P P1 | |
543 | Either statement begins the definition of a macro called @code{PLUS1}, | |
544 | which takes two arguments; within the macro definition, write | |
545 | @samp{\P} or @samp{\P1} to evaluate the arguments. | |
546 | ||
547 | @item .MACRO RESERVE_STR P1=0 P2 | |
548 | Begin the definition of a macro called @code{RESERVE_STR}, with two | |
549 | arguments. The first argument has a default value, but not the second. | |
550 | After the definition is complete, you can call the macro either as | |
551 | @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to | |
552 | @var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR | |
553 | ,@var{b}} (with @samp{\P1} evaluating as the default, in this case | |
554 | @samp{0}, and @samp{\P2} evaluating to @var{b}). | |
555 | @end table | |
556 | ||
557 | When you call a macro, you can specify the argument values either by | |
558 | position, or by keyword. For example, @samp{SUM 9,17} is equivalent to | |
559 | @samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables | |
560 | similar to the variables you define with @samp{.ASSIGNA} or | |
561 | @samp{.ASSIGNC}; in particular, you can use them in conditionals or for | |
562 | loop control. (The only difference is the prefix you write to evaluate | |
563 | the variable: for a macro argument, write @samp{\@var{argname}}, but for | |
564 | a preprocessor variable, write @samp{\&@var{varname}}.) | |
565 | ||
566 | @item @var{name} .MACRO | |
567 | @itemx @var{name} .MACRO ( @var{macargs} @dots{} ) | |
568 | @c FIXME check: I think no error _and_ no args recognized if I use form | |
569 | @c NAME .MACRO ARG ARG | |
570 | An alternative form of introducing a macro definition: specify the macro | |
571 | name in the label position, and the arguments (if any) between | |
572 | parentheses after the name. Defaulting rules and usage work the same | |
573 | way as for the other macro definition syntax. | |
574 | ||
575 | @item .ENDM | |
576 | Mark the end of a macro definition. | |
577 | ||
578 | @item .EXITM | |
579 | Exit early from the current macro definition, @code{.AREPEAT} loop, or | |
580 | @code{.AWHILE} loop. | |
581 | ||
582 | @cindex number of macros executed | |
583 | @cindex macros, count executed | |
584 | @item \@@ | |
585 | @sc{gasp} maintains a counter of how many macros it has | |
586 | executed in this pseudo-variable; you can copy that number to your | |
587 | output with @samp{\@@}, but @emph{only within a macro definition}. | |
588 | ||
589 | @item LOCAL @var{name} [ , @dots{} ] | |
590 | @emph{Warning: @code{LOCAL} is only available if you select ``alternate | |
591 | macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, | |
592 | Alternate macro syntax}. | |
593 | ||
594 | Generate a string replacement for each of the @var{name} arguments, and | |
595 | replace any instances of @var{name} in each macro expansion. The | |
596 | replacement string is unique in the assembly, and different for each | |
597 | separate macro expansion. @code{LOCAL} allows you to write macros that | |
598 | define symbols, without fear of conflict between separate macro expansions. | |
599 | @end ftable | |
600 | ||
601 | @node Data | |
602 | @section Data output | |
603 | ||
604 | In assembly code, you often need to specify working areas of memory; | |
605 | depending on the application, you may want to initialize such memory or | |
606 | not. @sc{gasp} provides preprocessor directives to help you avoid | |
607 | repetitive coding for both purposes. | |
608 | ||
609 | You can use labels as usual to mark the data areas. | |
610 | ||
611 | @menu | |
612 | * Initialized:: | |
613 | * Uninitialized:: | |
614 | @end menu | |
615 | ||
616 | @node Initialized | |
617 | @subsection Initialized data | |
618 | ||
619 | These are the @sc{gasp} directives for initialized data, and the standard | |
620 | @sc{gnu} assembler directives they expand to: | |
621 | ||
622 | @ftable @code | |
623 | @item .DATA @var{expr}, @var{expr}, @dots{} | |
624 | @itemx .DATA.B @var{expr}, @var{expr}, @dots{} | |
625 | @itemx .DATA.W @var{expr}, @var{expr}, @dots{} | |
626 | @itemx .DATA.L @var{expr}, @var{expr}, @dots{} | |
627 | Evaluate arithmetic expressions @var{expr}, and emit the corresponding | |
628 | @code{as} directive (labelled with @var{lab}). The unqualified | |
629 | @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte}; | |
630 | @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits | |
631 | @samp{.long}. | |
632 | ||
633 | For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}. | |
634 | ||
635 | @item .DATAB @var{repeat}, @var{expr} | |
636 | @itemx .DATAB.B @var{repeat}, @var{expr} | |
637 | @itemx .DATAB.W @var{repeat}, @var{expr} | |
638 | @itemx .DATAB.L @var{repeat}, @var{expr} | |
639 | @c FIXME! Looks like gasp accepts and ignores args after 2nd. | |
640 | Make @code{as} emit @var{repeat} copies of the value of the expression | |
641 | @var{expr} (using the @code{as} directive @code{.fill}). | |
642 | @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats | |
643 | two-byte values; and @samp{.DATAB.L} repeats four-byte values. | |
644 | @samp{.DATAB} without a suffix repeats four-byte values, just like | |
645 | @samp{.DATAB.L}. | |
646 | ||
647 | @c FIXME! Allowing zero might be useful for edge conditions in macros. | |
648 | @var{repeat} must be an absolute expression with a positive value. | |
649 | ||
650 | @item .SDATA "@var{str}" @dots{} | |
651 | String data. Emits a concatenation of bytes, precisely as you specify | |
652 | them (in particular, @emph{nothing is added to mark the end} of the | |
653 | string). @xref{Constants,, String and numeric constants}, for details | |
654 | about how to write strings. @code{.SDATA} concatenates multiple | |
655 | arguments, making it easy to switch between string representations. You | |
656 | can use commas to separate the individual arguments for clarity, if you | |
657 | choose. | |
658 | ||
659 | @item .SDATAB @var{repeat}, "@var{str}" @dots{} | |
660 | Repeated string data. The first argument specifies how many copies of | |
661 | the string to emit; the remaining arguments specify the string, in the | |
662 | same way as the arguments to @code{.SDATA}. | |
663 | ||
664 | @item .SDATAZ "@var{str}" @dots{} | |
665 | Zero-terminated string data. Just like @code{.SDATA}, except that | |
666 | @code{.SDATAZ} writes a zero byte at the end of the string. | |
667 | ||
668 | @item .SDATAC "@var{str}" @dots{} | |
669 | Count-prefixed string data. Just like @code{.SDATA}, except that | |
670 | @sc{gasp} precedes the string with a leading one-byte count. For | |
671 | example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the | |
672 | count field is only one byte, you can only use @code{.SDATAC} for | |
673 | strings less than 256 bytes in length. | |
674 | @end ftable | |
675 | ||
676 | @node Uninitialized | |
677 | @subsection Uninitialized data | |
678 | ||
679 | @c FIXME! .space different on some platforms, notably HPPA. Config? | |
680 | Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ} | |
681 | directives to reserve memory and leave it uninitialized. @sc{gasp} | |
682 | resolves these directives to appropriate calls of the @sc{gnu} | |
683 | @code{as} @code{.space} directive. | |
684 | ||
685 | @ftable @code | |
686 | @item .RES @var{count} | |
687 | @itemx .RES.B @var{count} | |
688 | @itemx .RES.W @var{count} | |
689 | @itemx .RES.L @var{count} | |
690 | Reserve room for @var{count} uninitialized elements of data. The | |
691 | suffix specifies the size of each element: @code{.RES.B} reserves | |
692 | @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes, | |
693 | and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a | |
694 | suffix is equivalent to @code{.RES.L}. | |
695 | ||
696 | @item .SRES @var{count} | |
697 | @itemx .SRES.B @var{count} | |
698 | @itemx .SRES.W @var{count} | |
699 | @itemx .SRES.L @var{count} | |
700 | @c FIXME! This is boring. Shouldn't it at least have a different | |
701 | @c default size? (e.g. the "S" suggests "string", for which .B | |
702 | @c would be more appropriate) | |
703 | @code{.SRES} is a synonym for @samp{.RES}. | |
704 | ||
705 | @item .SRESC @var{count} | |
706 | @itemx .SRESC.B @var{count} | |
707 | @itemx .SRESC.W @var{count} | |
708 | @itemx .SRESC.L @var{count} | |
709 | Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. | |
710 | ||
711 | @item .SRESZ @var{count} | |
712 | @itemx .SRESZ.B @var{count} | |
713 | @itemx .SRESZ.W @var{count} | |
714 | @itemx .SRESZ.L @var{count} | |
715 | Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. | |
716 | @end ftable | |
717 | ||
718 | @node Listings | |
719 | @section Assembly listing control | |
720 | ||
721 | The @sc{gasp} listing-control directives correspond to | |
722 | related @sc{gnu} @code{as} directives. | |
723 | ||
724 | @ftable @code | |
725 | @item .PRINT LIST | |
726 | @itemx .PRINT NOLIST | |
727 | Print control. This directive emits the @sc{gnu} @code{as} directive | |
728 | @code{.list} or @code{.nolist}, according to its argument. @xref{List,, | |
729 | @code{.list}, as.info, Using as}, for details on how these directives | |
730 | interact. | |
731 | ||
732 | @item .FORM LIN=@var{ln} | |
733 | @itemx .FORM COL=@var{cols} | |
734 | @itemx .FORM LIN=@var{ln} COL=@var{cols} | |
735 | Specify the page size for assembly listings: @var{ln} represents the | |
736 | number of lines, and @var{cols} the number of columns. You may specify | |
737 | either page dimension independently, or both together. If you do not | |
738 | specify the number of lines, @sc{gasp} assumes 60 lines; if you do not | |
739 | specify the number of columns, @sc{gasp} assumes 132 columns. | |
740 | (Any values you may have specified in previous instances of @code{.FORM} | |
741 | do @emph{not} carry over as defaults.) Emits the @code{.psize} | |
742 | assembler directive. | |
743 | ||
744 | @item .HEADING @var{string} | |
745 | Specify @var{string} as the title of your assembly listings. Emits | |
746 | @samp{.title "@var{string}"}. | |
747 | ||
748 | @item .PAGE | |
749 | Force a new page in assembly listings. Emits @samp{.eject}. | |
750 | @end ftable | |
751 | ||
752 | @node Other Commands | |
753 | @section Miscellaneous commands | |
754 | ||
755 | @ftable @code | |
756 | @item .ALTERNATE | |
757 | Use the alternate macro syntax henceforth in the assembly. | |
758 | @xref{Alternate,, Alternate macro syntax}. | |
759 | ||
760 | @item .ORG | |
761 | @c FIXME! This is very strange, since _GAS_ understands .org | |
762 | This command is recognized, but not yet implemented. @sc{gasp} | |
763 | generates an error message for programs that use @code{.ORG}. | |
764 | ||
765 | @item .RADIX @var{s} | |
766 | @c FIXME no test cases in testsuite/gasp | |
767 | @sc{gasp} understands numbers in any of base two, eight, ten, or | |
768 | sixteen. You can encode the base explicitly in any numeric constant | |
769 | (@pxref{Constants,, String and numeric constants}). If you write | |
770 | numbers without an explicit indication of the base, the most recent | |
771 | @samp{.RADIX @var{s}} command determines how they are interpreted. | |
772 | @var{s} is a single letter, one of the following: | |
773 | ||
774 | @table @code | |
775 | @item .RADIX B | |
776 | Base 2. | |
777 | ||
778 | @item .RADIX Q | |
779 | Base 8. | |
780 | ||
781 | @item .RADIX D | |
782 | Base 10. This is the original default radix. | |
783 | ||
784 | @item .RADIX H | |
785 | Base 16. | |
786 | @end table | |
787 | ||
788 | You may specify the argument @var{s} in lower case (any of @samp{bqdh}) | |
789 | with the same effects. | |
790 | ||
791 | @item .EXPORT @var{name} | |
792 | @itemx .GLOBAL @var{name} | |
793 | @c FIXME! No test cases in testsuite/gasp | |
794 | Declare @var{name} global (emits @samp{.global @var{name}}). The two | |
795 | directives are synonymous. | |
796 | ||
797 | @item .PROGRAM | |
798 | No effect: @sc{gasp} accepts this directive, and silently ignores it. | |
799 | ||
800 | @item .END | |
801 | Mark end of each preprocessor file. @sc{gasp} issues a warning if it | |
802 | reaches end of file without seeing this command. | |
803 | ||
804 | @item .INCLUDE "@var{str}" | |
805 | Preprocess the file named by @var{str}, as if its contents appeared | |
806 | where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum | |
807 | limit of 30 stacked include files, as a sanity check. | |
808 | @c FIXME! Why is include depth not affected by -u? | |
809 | ||
810 | @item .ALIGN @var{size} | |
811 | @c FIXME! Why is this not utterly pointless? | |
812 | Evaluate the absolute expression @var{size}, and emit the assembly | |
813 | instruction @samp{.align @var{size}} using the result. | |
814 | @end ftable | |
815 | ||
816 | @node Syntax Details | |
817 | @section Details of the GASP syntax | |
818 | ||
819 | Since @sc{gasp} is meant to work with assembly code, its statement | |
820 | syntax has no surprises for the assembly programmer. | |
821 | ||
822 | @cindex whitespace | |
823 | @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially | |
824 | significant, in that it delimits up to three fields in a line. The | |
825 | amount of whitespace does not matter; you may line up fields in separate | |
826 | lines if you wish, but @sc{gasp} does not require that. | |
827 | ||
828 | @cindex fields of @sc{gasp} source line | |
829 | @cindex label field | |
830 | The @emph{first field}, an optional @dfn{label}, must be flush left in a | |
831 | line (with no leading whitespace) if it appears at all. You may use a | |
832 | colon after the label if you wish; @sc{gasp} neither requires the colon | |
833 | nor objects to it (but will not include it as part of the label name). | |
834 | ||
835 | @cindex directive field | |
836 | The @emph{second field}, which must appear after some whitespace, | |
837 | contains a @sc{gasp} or assembly @dfn{directive}. | |
838 | ||
839 | @cindex argument fields | |
840 | Any @emph{further fields} on a line are @dfn{arguments} to the | |
841 | directive; you can separate them from one another using either commas or | |
842 | whitespace. | |
843 | ||
844 | @menu | |
845 | * Markers:: | |
846 | * Constants:: | |
847 | * Symbols:: | |
848 | * Expressions:: | |
849 | * String Builtins:: | |
850 | @end menu | |
851 | ||
852 | @node Markers | |
853 | @subsection Special syntactic markers | |
854 | ||
855 | @sc{gasp} recognizes a few special markers: to delimit comments, to | |
856 | continue a statement on the next line, to separate symbols from other | |
857 | characters, and to copy text to the output literally. (One other | |
858 | special marker, @samp{\@@}, works only within macro definitions; | |
859 | @pxref{Macros,, Defining your own directives}.) | |
860 | ||
861 | @cindex comments | |
862 | The trailing part of any @sc{gasp} source line may be a @dfn{comment}. | |
863 | A comment begins with the first unquoted comment character (@samp{!} by | |
864 | default), or an escaped or doubled comment character (@samp{\!} or | |
865 | @samp{!!} by default), and extends to the end of a line. You can | |
866 | specify what comment character to use with the @samp{-c} option | |
867 | (@pxref{Invoking GASP,, Command Line Options}). The two kinds of | |
868 | comment markers lead to slightly different treatment: | |
869 | ||
870 | @table @code | |
871 | @item ! | |
872 | A single, un-escaped comment character generates an assembly comment in | |
873 | the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables | |
874 | (macro arguments, or variables defined with @code{.ASSIGNA} or | |
875 | @code{.ASSIGNC}) present. For example, a macro that begins like this | |
876 | ||
877 | @example | |
878 | .MACRO SUM FROM=0, TO=9 | |
879 | ! \FROM \TO | |
880 | @end example | |
881 | ||
882 | @noindent | |
883 | issues as the first line of output a comment that records the | |
884 | values you used to call the macro. | |
885 | ||
886 | @c comments, preprocessor-only | |
887 | @c preprocessor-only comments | |
888 | @c GASP-only comments | |
889 | @item \! | |
890 | @itemx !! | |
891 | Either an escaped comment character, or a double comment character, | |
892 | marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments | |
893 | to the assembly output. | |
894 | @end table | |
895 | ||
896 | @cindex continuation character | |
897 | @kindex + | |
898 | To @emph{continue a statement} on the next line of the file, begin the | |
899 | second line with the character @samp{+}. | |
900 | ||
901 | @cindex literal copy to output | |
902 | @cindex copying literally to output | |
903 | @cindex preprocessing, avoiding | |
904 | @cindex avoiding preprocessing | |
905 | Occasionally you may want to prevent @sc{gasp} from preprocessing some | |
906 | particular bit of text. To @emph{copy literally} from the @sc{gasp} | |
907 | source to its output, place @samp{\(} before the string to copy, and | |
908 | @samp{)} at the end. For example, write @samp{\(\!)} if you need the | |
909 | characters @samp{\!} in your assembly output. | |
910 | ||
911 | @cindex symbol separator | |
912 | @cindex text, separating from symbols | |
913 | @cindex symbols, separating from text | |
914 | To @emph{separate a preprocessor variable} from text to appear | |
915 | immediately after its value, write a single quote (@code{'}). For | |
916 | example, @samp{.SDATA "\P'1"} writes a string built by concatenating the | |
917 | value of @code{P} and the digit @samp{1}. (You cannot achieve this by | |
918 | writing just @samp{\P1}, since @samp{P1} is itself a valid name for a | |
919 | preprocessor variable.) | |
920 | ||
921 | @node Constants | |
922 | @subsection String and numeric constants | |
923 | ||
924 | There are two ways of writing @dfn{string constants} in @sc{gasp}: as | |
925 | literal text, and by numeric byte value. Specify a string literal | |
926 | between double quotes (@code{"@var{str}"}). Specify an individual | |
927 | numeric byte value as an absolute expression between angle brackets | |
928 | (@code{<@var{expr}>}. Directives that output strings allow you to | |
929 | specify any number of either kind of value, in whatever order is | |
930 | convenient, and concatenate the result. (Alternate syntax mode | |
931 | introduces a number of alternative string notations; @pxref{Alternate,, | |
932 | Alternate macro syntax}.) | |
933 | ||
934 | @c Details of numeric notation, e.g. base prefixes | |
935 | You can write @dfn{numeric constants} either in a specific base, or in | |
936 | whatever base is currently selected (either 10, or selected by the most | |
937 | recent @code{.RADIX}). | |
938 | ||
939 | To write a number in a @emph{specific base}, use the pattern | |
940 | @code{@var{s}'@var{ddd}}: a base specifier character @var{s}, followed | |
941 | by a single quote followed by digits @var{ddd}. The base specifier | |
942 | character matches those you can specify with @code{.RADIX}: @samp{B} for | |
943 | base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base | |
944 | 16. (You can write this character in lower case if you prefer.) | |
945 | ||
946 | @c FIXME! What are rules for recognizing number in deflt base? Whatever | |
947 | @c is left over after parsing other things?? | |
948 | ||
949 | @node Symbols | |
950 | @subsection Symbols | |
951 | ||
952 | @sc{gasp} recognizes symbol names that start with any alphabetic character, | |
953 | @samp{_}, or @samp{$}, and continue with any of the same characters or | |
954 | with digits. Label names follow the same rules. | |
955 | ||
956 | @node Expressions | |
957 | @subsection Arithmetic expressions in GASP | |
958 | ||
959 | @cindex absolute expressions | |
960 | @cindex relocatable expressions | |
961 | There are two kinds of expressions, depending on their result: | |
962 | @dfn{absolute} expressions, which resolve to a constant (that is, they | |
963 | do not involve any values unknown to @sc{gasp}), and @dfn{relocatable} | |
964 | expressions, which must reduce to the form | |
965 | ||
966 | @example | |
967 | @var{addsym}+@var{const}-@var{subsym} | |
968 | @end example | |
969 | ||
970 | @noindent | |
971 | where @var{addsym} and @var{subsym} are assembly symbols of unknown | |
972 | value, and @var{const} is a constant. | |
973 | ||
974 | Arithmetic for @sc{gasp} expressions follows very similar rules to C. | |
975 | You can use parentheses to change precedence; otherwise, arithmetic | |
976 | primitives have decreasing precedence in the order of the following | |
977 | list. | |
978 | ||
979 | @enumerate | |
980 | @item | |
981 | Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or | |
982 | @code{~} (bitwise negation). @emph{The argument must be an absolute | |
983 | expression.} | |
984 | ||
985 | @item | |
986 | @code{*} (multiplication) and @code{/} (division). @emph{Both arguments | |
987 | must be absolute expressions.} | |
988 | ||
989 | @item | |
990 | @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument | |
991 | must be absolute.} | |
992 | @c FIXME! Actually, subtraction doesn't check for this. | |
993 | ||
994 | @item | |
995 | @code{&} (bitwise and). @emph{Both arguments must be absolute.} | |
996 | ||
997 | @item | |
998 | @c FIXME! I agree ~ is a better notation than ^ for xor, but is the | |
999 | @c improvement worth differing from C? | |
1000 | @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in | |
1001 | C). @emph{Both arguments must be absolute.} | |
1002 | @end enumerate | |
1003 | ||
1004 | @node String Builtins | |
1005 | @subsection String primitives | |
1006 | ||
1007 | You can use these primitives to manipulate strings (in the argument | |
1008 | field of @sc{gasp} statements): | |
1009 | ||
1010 | @ftable @code | |
1011 | @item .LEN("@var{str}") | |
1012 | Calculate the length of string @code{"@var{str}"}, as an absolute | |
1013 | expression. For example, @samp{.RES.B .LEN("sample")} reserves six | |
1014 | bytes of memory. | |
1015 | ||
1016 | @item .INSTR("@var{string}", "@var{seg}", @var{ix}) | |
1017 | Search for the first occurrence of @var{seg} after position @var{ix} of | |
1018 | @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates | |
1019 | to the absolute result @code{2}. | |
1020 | ||
1021 | The result is @code{-1} if @var{seg} does not occur in @var{string} | |
1022 | after position @var{ix}. | |
1023 | ||
1024 | @item .SUBSTR("@var{string}",@var{start},@var{len}) | |
1025 | The substring of @var{string} beginning at byte number @var{start} and | |
1026 | extending for @var{len} bytes. | |
1027 | @end ftable | |
1028 | ||
1029 | @node Alternate | |
1030 | @section Alternate macro syntax | |
1031 | ||
1032 | If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command | |
1033 | line, the preprocessor uses somewhat different syntax. This syntax is | |
1034 | reminiscent of the syntax of Phar Lap macro assembler, but it | |
1035 | is @emph{not} meant to be a full emulation of Phar Lap or similar | |
1036 | assemblers. In particular, @sc{gasp} does not support directives such | |
1037 | as @code{DB} and @code{IRP}, even in alternate syntax mode. | |
1038 | ||
1039 | In particular, @samp{-a} (or @samp{--alternate}) elicits these | |
1040 | differences: | |
1041 | ||
1042 | @table @emph | |
1043 | @item Preprocessor directives | |
1044 | You can use @sc{gasp} preprocessor directives without a leading @samp{.} | |
1045 | dot. For example, you can write @samp{SDATA} with the same effect as | |
1046 | @samp{.SDATA}. | |
1047 | ||
1048 | @item LOCAL | |
1049 | One additional directive, @code{LOCAL}, is available. @xref{Macros,, | |
1050 | Defining your own directives}, for an explanation of how to use | |
1051 | @code{LOCAL}. | |
1052 | ||
1053 | @need 2000 | |
1054 | @item String delimiters | |
1055 | You can write strings delimited in these other ways besides | |
1056 | @code{"@var{string}"}: | |
1057 | ||
1058 | @table @code | |
1059 | @item '@var{string}' | |
1060 | You can delimit strings with single-quote charaters. | |
1061 | ||
1062 | @item <@var{string}> | |
1063 | You can delimit strings with matching angle brackets. | |
1064 | @end table | |
1065 | ||
1066 | @item single-character string escape | |
1067 | To include any single character literally in a string (even if the | |
1068 | character would otherwise have some special meaning), you can prefix the | |
1069 | character with @samp{!} (an exclamation mark). For example, you can | |
1070 | write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. | |
1071 | ||
1072 | @item Expression results as strings | |
1073 | You can write @samp{%@var{expr}} to evaluate the expression @var{expr} | |
1074 | and use the result as a string. | |
1075 | @end table | |
1076 | ||
cf055d54 NC |
1077 | @node GNU Free Documentation License |
1078 | @chapter GNU Free Documentation License | |
1079 | ||
1080 | GNU Free Documentation License | |
1081 | ||
1082 | Version 1.1, March 2000 | |
1083 | ||
1084 | Copyright (C) 2000 Free Software Foundation, Inc. | |
1085 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
1086 | ||
1087 | Everyone is permitted to copy and distribute verbatim copies | |
1088 | of this license document, but changing it is not allowed. | |
1089 | ||
1090 | ||
1091 | 0. PREAMBLE | |
1092 | ||
1093 | The purpose of this License is to make a manual, textbook, or other | |
1094 | written document "free" in the sense of freedom: to assure everyone | |
1095 | the effective freedom to copy and redistribute it, with or without | |
1096 | modifying it, either commercially or noncommercially. Secondarily, | |
1097 | this License preserves for the author and publisher a way to get | |
1098 | credit for their work, while not being considered responsible for | |
1099 | modifications made by others. | |
1100 | ||
1101 | This License is a kind of "copyleft", which means that derivative | |
1102 | works of the document must themselves be free in the same sense. It | |
1103 | complements the GNU General Public License, which is a copyleft | |
1104 | license designed for free software. | |
1105 | ||
1106 | We have designed this License in order to use it for manuals for free | |
1107 | software, because free software needs free documentation: a free | |
1108 | program should come with manuals providing the same freedoms that the | |
1109 | software does. But this License is not limited to software manuals; | |
1110 | it can be used for any textual work, regardless of subject matter or | |
1111 | whether it is published as a printed book. We recommend this License | |
1112 | principally for works whose purpose is instruction or reference. | |
1113 | ||
1114 | ||
1115 | 1. APPLICABILITY AND DEFINITIONS | |
1116 | ||
1117 | This License applies to any manual or other work that contains a | |
1118 | notice placed by the copyright holder saying it can be distributed | |
1119 | under the terms of this License. The "Document", below, refers to any | |
1120 | such manual or work. Any member of the public is a licensee, and is | |
1121 | addressed as "you". | |
1122 | ||
1123 | A "Modified Version" of the Document means any work containing the | |
1124 | Document or a portion of it, either copied verbatim, or with | |
1125 | modifications and/or translated into another language. | |
1126 | ||
1127 | A "Secondary Section" is a named appendix or a front-matter section of | |
1128 | the Document that deals exclusively with the relationship of the | |
1129 | publishers or authors of the Document to the Document's overall subject | |
1130 | (or to related matters) and contains nothing that could fall directly | |
1131 | within that overall subject. (For example, if the Document is in part a | |
1132 | textbook of mathematics, a Secondary Section may not explain any | |
1133 | mathematics.) The relationship could be a matter of historical | |
1134 | connection with the subject or with related matters, or of legal, | |
1135 | commercial, philosophical, ethical or political position regarding | |
1136 | them. | |
1137 | ||
1138 | The "Invariant Sections" are certain Secondary Sections whose titles | |
1139 | are designated, as being those of Invariant Sections, in the notice | |
1140 | that says that the Document is released under this License. | |
1141 | ||
1142 | The "Cover Texts" are certain short passages of text that are listed, | |
1143 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
1144 | the Document is released under this License. | |
1145 | ||
1146 | A "Transparent" copy of the Document means a machine-readable copy, | |
1147 | represented in a format whose specification is available to the | |
1148 | general public, whose contents can be viewed and edited directly and | |
1149 | straightforwardly with generic text editors or (for images composed of | |
1150 | pixels) generic paint programs or (for drawings) some widely available | |
1151 | drawing editor, and that is suitable for input to text formatters or | |
1152 | for automatic translation to a variety of formats suitable for input | |
1153 | to text formatters. A copy made in an otherwise Transparent file | |
1154 | format whose markup has been designed to thwart or discourage | |
1155 | subsequent modification by readers is not Transparent. A copy that is | |
1156 | not "Transparent" is called "Opaque". | |
1157 | ||
1158 | Examples of suitable formats for Transparent copies include plain | |
1159 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
1160 | or XML using a publicly available DTD, and standard-conforming simple | |
1161 | HTML designed for human modification. Opaque formats include | |
1162 | PostScript, PDF, proprietary formats that can be read and edited only | |
1163 | by proprietary word processors, SGML or XML for which the DTD and/or | |
1164 | processing tools are not generally available, and the | |
1165 | machine-generated HTML produced by some word processors for output | |
1166 | purposes only. | |
1167 | ||
1168 | The "Title Page" means, for a printed book, the title page itself, | |
1169 | plus such following pages as are needed to hold, legibly, the material | |
1170 | this License requires to appear in the title page. For works in | |
1171 | formats which do not have any title page as such, "Title Page" means | |
1172 | the text near the most prominent appearance of the work's title, | |
1173 | preceding the beginning of the body of the text. | |
1174 | ||
1175 | ||
1176 | 2. VERBATIM COPYING | |
1177 | ||
1178 | You may copy and distribute the Document in any medium, either | |
1179 | commercially or noncommercially, provided that this License, the | |
1180 | copyright notices, and the license notice saying this License applies | |
1181 | to the Document are reproduced in all copies, and that you add no other | |
1182 | conditions whatsoever to those of this License. You may not use | |
1183 | technical measures to obstruct or control the reading or further | |
1184 | copying of the copies you make or distribute. However, you may accept | |
1185 | compensation in exchange for copies. If you distribute a large enough | |
1186 | number of copies you must also follow the conditions in section 3. | |
1187 | ||
1188 | You may also lend copies, under the same conditions stated above, and | |
1189 | you may publicly display copies. | |
1190 | ||
1191 | ||
1192 | 3. COPYING IN QUANTITY | |
1193 | ||
1194 | If you publish printed copies of the Document numbering more than 100, | |
1195 | and the Document's license notice requires Cover Texts, you must enclose | |
1196 | the copies in covers that carry, clearly and legibly, all these Cover | |
1197 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
1198 | the back cover. Both covers must also clearly and legibly identify | |
1199 | you as the publisher of these copies. The front cover must present | |
1200 | the full title with all words of the title equally prominent and | |
1201 | visible. You may add other material on the covers in addition. | |
1202 | Copying with changes limited to the covers, as long as they preserve | |
1203 | the title of the Document and satisfy these conditions, can be treated | |
1204 | as verbatim copying in other respects. | |
1205 | ||
1206 | If the required texts for either cover are too voluminous to fit | |
1207 | legibly, you should put the first ones listed (as many as fit | |
1208 | reasonably) on the actual cover, and continue the rest onto adjacent | |
1209 | pages. | |
1210 | ||
1211 | If you publish or distribute Opaque copies of the Document numbering | |
1212 | more than 100, you must either include a machine-readable Transparent | |
1213 | copy along with each Opaque copy, or state in or with each Opaque copy | |
1214 | a publicly-accessible computer-network location containing a complete | |
1215 | Transparent copy of the Document, free of added material, which the | |
1216 | general network-using public has access to download anonymously at no | |
1217 | charge using public-standard network protocols. If you use the latter | |
1218 | option, you must take reasonably prudent steps, when you begin | |
1219 | distribution of Opaque copies in quantity, to ensure that this | |
1220 | Transparent copy will remain thus accessible at the stated location | |
1221 | until at least one year after the last time you distribute an Opaque | |
1222 | copy (directly or through your agents or retailers) of that edition to | |
1223 | the public. | |
1224 | ||
1225 | It is requested, but not required, that you contact the authors of the | |
1226 | Document well before redistributing any large number of copies, to give | |
1227 | them a chance to provide you with an updated version of the Document. | |
1228 | ||
1229 | ||
1230 | 4. MODIFICATIONS | |
1231 | ||
1232 | You may copy and distribute a Modified Version of the Document under | |
1233 | the conditions of sections 2 and 3 above, provided that you release | |
1234 | the Modified Version under precisely this License, with the Modified | |
1235 | Version filling the role of the Document, thus licensing distribution | |
1236 | and modification of the Modified Version to whoever possesses a copy | |
1237 | of it. In addition, you must do these things in the Modified Version: | |
1238 | ||
1239 | A. Use in the Title Page (and on the covers, if any) a title distinct | |
1240 | from that of the Document, and from those of previous versions | |
1241 | (which should, if there were any, be listed in the History section | |
1242 | of the Document). You may use the same title as a previous version | |
1243 | if the original publisher of that version gives permission. | |
1244 | B. List on the Title Page, as authors, one or more persons or entities | |
1245 | responsible for authorship of the modifications in the Modified | |
1246 | Version, together with at least five of the principal authors of the | |
1247 | Document (all of its principal authors, if it has less than five). | |
1248 | C. State on the Title page the name of the publisher of the | |
1249 | Modified Version, as the publisher. | |
1250 | D. Preserve all the copyright notices of the Document. | |
1251 | E. Add an appropriate copyright notice for your modifications | |
1252 | adjacent to the other copyright notices. | |
1253 | F. Include, immediately after the copyright notices, a license notice | |
1254 | giving the public permission to use the Modified Version under the | |
1255 | terms of this License, in the form shown in the Addendum below. | |
1256 | G. Preserve in that license notice the full lists of Invariant Sections | |
1257 | and required Cover Texts given in the Document's license notice. | |
1258 | H. Include an unaltered copy of this License. | |
1259 | I. Preserve the section entitled "History", and its title, and add to | |
1260 | it an item stating at least the title, year, new authors, and | |
1261 | publisher of the Modified Version as given on the Title Page. If | |
1262 | there is no section entitled "History" in the Document, create one | |
1263 | stating the title, year, authors, and publisher of the Document as | |
1264 | given on its Title Page, then add an item describing the Modified | |
1265 | Version as stated in the previous sentence. | |
1266 | J. Preserve the network location, if any, given in the Document for | |
1267 | public access to a Transparent copy of the Document, and likewise | |
1268 | the network locations given in the Document for previous versions | |
1269 | it was based on. These may be placed in the "History" section. | |
1270 | You may omit a network location for a work that was published at | |
1271 | least four years before the Document itself, or if the original | |
1272 | publisher of the version it refers to gives permission. | |
1273 | K. In any section entitled "Acknowledgements" or "Dedications", | |
1274 | preserve the section's title, and preserve in the section all the | |
1275 | substance and tone of each of the contributor acknowledgements | |
1276 | and/or dedications given therein. | |
1277 | L. Preserve all the Invariant Sections of the Document, | |
1278 | unaltered in their text and in their titles. Section numbers | |
1279 | or the equivalent are not considered part of the section titles. | |
1280 | M. Delete any section entitled "Endorsements". Such a section | |
1281 | may not be included in the Modified Version. | |
1282 | N. Do not retitle any existing section as "Endorsements" | |
1283 | or to conflict in title with any Invariant Section. | |
1284 | ||
1285 | If the Modified Version includes new front-matter sections or | |
1286 | appendices that qualify as Secondary Sections and contain no material | |
1287 | copied from the Document, you may at your option designate some or all | |
1288 | of these sections as invariant. To do this, add their titles to the | |
1289 | list of Invariant Sections in the Modified Version's license notice. | |
1290 | These titles must be distinct from any other section titles. | |
1291 | ||
1292 | You may add a section entitled "Endorsements", provided it contains | |
1293 | nothing but endorsements of your Modified Version by various | |
1294 | parties--for example, statements of peer review or that the text has | |
1295 | been approved by an organization as the authoritative definition of a | |
1296 | standard. | |
1297 | ||
1298 | You may add a passage of up to five words as a Front-Cover Text, and a | |
1299 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
1300 | of Cover Texts in the Modified Version. Only one passage of | |
1301 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
1302 | through arrangements made by) any one entity. If the Document already | |
1303 | includes a cover text for the same cover, previously added by you or | |
1304 | by arrangement made by the same entity you are acting on behalf of, | |
1305 | you may not add another; but you may replace the old one, on explicit | |
1306 | permission from the previous publisher that added the old one. | |
1307 | ||
1308 | The author(s) and publisher(s) of the Document do not by this License | |
1309 | give permission to use their names for publicity for or to assert or | |
1310 | imply endorsement of any Modified Version. | |
1311 | ||
1312 | ||
1313 | 5. COMBINING DOCUMENTS | |
1314 | ||
1315 | You may combine the Document with other documents released under this | |
1316 | License, under the terms defined in section 4 above for modified | |
1317 | versions, provided that you include in the combination all of the | |
1318 | Invariant Sections of all of the original documents, unmodified, and | |
1319 | list them all as Invariant Sections of your combined work in its | |
1320 | license notice. | |
1321 | ||
1322 | The combined work need only contain one copy of this License, and | |
1323 | multiple identical Invariant Sections may be replaced with a single | |
1324 | copy. If there are multiple Invariant Sections with the same name but | |
1325 | different contents, make the title of each such section unique by | |
1326 | adding at the end of it, in parentheses, the name of the original | |
1327 | author or publisher of that section if known, or else a unique number. | |
1328 | Make the same adjustment to the section titles in the list of | |
1329 | Invariant Sections in the license notice of the combined work. | |
1330 | ||
1331 | In the combination, you must combine any sections entitled "History" | |
1332 | in the various original documents, forming one section entitled | |
1333 | "History"; likewise combine any sections entitled "Acknowledgements", | |
1334 | and any sections entitled "Dedications". You must delete all sections | |
1335 | entitled "Endorsements." | |
1336 | ||
1337 | ||
1338 | 6. COLLECTIONS OF DOCUMENTS | |
1339 | ||
1340 | You may make a collection consisting of the Document and other documents | |
1341 | released under this License, and replace the individual copies of this | |
1342 | License in the various documents with a single copy that is included in | |
1343 | the collection, provided that you follow the rules of this License for | |
1344 | verbatim copying of each of the documents in all other respects. | |
1345 | ||
1346 | You may extract a single document from such a collection, and distribute | |
1347 | it individually under this License, provided you insert a copy of this | |
1348 | License into the extracted document, and follow this License in all | |
1349 | other respects regarding verbatim copying of that document. | |
1350 | ||
1351 | ||
1352 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
1353 | ||
1354 | A compilation of the Document or its derivatives with other separate | |
1355 | and independent documents or works, in or on a volume of a storage or | |
1356 | distribution medium, does not as a whole count as a Modified Version | |
1357 | of the Document, provided no compilation copyright is claimed for the | |
1358 | compilation. Such a compilation is called an "aggregate", and this | |
1359 | License does not apply to the other self-contained works thus compiled | |
1360 | with the Document, on account of their being thus compiled, if they | |
1361 | are not themselves derivative works of the Document. | |
1362 | ||
1363 | If the Cover Text requirement of section 3 is applicable to these | |
1364 | copies of the Document, then if the Document is less than one quarter | |
1365 | of the entire aggregate, the Document's Cover Texts may be placed on | |
1366 | covers that surround only the Document within the aggregate. | |
1367 | Otherwise they must appear on covers around the whole aggregate. | |
1368 | ||
1369 | ||
1370 | 8. TRANSLATION | |
1371 | ||
1372 | Translation is considered a kind of modification, so you may | |
1373 | distribute translations of the Document under the terms of section 4. | |
1374 | Replacing Invariant Sections with translations requires special | |
1375 | permission from their copyright holders, but you may include | |
1376 | translations of some or all Invariant Sections in addition to the | |
1377 | original versions of these Invariant Sections. You may include a | |
1378 | translation of this License provided that you also include the | |
1379 | original English version of this License. In case of a disagreement | |
1380 | between the translation and the original English version of this | |
1381 | License, the original English version will prevail. | |
1382 | ||
1383 | ||
1384 | 9. TERMINATION | |
1385 | ||
1386 | You may not copy, modify, sublicense, or distribute the Document except | |
1387 | as expressly provided for under this License. Any other attempt to | |
1388 | copy, modify, sublicense or distribute the Document is void, and will | |
1389 | automatically terminate your rights under this License. However, | |
1390 | parties who have received copies, or rights, from you under this | |
1391 | License will not have their licenses terminated so long as such | |
1392 | parties remain in full compliance. | |
1393 | ||
1394 | ||
1395 | 10. FUTURE REVISIONS OF THIS LICENSE | |
1396 | ||
1397 | The Free Software Foundation may publish new, revised versions | |
1398 | of the GNU Free Documentation License from time to time. Such new | |
1399 | versions will be similar in spirit to the present version, but may | |
1400 | differ in detail to address new problems or concerns. See | |
1401 | http://www.gnu.org/copyleft/. | |
1402 | ||
1403 | Each version of the License is given a distinguishing version number. | |
1404 | If the Document specifies that a particular numbered version of this | |
1405 | License "or any later version" applies to it, you have the option of | |
1406 | following the terms and conditions either of that specified version or | |
1407 | of any later version that has been published (not as a draft) by the | |
1408 | Free Software Foundation. If the Document does not specify a version | |
1409 | number of this License, you may choose any version ever published (not | |
1410 | as a draft) by the Free Software Foundation. | |
1411 | ||
1412 | ||
1413 | ADDENDUM: How to use this License for your documents | |
1414 | ||
1415 | To use this License in a document you have written, include a copy of | |
1416 | the License in the document and put the following copyright and | |
1417 | license notices just after the title page: | |
1418 | ||
1419 | @smallexample | |
1420 | Copyright (c) YEAR YOUR NAME. | |
1421 | Permission is granted to copy, distribute and/or modify this document | |
1422 | under the terms of the GNU Free Documentation License, Version 1.1 | |
1423 | or any later version published by the Free Software Foundation; | |
1424 | with the Invariant Sections being LIST THEIR TITLES, with the | |
1425 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
1426 | A copy of the license is included in the section entitled "GNU | |
1427 | Free Documentation License". | |
1428 | @end smallexample | |
1429 | ||
1430 | If you have no Invariant Sections, write "with no Invariant Sections" | |
1431 | instead of saying which ones are invariant. If you have no | |
1432 | Front-Cover Texts, write "no Front-Cover Texts" instead of | |
1433 | "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. | |
1434 | ||
1435 | If your document contains nontrivial examples of program code, we | |
1436 | recommend releasing these examples in parallel under your choice of | |
1437 | free software license, such as the GNU General Public License, | |
1438 | to permit their use in free software. | |
1439 | ||
252b5132 RH |
1440 | @node Index |
1441 | @unnumbered Index | |
1442 | ||
1443 | @printindex cp | |
1444 | ||
1445 | @contents | |
1446 | @bye |