Initial revision
[chise/xemacs-chise.git-] / info / texinfo.info-7
1 This is Info file ../info/texinfo.info, produced by Makeinfo version
2 1.68 from the input file texinfo.texi.
3
4 INFO-DIR-SECTION Texinfo documentation system
5 START-INFO-DIR-ENTRY
6 * Texinfo: (texinfo).           The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi.      Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex.  Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred.        Translate Texinfo source.
11 END-INFO-DIR-ENTRY
12
13   This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
15
16   Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
17 Foundation, Inc.
18
19   This edition is for Texinfo version 3.12.
20
21   Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
24
25   Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
29
30   Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
34
35 \1f
36 File: texinfo.info,  Node: group,  Next: need,  Prev: page,  Up: Breaks
37
38 `@group': Prevent Page Breaks
39 =============================
40
41   The `@group' command (on a line by itself) is used inside an
42 `@example' or similar construct to begin an unsplittable vertical
43 group, which will appear entirely on one page in the printed output.
44 The group is terminated by a line containing only `@end group'.  These
45 two lines produce no output of their own, and in the Info file output
46 they have no effect at all.
47
48   Although `@group' would make sense conceptually in a wide variety of
49 contexts, its current implementation works reliably only within
50 `@example' and variants, and within `@display', `@format', `@flushleft'
51 and `@flushright'.  *Note Quotations and Examples::.  (What all these
52 commands have in common is that each line of input produces a line of
53 output.)  In other contexts, `@group' can cause anomalous vertical
54 spacing.
55
56   This formatting requirement means that you should write:
57
58      @example
59      @group
60      ...
61      @end group
62      @end example
63
64 with the `@group' and `@end group' commands inside the `@example' and
65 `@end example' commands.
66
67   The `@group' command is most often used to hold an example together
68 on one page.  In this Texinfo manual, more than 100 examples contain
69 text that is enclosed between `@group' and `@end group'.
70
71   If you forget to end a group, you may get strange and unfathomable
72 error messages when you run TeX.  This is because TeX keeps trying to
73 put the rest of the Texinfo file onto the one page and does not start
74 to generate error messages until it has processed considerable text.
75 It is a good rule of thumb to look for a missing `@end group' if you
76 get incomprehensible error messages in TeX.
77
78 \1f
79 File: texinfo.info,  Node: need,  Prev: group,  Up: Breaks
80
81 `@need MILS': Prevent Page Breaks
82 =================================
83
84   A line containing only `@need N' starts a new page in a printed
85 manual if fewer than N mils (thousandths of an inch) remain on the
86 current page.  Do not use braces around the argument N.  The `@need'
87 command has no effect on Info files since they are not paginated.
88
89   This paragraph is preceded by an `@need' command that tells TeX to
90 start a new page if fewer than 800 mils (eight-tenths inch) remain on
91 the page.  It looks like this:
92
93      @need 800
94      This paragraph is preceded by ...
95
96   The `@need' command is useful for preventing orphans (single lines at
97 the bottoms of printed pages).
98
99 \1f
100 File: texinfo.info,  Node: Definition Commands,  Next: Footnotes,  Prev: Breaks,  Up: Top
101
102 Definition Commands
103 *******************
104
105   The `@deffn' command and the other "definition commands" enable you
106 to describe functions, variables, macros, commands, user options,
107 special forms and other such artifacts in a uniform format.
108
109   In the Info file, a definition causes the entity
110 category--`Function', `Variable', or whatever--to appear at the
111 beginning of the first line of the definition, followed by the entity's
112 name and arguments.  In the printed manual, the command causes TeX to
113 print the entity's name and its arguments on the left margin and print
114 the category next to the right margin.  In both output formats, the
115 body of the definition is indented.  Also, the name of the entity is
116 entered into the appropriate index: `@deffn' enters the name into the
117 index of functions, `@defvr' enters it into the index of variables, and
118 so on.
119
120   A manual need not and should not contain more than one definition for
121 a given name.  An appendix containing a summary should use `@table'
122 rather than the definition commands.
123
124 * Menu:
125
126 * Def Cmd Template::            How to structure a description using a
127                                   definition command.
128 * Optional Arguments::          How to handle optional and repeated arguments.
129 * deffnx::                      How to group two or more `first' lines.
130 * Def Cmds in Detail::          All the definition commands.
131 * Def Cmd Conventions::         Conventions for writing definitions.
132 * Sample Function Definition::
133
134 \1f
135 File: texinfo.info,  Node: Def Cmd Template,  Next: Optional Arguments,  Prev: Definition Commands,  Up: Definition Commands
136
137 The Template for a Definition
138 =============================
139
140   The `@deffn' command is used for definitions of entities that
141 resemble functions.  To write a definition using the `@deffn' command,
142 write the `@deffn' command at the beginning of a line and follow it on
143 the same line by the category of the entity, the name of the entity
144 itself, and its arguments (if any).  Then write the body of the
145 definition on succeeding lines.  (You may embed examples in the body.)
146 Finally, end the definition with an `@end deffn' command written on a
147 line of its own.  (The other definition commands follow the same
148 format.)
149
150   The template for a definition looks like this:
151
152      @deffn CATEGORY NAME ARGUMENTS...
153      BODY-OF-DEFINITION
154      @end deffn
155
156 For example,
157
158      @deffn Command forward-word count
159      This command moves point forward @var{count} words
160      (or backward if @var{count} is negative). ...
161      @end deffn
162
163 produces
164
165       - Command: forward-word COUNT
166           This function moves point forward COUNT words (or backward if
167           COUNT is negative). ...
168
169   Capitalize the category name like a title.  If the name of the
170 category contains spaces, as in the phrase `Interactive Command', write
171 braces around it.  For example:
172
173      @deffn {Interactive Command} isearch-forward
174      ...
175      @end deffn
176
177 Otherwise, the second word will be mistaken for the name of the entity.
178
179   Some of the definition commands are more general than others.  The
180 `@deffn' command, for example, is the general definition command for
181 functions and the like--for entities that may take arguments.  When you
182 use this command, you specify the category to which the entity belongs.
183 The `@deffn' command possesses three predefined, specialized
184 variations, `@defun', `@defmac', and `@defspec', that specify the
185 category for you: "Function", "Macro", and "Special Form" respectively.
186 (In Lisp, a special form is an entity much like a function.)  The
187 `@defvr' command also is accompanied by several predefined, specialized
188 variations for describing particular kinds of variables.
189
190   The template for a specialized definition, such as `@defun', is
191 similar to the template for a generalized definition, except that you
192 do not need to specify the category:
193
194      @defun NAME ARGUMENTS...
195      BODY-OF-DEFINITION
196      @end defun
197
198 Thus,
199
200      @defun buffer-end flag
201      This function returns @code{(point-min)} if @var{flag}
202      is less than 1, @code{(point-max)} otherwise.
203      ...
204      @end defun
205
206 produces
207
208       - Function: buffer-end FLAG
209           This function returns `(point-min)' if FLAG is less than 1,
210           `(point-max)' otherwise.  ...
211
212 *Note Sample Function Definition: Sample Function Definition, for a
213 more detailed example of a function definition, including the use of
214 `@example' inside the definition.
215
216   The other specialized commands work like `@defun'.
217
218 \1f
219 File: texinfo.info,  Node: Optional Arguments,  Next: deffnx,  Prev: Def Cmd Template,  Up: Definition Commands
220
221 Optional and Repeated Arguments
222 ===============================
223
224   Some entities take optional or repeated arguments, which may be
225 specified by a distinctive glyph that uses square brackets and
226 ellipses.  For example, a special form often breaks its argument list
227 into separate arguments in more complicated ways than a straightforward
228 function.
229
230   An argument enclosed within square brackets is optional.  Thus,
231 [OPTIONAL-ARG] means that OPTIONAL-ARG is optional.  An argument
232 followed by an ellipsis is optional and may be repeated more than once.
233 Thus, REPEATED-ARGS... stands for zero or more arguments.  Parentheses
234 are used when several arguments are grouped into additional levels of
235 list structure in Lisp.
236
237   Here is the `@defspec' line of an example of an imaginary special
238 form:
239
240       - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
241
242 In this example, the arguments FROM and TO are optional, but must both
243 be present or both absent.  If they are present, INC may optionally be
244 specified as well.  These arguments are grouped with the argument VAR
245 into a list, to distinguish them from BODY, which includes all
246 remaining elements of the form.
247
248   In a Texinfo source file, this `@defspec' line is written like this
249 (except it would not be split over two lines, as it is in this example).
250
251      @defspec foobar (@var{var} [@var{from} @var{to}
252           [@var{inc}]]) @var{body}@dots{}
253
254 The function is listed in the Command and Variable Index under `foobar'.
255
256 \1f
257 File: texinfo.info,  Node: deffnx,  Next: Def Cmds in Detail,  Prev: Optional Arguments,  Up: Definition Commands
258
259 Two or More `First' Lines
260 =========================
261
262   To create two or more `first' or header lines for a definition, follow
263 the first `@deffn' line by a line beginning with `@deffnx'.  The
264 `@deffnx' command works exactly like `@deffn' except that it does not
265 generate extra vertical white space between it and the preceding line.
266
267   For example,
268
269      @deffn {Interactive Command} isearch-forward
270      @deffnx {Interactive Command} isearch-backward
271      These two search commands are similar except ...
272      @end deffn
273
274 produces
275
276  - Interactive Command: isearch-forward
277  - Interactive Command: isearch-backward
278      These two search commands are similar except ...
279
280   Each of the other definition commands has an `x' form: `@defunx',
281 `@defvrx', `@deftypefunx', etc.
282
283   The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
284
285 \1f
286 File: texinfo.info,  Node: Def Cmds in Detail,  Next: Def Cmd Conventions,  Prev: deffnx,  Up: Definition Commands
287
288 The Definition Commands
289 =======================
290
291   Texinfo provides more than a dozen definition commands, all of which
292 are described in this section.
293
294   The definition commands automatically enter the name of the entity in
295 the appropriate index: for example, `@deffn', `@defun', and `@defmac'
296 enter function names in the index of functions; `@defvr' and `@defvar'
297 enter variable names in the index of variables.
298
299   Although the examples that follow mostly illustrate Lisp, the commands
300 can be used for other programming languages.
301
302 * Menu:
303
304 * Functions Commands::          Commands for functions and similar entities.
305 * Variables Commands::          Commands for variables and similar entities.
306 * Typed Functions::             Commands for functions in typed languages.
307 * Typed Variables::             Commands for variables in typed languages.
308 * Abstract Objects::            Commands for object-oriented programming.
309 * Data Types::                  The definition command for data types.
310
311 \1f
312 File: texinfo.info,  Node: Functions Commands,  Next: Variables Commands,  Prev: Def Cmds in Detail,  Up: Def Cmds in Detail
313
314 Functions and Similar Entities
315 ------------------------------
316
317   This section describes the commands for describing functions and
318 similar entities:
319
320 `@deffn CATEGORY NAME ARGUMENTS...'
321      The `@deffn' command is the general definition command for
322      functions, interactive commands, and similar entities that may take
323      arguments.  You must choose a term to describe the category of
324      entity being defined; for example, "Function" could be used if the
325      entity is a function.  The `@deffn' command is written at the
326      beginning of a line and is followed on the same line by the
327      category of entity being described, the name of this particular
328      entity, and its arguments, if any.  Terminate the definition with
329      `@end deffn' on a line of its own.
330
331      For example, here is a definition:
332
333           @deffn Command forward-char nchars
334           Move point forward @var{nchars} characters.
335           @end deffn
336
337      This shows a rather terse definition for a "command" named
338      `forward-char' with one argument, NCHARS.
339
340      `@deffn' prints argument names such as NCHARS in italics or upper
341      case, as if `@var' had been used, because we think of these names
342      as metasyntactic variables--they stand for the actual argument
343      values.  Within the text of the description, write an argument name
344      explicitly with `@var' to refer to the value of the argument.  In
345      the example above, we used `@var{nchars}' in this way.
346
347      The template for `@deffn' is:
348
349           @deffn CATEGORY NAME ARGUMENTS...
350           BODY-OF-DEFINITION
351           @end deffn
352
353 `@defun NAME ARGUMENTS...'
354      The `@defun' command is the definition command for functions.
355      `@defun' is equivalent to `@deffn Function ...'.
356
357      For example,
358
359           @defun set symbol new-value
360           Change the value of the symbol @var{symbol}
361           to @var{new-value}.
362           @end defun
363
364      shows a rather terse definition for a function `set' whose
365      arguments are SYMBOL and NEW-VALUE.  The argument names on the
366      `@defun' line automatically appear in italics or upper case as if
367      they were enclosed in `@var'.  Terminate the definition with `@end
368      defun' on a line of its own.
369
370      The template is:
371
372           @defun FUNCTION-NAME ARGUMENTS...
373           BODY-OF-DEFINITION
374           @end defun
375
376      `@defun' creates an entry in the index of functions.
377
378 `@defmac NAME ARGUMENTS...'
379      The `@defmac' command is the definition command for macros.
380      `@defmac' is equivalent to `@deffn Macro ...' and works like
381      `@defun'.
382
383 `@defspec NAME ARGUMENTS...'
384      The `@defspec' command is the definition command for special
385      forms.  (In Lisp, a special form is an entity much like a function,
386      *note Special Forms: (lispref)Special Forms..)  `@defspec' is
387      equivalent to `@deffn {Special Form} ...' and works like `@defun'.
388
389 \1f
390 File: texinfo.info,  Node: Variables Commands,  Next: Typed Functions,  Prev: Functions Commands,  Up: Def Cmds in Detail
391
392 Variables and Similar Entities
393 ------------------------------
394
395   Here are the commands for defining variables and similar entities:
396
397 `@defvr CATEGORY NAME'
398      The `@defvr' command is a general definition command for something
399      like a variable--an entity that records a value.  You must choose
400      a term to describe the category of entity being defined; for
401      example, "Variable" could be used if the entity is a variable.
402      Write the `@defvr' command at the beginning of a line and followed
403      it on the same line by the category of the entity and the name of
404      the entity.
405
406      Capitalize the category name like a title.  If the name of the
407      category contains spaces, as in the name "User Option", enclose it
408      in braces.  Otherwise, the second word will be mistaken for the
409      name of the entity.  For example,
410
411           @defvr {User Option} fill-column
412           This buffer-local variable specifies
413           the maximum width of filled lines.
414           ...
415           @end defvr
416
417      Terminate the definition with `@end defvr' on a line of its own.
418
419      The template is:
420
421           @defvr CATEGORY NAME
422           BODY-OF-DEFINITION
423           @end defvr
424
425      `@defvr' creates an entry in the index of variables for NAME.
426
427 `@defvar NAME'
428      The `@defvar' command is the definition command for variables.
429      `@defvar' is equivalent to `@defvr Variable ...'.
430
431      For example:
432
433           @defvar kill-ring
434           ...
435           @end defvar
436
437      The template is:
438
439           @defvar NAME
440           BODY-OF-DEFINITION
441           @end defvar
442
443      `@defvar' creates an entry in the index of variables for NAME.
444
445 `@defopt NAME'
446      The `@defopt' command is the definition command for "user
447      options", i.e., variables intended for users to change according to
448      taste; Emacs has many such (*note Variables: (xemacs)Variables.).
449      `@defopt' is equivalent to `@defvr {User Option} ...' and works
450      like `@defvar'.
451
452 \1f
453 File: texinfo.info,  Node: Typed Functions,  Next: Typed Variables,  Prev: Variables Commands,  Up: Def Cmds in Detail
454
455 Functions in Typed Languages
456 ----------------------------
457
458   The `@deftypefn' command and its variations are for describing
459 functions in languages in which you must declare types of variables and
460 functions, such as C and C++.
461
462 `@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
463      The `@deftypefn' command is the general definition command for
464      functions and similar entities that may take arguments and that are
465      typed.  The `@deftypefn' command is written at the beginning of a
466      line and is followed on the same line by the category of entity
467      being described, the type of the returned value, the name of this
468      particular entity, and its arguments, if any.
469
470      For example,
471
472           @deftypefn {Library Function} int foobar
473              (int @var{foo}, float @var{bar})
474           ...
475           @end deftypefn
476
477      (where the text before the "...", shown above as two lines, would
478      actually be a single line in a real Texinfo file) produces the
479      following in Info:
480
481           -- Library Function: int foobar (int FOO, float BAR)
482           ...
483
484      This means that `foobar' is a "library function" that returns an
485      `int', and its arguments are FOO (an `int') and BAR (a `float').
486
487      The argument names that you write in `@deftypefn' are not subject
488      to an implicit `@var'--since the actual names of the arguments in
489      `@deftypefn' are typically scattered among data type names and
490      keywords, Texinfo cannot find them without help.  Instead, you
491      must write `@var' explicitly around the argument names.  In the
492      example above, the argument names are `foo' and `bar'.
493
494      The template for `@deftypefn' is:
495
496           @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
497           BODY-OF-DESCRIPTION
498           @end deftypefn
499
500      Note that if the CATEGORY or DATA TYPE is more than one word then
501      it must be enclosed in braces to make it a single argument.
502
503      If you are describing a procedure in a language that has packages,
504      such as Ada, you might consider using `@deftypefn' in a manner
505      somewhat contrary to the convention described in the preceding
506      paragraphs.
507
508      For example:
509
510           @deftypefn stacks private push
511                   (@var{s}:in out stack;
512                   @var{n}:in integer)
513           ...
514           @end deftypefn
515
516      (The `@deftypefn' arguments are shown split into three lines, but
517      would be a single line in a real Texinfo file.)
518
519      In this instance, the procedure is classified as belonging to the
520      package `stacks' rather than classified as a `procedure' and its
521      data type is described as `private'.  (The name of the procedure
522      is `push', and its arguments are S and N.)
523
524      `@deftypefn' creates an entry in the index of functions for NAME.
525
526 `@deftypefun DATA-TYPE NAME ARGUMENTS...'
527      The `@deftypefun' command is the specialized definition command
528      for functions in typed languages.  The command is equivalent to
529      `@deftypefn Function ...'.
530
531      Thus,
532
533           @deftypefun int foobar (int @var{foo}, float @var{bar})
534           ...
535           @end deftypefun
536
537      produces the following in Info:
538
539           -- Function: int foobar (int FOO, float BAR)
540           ...
541
542      The template is:
543
544           @deftypefun TYPE NAME ARGUMENTS...
545           BODY-OF-DESCRIPTION
546           @end deftypefun
547
548      `@deftypefun' creates an entry in the index of functions for NAME.
549
550 \1f
551 File: texinfo.info,  Node: Typed Variables,  Next: Abstract Objects,  Prev: Typed Functions,  Up: Def Cmds in Detail
552
553 Variables in Typed Languages
554 ----------------------------
555
556   Variables in typed languages are handled in a manner similar to
557 functions in typed languages.  *Note Typed Functions::.  The general
558 definition command `@deftypevr' corresponds to `@deftypefn' and the
559 specialized definition command `@deftypevar' corresponds to
560 `@deftypefun'.
561
562 `@deftypevr CATEGORY DATA-TYPE NAME'
563      The `@deftypevr' command is the general definition command for
564      something like a variable in a typed language--an entity that
565      records a value.  You must choose a term to describe the category
566      of the entity being defined; for example, "Variable" could be used
567      if the entity is a variable.
568
569      The `@deftypevr' command is written at the beginning of a line and
570      is followed on the same line by the category of the entity being
571      described, the data type, and the name of this particular entity.
572
573      For example:
574
575           @deftypevr {Global Flag} int enable
576           ...
577           @end deftypevr
578
579      produces the following in Info:
580
581           -- Global Flag: int enable
582           ...
583
584      The template is:
585
586           @deftypevr CATEGORY DATA-TYPE NAME
587           BODY-OF-DESCRIPTION
588           @end deftypevr
589
590      `@deftypevr' creates an entry in the index of variables for NAME.
591
592 `@deftypevar DATA-TYPE NAME'
593      The `@deftypevar' command is the specialized definition command
594      for variables in typed languages.  `@deftypevar' is equivalent to
595      `@deftypevr Variable ...'.
596
597      For example:
598
599           @deftypevar int fubar
600           ...
601           @end deftypevar
602
603      produces the following in Info:
604
605           -- Variable: int fubar
606           ...
607
608      The template is:
609
610           @deftypevar DATA-TYPE NAME
611           BODY-OF-DESCRIPTION
612           @end deftypevar
613
614      `@deftypevar' creates an entry in the index of variables for NAME.
615
616 \1f
617 File: texinfo.info,  Node: Abstract Objects,  Next: Data Types,  Prev: Typed Variables,  Up: Def Cmds in Detail
618
619 Object-Oriented Programming
620 ---------------------------
621
622   Here are the commands for formatting descriptions about abstract
623 objects, such as are used in object-oriented programming.  A class is a
624 defined type of abstract object.  An instance of a class is a
625 particular object that has the type of the class.  An instance variable
626 is a variable that belongs to the class but for which each instance has
627 its own value.
628
629   In a definition, if the name of a class is truly a name defined in the
630 programming system for a class, then you should write an `@code' around
631 it.  Otherwise, it is printed in the usual text font.
632
633 `@defcv CATEGORY CLASS NAME'
634      The `@defcv' command is the general definition command for
635      variables associated with classes in object-oriented programming.
636      The `@defcv' command is followed by three arguments: the category
637      of thing being defined, the class to which it belongs, and its
638      name.  Thus,
639
640           @defcv {Class Option} Window border-pattern
641           ...
642           @end defcv
643
644      illustrates how you would write the first line of a definition of
645      the `border-pattern' class option of the class `Window'.
646
647      The template is
648
649           @defcv CATEGORY CLASS NAME
650           ...
651           @end defcv
652
653      `@defcv' creates an entry in the index of variables.
654
655 `@defivar CLASS NAME'
656      The `@defivar' command is the definition command for instance
657      variables in object-oriented programming.  `@defivar' is
658      equivalent to `@defcv {Instance Variable} ...'
659
660      The template is:
661
662           @defivar CLASS INSTANCE-VARIABLE-NAME
663           BODY-OF-DEFINITION
664           @end defivar
665
666      `@defivar' creates an entry in the index of variables.
667
668 `@defop CATEGORY CLASS NAME ARGUMENTS...'
669      The `@defop' command is the general definition command for
670      entities that may resemble methods in object-oriented programming.
671      These entities take arguments, as functions do, but are associated
672      with particular classes of objects.
673
674      For example, some systems have constructs called "wrappers" that
675      are associated with classes as methods are, but that act more like
676      macros than like functions.  You could use `@defop Wrapper' to
677      describe one of these.
678
679      Sometimes it is useful to distinguish methods and "operations".
680      You can think of an operation as the specification for a method.
681      Thus, a window system might specify that all window classes have a
682      method named `expose'; we would say that this window system
683      defines an `expose' operation on windows in general.  Typically,
684      the operation has a name and also specifies the pattern of
685      arguments; all methods that implement the operation must accept
686      the same arguments, since applications that use the operation do
687      so without knowing which method will implement it.
688
689      Often it makes more sense to document operations than methods.  For
690      example, window application developers need to know about the
691      `expose' operation, but need not be concerned with whether a given
692      class of windows has its own method to implement this operation.
693      To describe this operation, you would write:
694
695           @defop Operation windows expose
696
697      The `@defop' command is written at the beginning of a line and is
698      followed on the same line by the overall name of the category of
699      operation, the name of the class of the operation, the name of the
700      operation, and its arguments, if any.
701
702      The template is:
703
704           @defop CATEGORY CLASS NAME ARGUMENTS...
705           BODY-OF-DEFINITION
706           @end defop
707
708      `@defop' creates an entry, such as ``expose' on `windows'', in the
709      index of functions.
710
711 `@defmethod CLASS NAME ARGUMENTS...'
712      The `@defmethod' command is the definition command for methods in
713      object-oriented programming.  A method is a kind of function that
714      implements an operation for a particular class of objects and its
715      subclasses.  In the Lisp Machine, methods actually were functions,
716      but they were usually defined with `defmethod'.
717
718      `@defmethod' is equivalent to `@defop Method ...'.  The command is
719      written at the beginning of a line and is followed by the name of
720      the class of the method, the name of the method, and its
721      arguments, if any.
722
723      For example,
724
725           @defmethod `bar-class' bar-method argument
726           ...
727           @end defmethod
728
729      illustrates the definition for a method called `bar-method' of the
730      class `bar-class'.  The method takes an argument.
731
732      The template is:
733
734           @defmethod CLASS METHOD-NAME ARGUMENTS...
735           BODY-OF-DEFINITION
736           @end defmethod
737
738      `@defmethod' creates an entry, such as ``bar-method' on
739      `bar-class'', in the index of functions.
740
741 `@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
742      The `@deftypemethod' command is the definition command for methods
743      in object-oriented typed languages, such as C++ and Java.  It is
744      similar to the `@defmethod' command with the addition of the
745      DATA-TYPE parameter to specify the return type of the method.
746
747 \1f
748 File: texinfo.info,  Node: Data Types,  Prev: Abstract Objects,  Up: Def Cmds in Detail
749
750 Data Types
751 ----------
752
753   Here is the command for data types:
754
755 `@deftp CATEGORY NAME ATTRIBUTES...'
756      The `@deftp' command is the generic definition command for data
757      types.  The command is written at the beginning of a line and is
758      followed on the same line by the category, by the name of the type
759      (which is a word like `int' or `float'), and then by names of
760      attributes of objects of that type.  Thus, you could use this
761      command for describing `int' or `float', in which case you could
762      use `data type' as the category.  (A data type is a category of
763      certain objects for purposes of deciding which operations can be
764      performed on them.)
765
766      In Lisp, for example,  "pair" names a particular data type, and an
767      object of that type has two slots called the CAR and the CDR.
768      Here is how you would write the first line of a definition of
769      `pair'.
770
771           @deftp {Data type} pair car cdr
772           ...
773           @end deftp
774
775      The template is:
776
777           @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
778           BODY-OF-DEFINITION
779           @end deftp
780
781      `@deftp' creates an entry in the index of data types.
782
783 \1f
784 File: texinfo.info,  Node: Def Cmd Conventions,  Next: Sample Function Definition,  Prev: Def Cmds in Detail,  Up: Definition Commands
785
786 Conventions for Writing Definitions
787 ===================================
788
789   When you write a definition using `@deffn', `@defun', or one of the
790 other definition commands, please take care to use arguments that
791 indicate the meaning, as with the COUNT argument to the `forward-word'
792 function.  Also, if the name of an argument contains the name of a
793 type, such as INTEGER, take care that the argument actually is of that
794 type.
795
796 \1f
797 File: texinfo.info,  Node: Sample Function Definition,  Prev: Def Cmd Conventions,  Up: Definition Commands
798
799 A Sample Function Definition
800 ============================
801
802   A function definition uses the `@defun' and `@end defun' commands.
803 The name of the function follows immediately after the `@defun' command
804 and it is followed, on the same line, by the parameter list.
805
806   Here is a definition from *Note Calling Functions: (lispref)Calling
807 Functions.
808
809       - Function: apply FUNCTION &rest ARGUMENTS
810           `apply' calls FUNCTION with ARGUMENTS, just like `funcall'
811           but with one difference: the last of ARGUMENTS is a list of
812           arguments to give to FUNCTION, rather than a single argument.
813           We also say that this list is "appended" to the other
814           arguments.
815
816           `apply' returns the result of calling FUNCTION.  As with
817           `funcall', FUNCTION must either be a Lisp function or a
818           primitive function; special forms and macros do not make
819           sense in `apply'.
820
821                (setq f 'list)
822                     => list
823                (apply f 'x 'y 'z)
824                error--> Wrong type argument: listp, z
825                (apply '+ 1 2 '(3 4))
826                     => 10
827                (apply '+ '(1 2 3 4))
828                     => 10
829                
830                (apply 'append '((a b c) nil (x y z) nil))
831                     => (a b c x y z)
832
833           An interesting example of using `apply' is found in the
834           description of `mapcar'.
835
836   In the Texinfo source file, this example looks like this:
837
838      @defun apply function &rest arguments
839      
840      @code{apply} calls @var{function} with
841      @var{arguments}, just like @code{funcall} but with one
842      difference: the last of @var{arguments} is a list of
843      arguments to give to @var{function}, rather than a single
844      argument.  We also say that this list is @dfn{appended}
845      to the other arguments.
846      
847      @code{apply} returns the result of calling
848      @var{function}.  As with @code{funcall},
849      @var{function} must either be a Lisp function or a
850      primitive function; special forms and macros do not make
851      sense in @code{apply}.
852      
853      @example
854      (setq f 'list)
855           @result{} list
856      (apply f 'x 'y 'z)
857      @error{} Wrong type argument: listp, z
858      (apply '+ 1 2 '(3 4))
859           @result{} 10
860      (apply '+ '(1 2 3 4))
861           @result{} 10
862      
863      (apply 'append '((a b c) nil (x y z) nil))
864           @result{} (a b c x y z)
865      @end example
866      
867      An interesting example of using @code{apply} is found
868      in the description of @code{mapcar}.@refill
869      @end defun
870
871 In this manual, this function is listed in the Command and Variable
872 Index under `apply'.
873
874   Ordinary variables and user options are described using a format like
875 that for functions except that variables do not take arguments.
876
877 \1f
878 File: texinfo.info,  Node: Footnotes,  Next: Conditionals,  Prev: Definition Commands,  Up: Top
879
880 Footnotes
881 *********
882
883   A "footnote" is for a reference that documents or elucidates the
884 primary text.(1) (*note Footnotes-Footnotes::)
885
886 * Menu:
887
888 * Footnote Commands::           How to write a footnote in Texinfo.
889 * Footnote Styles::             Controlling how footnotes appear in Info.
890
891 \1f
892 File: texinfo.info,  Node: Footnotes-Footnotes,  Up: Footnotes
893
894   (1) A footnote should complement or expand upon the primary text, but
895 a reader should not need to read a footnote to understand the primary
896 text.  For a thorough discussion of footnotes, see `The Chicago Manual
897 of Style', which is published by the University of Chicago Press.
898
899 \1f
900 File: texinfo.info,  Node: Footnote Commands,  Next: Footnote Styles,  Prev: Footnotes,  Up: Footnotes
901
902 Footnote Commands
903 =================
904
905   In Texinfo, footnotes are created with the `@footnote' command.  This
906 command is followed immediately by a left brace, then by the text of
907 the footnote, and then by a terminating right brace.  Footnotes may be
908 of any length (they will be broken across pages if necessary), but are
909 usually short.  The template is:
910
911      ordinary text@footnote{TEXT OF FOOTNOTE}
912
913   As shown here, the `@footnote' command should come right after the
914 text being footnoted, with no intervening space; otherwise, the
915 formatters the footnote mark might end up starting up a line.
916
917   For example, this clause is followed by a sample footnote(1) (*note
918 Footnote Commands-Footnotes::); in the Texinfo source, it looks like
919 this:
920
921      ...a sample footnote@footnote{Here is the sample
922      footnote.}; in the Texinfo source...
923
924   *Warning:* Don't use footnotes in the argument of the `@item' command
925 for a `@table' table.  This doesn't work, and because of limitations of
926 TeX, there is no way to fix it.  You must put the footnote into the
927 body text of the table.
928
929   In a printed manual or book, the reference mark for a footnote is a
930 small, superscripted number; the text of the footnote appears at the
931 bottom of the page, below a horizontal line.
932
933   In Info, the reference mark for a footnote is a pair of parentheses
934 with the footnote number between them, like this: `(1)'.
935
936 \1f
937 File: texinfo.info,  Node: Footnote Commands-Footnotes,  Up: Footnote Commands
938
939   (1) Here is the sample footnote.
940
941 \1f
942 File: texinfo.info,  Node: Footnote Styles,  Prev: Footnote Commands,  Up: Footnotes
943
944 Footnote Styles
945 ===============
946
947   Info has two footnote styles, which determine where the text of the
948 footnote is located:
949
950    * In the `End' node style, all the footnotes for a single node are
951      placed at the end of that node.  The footnotes are separated from
952      the rest of the node by a line of dashes with the word `Footnotes'
953      within it.  Each footnote begins with an `(N)' reference mark.
954
955      Here is an example of a single footnote in the end of node style:
956
957            --------- Footnotes ---------
958           
959           (1)  Here is a sample footnote.
960
961    * In the `Separate' node style, all the footnotes for a single node
962      are placed in an automatically constructed node of their own.  In
963      this style, a "footnote reference" follows each `(N)' reference
964      mark in the body of the node.  The footnote reference is actually
965      a cross reference which you use to reach the footnote node.
966
967      The name of the node containing the footnotes is constructed by
968      appending `-Footnotes' to the name of the node that contains the
969      footnotes. (Consequently, the footnotes' node for the `Footnotes'
970      node is `Footnotes-Footnotes'!)  The footnotes' node has an `Up'
971      node pointer that leads back to its parent node.
972
973      Here is how the first footnote in this manual looks after being
974      formatted for Info in the separate node style:
975
976           File: texinfo.info  Node: Overview-Footnotes, Up: Overview
977           
978           (1) Note that the first syllable of "Texinfo" is
979           pronounced like "speck", not "hex". ...
980
981   A Texinfo file may be formatted into an Info file with either footnote
982 style.
983
984   Use the `@footnotestyle' command to specify an Info file's footnote
985 style.  Write this command at the beginning of a line followed by an
986 argument, either `end' for the end node style or `separate' for the
987 separate node style.
988
989   For example,
990
991      @footnotestyle end
992
993 or
994      @footnotestyle separate
995
996   Write an `@footnotestyle' command before or shortly after the
997 end-of-header line at the beginning of a Texinfo file.  (If you include
998 the `@footnotestyle' command between the start-of-header and
999 end-of-header lines, the region formatting commands will format
1000 footnotes as specified.)
1001
1002   If you do not specify a footnote style, the formatting commands use
1003 their default style.  Currently, `texinfo-format-buffer' and
1004 `texinfo-format-region' use the `separate' style and `makeinfo' uses
1005 the `end' style.
1006
1007   This chapter contains two footnotes.
1008
1009 \1f
1010 File: texinfo.info,  Node: Conditionals,  Next: Macros,  Prev: Footnotes,  Up: Top
1011
1012 Conditionally Visible Text
1013 **************************
1014
1015   Sometimes it is good to use different text for a printed manual and
1016 its corresponding Info file.  In this case, you can use the
1017 "conditional commands" to specify which text is for the printed manual
1018 and which is for the Info file.
1019
1020 * Menu:
1021
1022 * Conditional Commands::        Specifying text for HTML, Info, or TeX.
1023 * Conditional Not Commands::    Specifying text for not HTML, Info, or TeX.
1024 * Raw Formatter Commands::      Using raw TeX or HTML commands.
1025 * set clear value::             Designating which text to format (for
1026                                   all output formats); and how to set a
1027                                   flag to a string that you can insert.
1028
1029 \1f
1030 File: texinfo.info,  Node: Conditional Commands,  Next: Conditional Not Commands,  Prev: Conditionals,  Up: Conditionals
1031
1032 Conditional Commands
1033 ====================
1034
1035   `@ifinfo' begins segments of text that should be ignored by TeX when
1036 it typesets the printed manual.  The segment of text appears only in
1037 the Info file.  The `@ifinfo' command should appear on a line by
1038 itself;  end the Info-only text with a line containing `@end ifinfo' by
1039 itself.  At the beginning of a Texinfo file, the Info permissions are
1040 contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
1041 Info Summary and Permissions::.)
1042
1043   The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
1044 and `@end ifinfo' commands, except that they specify text that will
1045 appear in the printed manual but not in the Info file.  Likewise for
1046 `@ifhtml' and `@end ifhtml', which specify text to appear only in HTML
1047 output.
1048
1049   For example,
1050
1051      @iftex
1052      This text will appear only in the printed manual.
1053      @end iftex
1054      @ifinfo
1055      However, this text will appear only in Info.
1056      @end ifinfo
1057
1058 The preceding example produces the following line: However, this text
1059 will appear only in Info.
1060
1061 Note how you only see one of the two lines, depending on whether you
1062 are reading the Info version or the printed version of this manual.
1063
1064   The `@titlepage' command is a special variant of `@iftex' that is
1065 used for making the title and copyright pages of the printed manual.
1066 (*Note `@titlepage': titlepage.)
1067
1068 \1f
1069 File: texinfo.info,  Node: Conditional Not Commands,  Next: Raw Formatter Commands,  Prev: Conditional Commands,  Up: Conditionals
1070
1071 Conditional Not Commands
1072 ========================
1073
1074   You can specify text to be included in any output format *other* than
1075 some given one with the `@ifnot...' commands:
1076      @ifnothtml ... @end ifnothtml
1077      @ifnotinfo ... @end ifnotinfo
1078      @ifnottex ... @end ifnottex
1079
1080 (The `@ifnot...' command and the `@end' command must actually appear on
1081 lines by themselves.)
1082
1083   If the output file is not being made for the given format, the region
1084 is included.  Otherwise, it is ignored.
1085
1086   The regions delimited by these commands are ordinary Texinfo source as
1087 with `@iftex', not raw formatter source as with `@tex'.
1088
1089 \1f
1090 File: texinfo.info,  Node: Raw Formatter Commands,  Next: set clear value,  Prev: Conditional Not Commands,  Up: Conditionals
1091
1092 Raw Formatter Commands
1093 ======================
1094
1095   Inside a region delineated by `@iftex' and `@end iftex', you can
1096 embed some raw TeX commands.  Info will ignore these commands since
1097 they are only in that part of the file which is seen by TeX.  You can
1098 write the TeX commands as you would write them in a normal TeX file,
1099 except that you must replace the `\' used by TeX with an `@'.  For
1100 example, in the `@titlepage' section of a Texinfo file, you can use the
1101 TeX command `@vskip' to format the copyright page.  (The `@titlepage'
1102 command causes Info to ignore the region automatically, as it does with
1103 the `@iftex' command.)
1104
1105   However, many features of plain TeX will not work, as they are
1106 overridden by Texinfo features.
1107
1108   You can enter plain TeX completely, and use `\' in the TeX commands,
1109 by delineating a region with the `@tex' and `@end tex' commands.  (The
1110 `@tex' command also causes Info to ignore the region, like the `@iftex'
1111 command.)  The sole exception is that `@' chracter still introduces a
1112 command, so that `@end tex' can be recognized properly.
1113
1114   For example, here is a mathematical expression written in plain TeX:
1115
1116      @tex
1117      $$ \chi^2 = \sum_{i=1}^N
1118                \left (y_i - (a + b x_i)
1119                \over \sigma_i\right)^2 $$
1120      @end tex
1121
1122 The output of this example will appear only in a printed manual.  If
1123 you are reading this in Info, you will not see the equation that appears
1124 in the printed manual.
1125
1126   Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
1127 region to be included in HTML output only, and `@html ...  @end ifhtml'
1128 for a region of raw HTML (again, except that `@' is still the escape
1129 character, so the `@end' command can be recognized.)
1130
1131 \1f
1132 File: texinfo.info,  Node: set clear value,  Prev: Raw Formatter Commands,  Up: Conditionals
1133
1134 `@set', `@clear', and `@value'
1135 ==============================
1136
1137   You can direct the Texinfo formatting commands to format or ignore
1138 parts of a Texinfo file with the `@set', `@clear', `@ifset', and
1139 `@ifclear' commands.
1140
1141   In addition, you can use the `@set FLAG' command to set the value of
1142 FLAG to a string of characters; and use `@value{FLAG}' to insert that
1143 string.  You can use `@set', for example, to set a date and use
1144 `@value' to insert the date in several places in the Texinfo file.
1145
1146 * Menu:
1147
1148 * ifset ifclear::               Format a region if a flag is set.
1149 * value::                       Replace a flag with a string.
1150 * value Example::               An easy way to update edition information.
1151
1152 \1f
1153 File: texinfo.info,  Node: ifset ifclear,  Next: value,  Prev: set clear value,  Up: set clear value
1154
1155 `@ifset' and `@ifclear'
1156 -----------------------
1157
1158   When a FLAG is set, the Texinfo formatting commands format text
1159 between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
1160 When the FLAG is cleared, the Texinfo formatting commands do *not*
1161 format the text.
1162
1163   Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
1164 can be any single word.  The format for the command looks like this:
1165
1166      @set FLAG
1167
1168   Write the conditionally formatted text between `@ifset FLAG' and
1169 `@end ifset' commands, like this:
1170
1171      @ifset FLAG
1172      CONDITIONAL-TEXT
1173      @end ifset
1174
1175   For example, you can create one document that has two variants, such
1176 as a manual for a `large' and `small' model:
1177
1178      You can use this machine to dig up shrubs
1179      without hurting them.
1180      
1181      @set large
1182      
1183      @ifset large
1184      It can also dig up fully grown trees.
1185      @end ifset
1186      
1187      Remember to replant promptly ...
1188
1189 In the example, the formatting commands will format the text between
1190 `@ifset large' and `@end ifset' because the `large' flag is set.
1191
1192   Use the `@clear FLAG' command to turn off, or "clear", a flag.
1193 Clearing a flag is the opposite of setting a flag.  The command looks
1194 like this:
1195
1196      @clear FLAG
1197
1198 Write the command on a line of its own.
1199
1200   When FLAG is cleared, the Texinfo formatting commands do *not* format
1201 the text between `@ifset FLAG' and `@end ifset'; that text is ignored
1202 and does not appear in either printed or Info output.
1203
1204   For example, if you clear the flag of the preceding example by writing
1205 an `@clear large' command after the `@set large' command (but before
1206 the conditional text), then the Texinfo formatting commands ignore the
1207 text between the `@ifset large' and `@end ifset' commands.  In the
1208 formatted output, that text does not appear; in both printed and Info
1209 output, you see only the lines that say, "You can use this machine to
1210 dig up shrubs without hurting them.  Remember to replant promptly ...".
1211
1212   If a flag is cleared with an `@clear FLAG' command, then the
1213 formatting commands format text between subsequent pairs of `@ifclear'
1214 and `@end ifclear' commands.  But if the flag is set with `@set FLAG',
1215 then the formatting commands do *not* format text between an `@ifclear'
1216 and an `@end ifclear' command; rather, they ignore that text.  An
1217 `@ifclear' command looks like this:
1218
1219      @ifclear FLAG
1220
1221   In brief, the commands are:
1222
1223 `@set FLAG'
1224      Tell the Texinfo formatting commands that FLAG is set.
1225
1226 `@clear FLAG'
1227      Tell the Texinfo formatting commands that FLAG is cleared.
1228
1229 `@ifset FLAG'
1230      If FLAG is set, tell the Texinfo formatting commands to format the
1231      text up to the following `@end ifset' command.
1232
1233      If FLAG is cleared, tell the Texinfo formatting commands to ignore
1234      text up to the following `@end ifset' command.
1235
1236 `@ifclear FLAG'
1237      If FLAG is set, tell the Texinfo formatting commands to ignore the
1238      text up to the following `@end ifclear' command.
1239
1240      If FLAG is cleared, tell the Texinfo formatting commands to format
1241      the text up to the following `@end ifclear' command.
1242
1243 \1f
1244 File: texinfo.info,  Node: value,  Next: value Example,  Prev: ifset ifclear,  Up: set clear value
1245
1246 `@value'
1247 --------
1248
1249   You can use the `@set' command to specify a value for a flag, which
1250 is expanded by the `@value' command.  The value is a string a
1251 characters.
1252
1253   Write the `@set' command like this:
1254
1255      @set foo This is a string.
1256
1257 This sets the value of `foo' to "This is a string."
1258
1259   The Texinfo formatters replace an `@value{FLAG}' command with the
1260 string to which FLAG is set.
1261
1262   Thus, when `foo' is set as shown above, the Texinfo formatters convert
1263
1264      @value{foo}
1265 to
1266      This is a string.
1267
1268   You can write an `@value' command within a paragraph; but you must
1269 write an `@set' command on a line of its own.
1270
1271   If you write the `@set' command like this:
1272
1273      @set foo
1274
1275 without specifying a string, the value of `foo' is an empty string.
1276
1277   If you clear a previously set flag with an `@clear FLAG' command, a
1278 subsequent `@value{flag}' command is invalid and the string is replaced
1279 with an error message that says `{No value for "FLAG"}'.
1280
1281   For example, if you set `foo' as follows:
1282
1283      @set how-much very, very, very
1284
1285 then the formatters transform
1286
1287      It is a @value{how-much} wet day.
1288 into
1289      It is a very, very, very wet day.
1290
1291   If you write
1292
1293      @clear how-much
1294
1295 then the formatters transform
1296
1297      It is a @value{how-much} wet day.
1298 into
1299      It is a {No value for "how-much"} wet day.
1300
1301 \1f
1302 File: texinfo.info,  Node: value Example,  Prev: value,  Up: set clear value
1303
1304 `@value' Example
1305 ----------------
1306
1307   You can use the `@value' command to limit the number of places you
1308 need to change when you record an update to a manual.  Here is how it
1309 is done in `The GNU Make Manual':
1310
1311 Set the flags:
1312
1313      @set EDITION 0.35 Beta
1314      @set VERSION 3.63 Beta
1315      @set UPDATED 14 August 1992
1316      @set UPDATE-MONTH August 1992
1317
1318 Write text for the first `@ifinfo' section, for people reading the
1319 Texinfo file:
1320
1321      This is Edition @value{EDITION},
1322      last updated @value{UPDATED},
1323      of @cite{The GNU Make Manual},
1324      for @code{make}, Version @value{VERSION}.
1325
1326 Write text for the title page, for people reading the printed manual:
1327
1328      @title GNU Make
1329      @subtitle A Program for Directing Recompilation
1330      @subtitle Edition @value{EDITION}, ...
1331      @subtitle @value{UPDATE-MONTH}
1332
1333 (On a printed cover, a date listing the month and the year looks less
1334 fussy than a date listing the day as well as the month and year.)
1335
1336 Write text for the Top node, for people reading the Info file:
1337
1338      This is Edition @value{EDITION}
1339      of the @cite{GNU Make Manual},
1340      last updated @value{UPDATED}
1341      for @code{make} Version @value{VERSION}.
1342
1343   After you format the manual, the text in the first `@ifinfo' section
1344 looks like this:
1345
1346      This is Edition 0.35 Beta, last updated 14 August 1992,
1347      of `The GNU Make Manual', for `make', Version 3.63 Beta.
1348
1349   When you update the manual, change only the values of the flags; you
1350 do not need to rewrite the three sections.
1351
1352 \1f
1353 File: texinfo.info,  Node: Macros,  Next: Format/Print Hardcopy,  Prev: Conditionals,  Up: Top
1354
1355 Macros: Defining New Texinfo Commands
1356 *************************************
1357
1358   A Texinfo "macro" allows you to define a new Texinfo command as any
1359 sequence of text and/or existing commands (including other macros).  The
1360 macro can have any number of "parameters"--text you supply each time
1361 you use the macro.  (This has nothing to do with the `@defmac' command,
1362 which is for documenting macros in the subject of the manual; *note Def
1363 Cmd Template::..)
1364
1365 * Menu:
1366
1367 * Defining Macros::             Both defining and undefining new commands.
1368 * Invoking Macros::             Using a macro, once you've defined it.
1369
1370 \1f
1371 File: texinfo.info,  Node: Defining Macros,  Next: Invoking Macros,  Prev: Macros,  Up: Macros
1372
1373 Defining Macros
1374 ===============
1375
1376   You use the Texinfo `@macro' command to define a macro.  For example:
1377
1378      @macro MACRO-NAME{PARAM1, PARAM2, ...}
1379      TEXT ... \PARAM1\ ...
1380      @end macro
1381
1382   The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
1383 when the macro is subsequently used in the document (see the next
1384 section).
1385
1386   If a macro needs no parameters, you can define it either with an empty
1387 list (`@macro foo {}') or with no braces at all (`@macro foo').
1388
1389   The definition or "body" of the macro can contain any Texinfo
1390 commands, including previously-defined macros.  (It is not possible to
1391 have mutually recursive Texinfo macros.)  In the body, instances of a
1392 parameter name surrounded by backslashes, as in `\PARAM1\' in the
1393 example above, are replaced by the corresponding argument from the
1394 macro invocation.
1395
1396   You can undefine a macro FOO with `@unmacro FOO'.  It is not an error
1397 to undefine a macro that is already undefined.  For example:
1398
1399      @unmacro foo
1400