+++ /dev/null
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
-
-INFO-DIR-SECTION Texinfo documentation system
-START-INFO-DIR-ENTRY
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
-* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
-END-INFO-DIR-ENTRY
-
- This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
-
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
-Foundation, Inc.
-
- This edition is for Texinfo version 3.12.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
-
-\1f
-File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks
-
-`@group': Prevent Page Breaks
-=============================
-
- The `@group' command (on a line by itself) is used inside an
-`@example' or similar construct to begin an unsplittable vertical
-group, which will appear entirely on one page in the printed output.
-The group is terminated by a line containing only `@end group'. These
-two lines produce no output of their own, and in the Info file output
-they have no effect at all.
-
- Although `@group' would make sense conceptually in a wide variety of
-contexts, its current implementation works reliably only within
-`@example' and variants, and within `@display', `@format', `@flushleft'
-and `@flushright'. *Note Quotations and Examples::. (What all these
-commands have in common is that each line of input produces a line of
-output.) In other contexts, `@group' can cause anomalous vertical
-spacing.
-
- This formatting requirement means that you should write:
-
- @example
- @group
- ...
- @end group
- @end example
-
-with the `@group' and `@end group' commands inside the `@example' and
-`@end example' commands.
-
- The `@group' command is most often used to hold an example together
-on one page. In this Texinfo manual, more than 100 examples contain
-text that is enclosed between `@group' and `@end group'.
-
- If you forget to end a group, you may get strange and unfathomable
-error messages when you run TeX. This is because TeX keeps trying to
-put the rest of the Texinfo file onto the one page and does not start
-to generate error messages until it has processed considerable text.
-It is a good rule of thumb to look for a missing `@end group' if you
-get incomprehensible error messages in TeX.
-
-\1f
-File: texinfo.info, Node: need, Prev: group, Up: Breaks
-
-`@need MILS': Prevent Page Breaks
-=================================
-
- A line containing only `@need N' starts a new page in a printed
-manual if fewer than N mils (thousandths of an inch) remain on the
-current page. Do not use braces around the argument N. The `@need'
-command has no effect on Info files since they are not paginated.
-
- This paragraph is preceded by an `@need' command that tells TeX to
-start a new page if fewer than 800 mils (eight-tenths inch) remain on
-the page. It looks like this:
-
- @need 800
- This paragraph is preceded by ...
-
- The `@need' command is useful for preventing orphans (single lines at
-the bottoms of printed pages).
-
-\1f
-File: texinfo.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top
-
-Definition Commands
-*******************
-
- The `@deffn' command and the other "definition commands" enable you
-to describe functions, variables, macros, commands, user options,
-special forms and other such artifacts in a uniform format.
-
- In the Info file, a definition causes the entity
-category--`Function', `Variable', or whatever--to appear at the
-beginning of the first line of the definition, followed by the entity's
-name and arguments. In the printed manual, the command causes TeX to
-print the entity's name and its arguments on the left margin and print
-the category next to the right margin. In both output formats, the
-body of the definition is indented. Also, the name of the entity is
-entered into the appropriate index: `@deffn' enters the name into the
-index of functions, `@defvr' enters it into the index of variables, and
-so on.
-
- A manual need not and should not contain more than one definition for
-a given name. An appendix containing a summary should use `@table'
-rather than the definition commands.
-
-* Menu:
-
-* Def Cmd Template:: How to structure a description using a
- definition command.
-* Optional Arguments:: How to handle optional and repeated arguments.
-* deffnx:: How to group two or more `first' lines.
-* Def Cmds in Detail:: All the definition commands.
-* Def Cmd Conventions:: Conventions for writing definitions.
-* Sample Function Definition::
-
-\1f
-File: texinfo.info, Node: Def Cmd Template, Next: Optional Arguments, Prev: Definition Commands, Up: Definition Commands
-
-The Template for a Definition
-=============================
-
- The `@deffn' command is used for definitions of entities that
-resemble functions. To write a definition using the `@deffn' command,
-write the `@deffn' command at the beginning of a line and follow it on
-the same line by the category of the entity, the name of the entity
-itself, and its arguments (if any). Then write the body of the
-definition on succeeding lines. (You may embed examples in the body.)
-Finally, end the definition with an `@end deffn' command written on a
-line of its own. (The other definition commands follow the same
-format.)
-
- The template for a definition looks like this:
-
- @deffn CATEGORY NAME ARGUMENTS...
- BODY-OF-DEFINITION
- @end deffn
-
-For example,
-
- @deffn Command forward-word count
- This command moves point forward @var{count} words
- (or backward if @var{count} is negative). ...
- @end deffn
-
-produces
-
- - Command: forward-word COUNT
- This function moves point forward COUNT words (or backward if
- COUNT is negative). ...
-
- Capitalize the category name like a title. If the name of the
-category contains spaces, as in the phrase `Interactive Command', write
-braces around it. For example:
-
- @deffn {Interactive Command} isearch-forward
- ...
- @end deffn
-
-Otherwise, the second word will be mistaken for the name of the entity.
-
- Some of the definition commands are more general than others. The
-`@deffn' command, for example, is the general definition command for
-functions and the like--for entities that may take arguments. When you
-use this command, you specify the category to which the entity belongs.
-The `@deffn' command possesses three predefined, specialized
-variations, `@defun', `@defmac', and `@defspec', that specify the
-category for you: "Function", "Macro", and "Special Form" respectively.
-(In Lisp, a special form is an entity much like a function.) The
-`@defvr' command also is accompanied by several predefined, specialized
-variations for describing particular kinds of variables.
-
- The template for a specialized definition, such as `@defun', is
-similar to the template for a generalized definition, except that you
-do not need to specify the category:
-
- @defun NAME ARGUMENTS...
- BODY-OF-DEFINITION
- @end defun
-
-Thus,
-
- @defun buffer-end flag
- This function returns @code{(point-min)} if @var{flag}
- is less than 1, @code{(point-max)} otherwise.
- ...
- @end defun
-
-produces
-
- - Function: buffer-end FLAG
- This function returns `(point-min)' if FLAG is less than 1,
- `(point-max)' otherwise. ...
-
-*Note Sample Function Definition: Sample Function Definition, for a
-more detailed example of a function definition, including the use of
-`@example' inside the definition.
-
- The other specialized commands work like `@defun'.
-
-\1f
-File: texinfo.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Template, Up: Definition Commands
-
-Optional and Repeated Arguments
-===============================
-
- Some entities take optional or repeated arguments, which may be
-specified by a distinctive glyph that uses square brackets and
-ellipses. For example, a special form often breaks its argument list
-into separate arguments in more complicated ways than a straightforward
-function.
-
- An argument enclosed within square brackets is optional. Thus,
-[OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument
-followed by an ellipsis is optional and may be repeated more than once.
-Thus, REPEATED-ARGS... stands for zero or more arguments. Parentheses
-are used when several arguments are grouped into additional levels of
-list structure in Lisp.
-
- Here is the `@defspec' line of an example of an imaginary special
-form:
-
- - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
-
-In this example, the arguments FROM and TO are optional, but must both
-be present or both absent. If they are present, INC may optionally be
-specified as well. These arguments are grouped with the argument VAR
-into a list, to distinguish them from BODY, which includes all
-remaining elements of the form.
-
- In a Texinfo source file, this `@defspec' line is written like this
-(except it would not be split over two lines, as it is in this example).
-
- @defspec foobar (@var{var} [@var{from} @var{to}
- [@var{inc}]]) @var{body}@dots{}
-
-The function is listed in the Command and Variable Index under `foobar'.
-
-\1f
-File: texinfo.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands
-
-Two or More `First' Lines
-=========================
-
- To create two or more `first' or header lines for a definition, follow
-the first `@deffn' line by a line beginning with `@deffnx'. The
-`@deffnx' command works exactly like `@deffn' except that it does not
-generate extra vertical white space between it and the preceding line.
-
- For example,
-
- @deffn {Interactive Command} isearch-forward
- @deffnx {Interactive Command} isearch-backward
- These two search commands are similar except ...
- @end deffn
-
-produces
-
- - Interactive Command: isearch-forward
- - Interactive Command: isearch-backward
- These two search commands are similar except ...
-
- Each of the other definition commands has an `x' form: `@defunx',
-`@defvrx', `@deftypefunx', etc.
-
- The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
-
-\1f
-File: texinfo.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands
-
-The Definition Commands
-=======================
-
- Texinfo provides more than a dozen definition commands, all of which
-are described in this section.
-
- The definition commands automatically enter the name of the entity in
-the appropriate index: for example, `@deffn', `@defun', and `@defmac'
-enter function names in the index of functions; `@defvr' and `@defvar'
-enter variable names in the index of variables.
-
- Although the examples that follow mostly illustrate Lisp, the commands
-can be used for other programming languages.
-
-* Menu:
-
-* Functions Commands:: Commands for functions and similar entities.
-* Variables Commands:: Commands for variables and similar entities.
-* Typed Functions:: Commands for functions in typed languages.
-* Typed Variables:: Commands for variables in typed languages.
-* Abstract Objects:: Commands for object-oriented programming.
-* Data Types:: The definition command for data types.
-
-\1f
-File: texinfo.info, Node: Functions Commands, Next: Variables Commands, Prev: Def Cmds in Detail, Up: Def Cmds in Detail
-
-Functions and Similar Entities
-------------------------------
-
- This section describes the commands for describing functions and
-similar entities:
-
-`@deffn CATEGORY NAME ARGUMENTS...'
- The `@deffn' command is the general definition command for
- functions, interactive commands, and similar entities that may take
- arguments. You must choose a term to describe the category of
- entity being defined; for example, "Function" could be used if the
- entity is a function. The `@deffn' command is written at the
- beginning of a line and is followed on the same line by the
- category of entity being described, the name of this particular
- entity, and its arguments, if any. Terminate the definition with
- `@end deffn' on a line of its own.
-
- For example, here is a definition:
-
- @deffn Command forward-char nchars
- Move point forward @var{nchars} characters.
- @end deffn
-
- This shows a rather terse definition for a "command" named
- `forward-char' with one argument, NCHARS.
-
- `@deffn' prints argument names such as NCHARS in italics or upper
- case, as if `@var' had been used, because we think of these names
- as metasyntactic variables--they stand for the actual argument
- values. Within the text of the description, write an argument name
- explicitly with `@var' to refer to the value of the argument. In
- the example above, we used `@var{nchars}' in this way.
-
- The template for `@deffn' is:
-
- @deffn CATEGORY NAME ARGUMENTS...
- BODY-OF-DEFINITION
- @end deffn
-
-`@defun NAME ARGUMENTS...'
- The `@defun' command is the definition command for functions.
- `@defun' is equivalent to `@deffn Function ...'.
-
- For example,
-
- @defun set symbol new-value
- Change the value of the symbol @var{symbol}
- to @var{new-value}.
- @end defun
-
- shows a rather terse definition for a function `set' whose
- arguments are SYMBOL and NEW-VALUE. The argument names on the
- `@defun' line automatically appear in italics or upper case as if
- they were enclosed in `@var'. Terminate the definition with `@end
- defun' on a line of its own.
-
- The template is:
-
- @defun FUNCTION-NAME ARGUMENTS...
- BODY-OF-DEFINITION
- @end defun
-
- `@defun' creates an entry in the index of functions.
-
-`@defmac NAME ARGUMENTS...'
- The `@defmac' command is the definition command for macros.
- `@defmac' is equivalent to `@deffn Macro ...' and works like
- `@defun'.
-
-`@defspec NAME ARGUMENTS...'
- The `@defspec' command is the definition command for special
- forms. (In Lisp, a special form is an entity much like a function,
- *note Special Forms: (lispref)Special Forms..) `@defspec' is
- equivalent to `@deffn {Special Form} ...' and works like `@defun'.
-
-\1f
-File: texinfo.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail
-
-Variables and Similar Entities
-------------------------------
-
- Here are the commands for defining variables and similar entities:
-
-`@defvr CATEGORY NAME'
- The `@defvr' command is a general definition command for something
- like a variable--an entity that records a value. You must choose
- a term to describe the category of entity being defined; for
- example, "Variable" could be used if the entity is a variable.
- Write the `@defvr' command at the beginning of a line and followed
- it on the same line by the category of the entity and the name of
- the entity.
-
- Capitalize the category name like a title. If the name of the
- category contains spaces, as in the name "User Option", enclose it
- in braces. Otherwise, the second word will be mistaken for the
- name of the entity. For example,
-
- @defvr {User Option} fill-column
- This buffer-local variable specifies
- the maximum width of filled lines.
- ...
- @end defvr
-
- Terminate the definition with `@end defvr' on a line of its own.
-
- The template is:
-
- @defvr CATEGORY NAME
- BODY-OF-DEFINITION
- @end defvr
-
- `@defvr' creates an entry in the index of variables for NAME.
-
-`@defvar NAME'
- The `@defvar' command is the definition command for variables.
- `@defvar' is equivalent to `@defvr Variable ...'.
-
- For example:
-
- @defvar kill-ring
- ...
- @end defvar
-
- The template is:
-
- @defvar NAME
- BODY-OF-DEFINITION
- @end defvar
-
- `@defvar' creates an entry in the index of variables for NAME.
-
-`@defopt NAME'
- The `@defopt' command is the definition command for "user
- options", i.e., variables intended for users to change according to
- taste; Emacs has many such (*note Variables: (xemacs)Variables.).
- `@defopt' is equivalent to `@defvr {User Option} ...' and works
- like `@defvar'.
-
-\1f
-File: texinfo.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail
-
-Functions in Typed Languages
-----------------------------
-
- The `@deftypefn' command and its variations are for describing
-functions in languages in which you must declare types of variables and
-functions, such as C and C++.
-
-`@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
- The `@deftypefn' command is the general definition command for
- functions and similar entities that may take arguments and that are
- typed. The `@deftypefn' command is written at the beginning of a
- line and is followed on the same line by the category of entity
- being described, the type of the returned value, the name of this
- particular entity, and its arguments, if any.
-
- For example,
-
- @deftypefn {Library Function} int foobar
- (int @var{foo}, float @var{bar})
- ...
- @end deftypefn
-
- (where the text before the "...", shown above as two lines, would
- actually be a single line in a real Texinfo file) produces the
- following in Info:
-
- -- Library Function: int foobar (int FOO, float BAR)
- ...
-
- This means that `foobar' is a "library function" that returns an
- `int', and its arguments are FOO (an `int') and BAR (a `float').
-
- The argument names that you write in `@deftypefn' are not subject
- to an implicit `@var'--since the actual names of the arguments in
- `@deftypefn' are typically scattered among data type names and
- keywords, Texinfo cannot find them without help. Instead, you
- must write `@var' explicitly around the argument names. In the
- example above, the argument names are `foo' and `bar'.
-
- The template for `@deftypefn' is:
-
- @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
- BODY-OF-DESCRIPTION
- @end deftypefn
-
- Note that if the CATEGORY or DATA TYPE is more than one word then
- it must be enclosed in braces to make it a single argument.
-
- If you are describing a procedure in a language that has packages,
- such as Ada, you might consider using `@deftypefn' in a manner
- somewhat contrary to the convention described in the preceding
- paragraphs.
-
- For example:
-
- @deftypefn stacks private push
- (@var{s}:in out stack;
- @var{n}:in integer)
- ...
- @end deftypefn
-
- (The `@deftypefn' arguments are shown split into three lines, but
- would be a single line in a real Texinfo file.)
-
- In this instance, the procedure is classified as belonging to the
- package `stacks' rather than classified as a `procedure' and its
- data type is described as `private'. (The name of the procedure
- is `push', and its arguments are S and N.)
-
- `@deftypefn' creates an entry in the index of functions for NAME.
-
-`@deftypefun DATA-TYPE NAME ARGUMENTS...'
- The `@deftypefun' command is the specialized definition command
- for functions in typed languages. The command is equivalent to
- `@deftypefn Function ...'.
-
- Thus,
-
- @deftypefun int foobar (int @var{foo}, float @var{bar})
- ...
- @end deftypefun
-
- produces the following in Info:
-
- -- Function: int foobar (int FOO, float BAR)
- ...
-
- The template is:
-
- @deftypefun TYPE NAME ARGUMENTS...
- BODY-OF-DESCRIPTION
- @end deftypefun
-
- `@deftypefun' creates an entry in the index of functions for NAME.
-
-\1f
-File: texinfo.info, Node: Typed Variables, Next: Abstract Objects, Prev: Typed Functions, Up: Def Cmds in Detail
-
-Variables in Typed Languages
-----------------------------
-
- Variables in typed languages are handled in a manner similar to
-functions in typed languages. *Note Typed Functions::. The general
-definition command `@deftypevr' corresponds to `@deftypefn' and the
-specialized definition command `@deftypevar' corresponds to
-`@deftypefun'.
-
-`@deftypevr CATEGORY DATA-TYPE NAME'
- The `@deftypevr' command is the general definition command for
- something like a variable in a typed language--an entity that
- records a value. You must choose a term to describe the category
- of the entity being defined; for example, "Variable" could be used
- if the entity is a variable.
-
- The `@deftypevr' command is written at the beginning of a line and
- is followed on the same line by the category of the entity being
- described, the data type, and the name of this particular entity.
-
- For example:
-
- @deftypevr {Global Flag} int enable
- ...
- @end deftypevr
-
- produces the following in Info:
-
- -- Global Flag: int enable
- ...
-
- The template is:
-
- @deftypevr CATEGORY DATA-TYPE NAME
- BODY-OF-DESCRIPTION
- @end deftypevr
-
- `@deftypevr' creates an entry in the index of variables for NAME.
-
-`@deftypevar DATA-TYPE NAME'
- The `@deftypevar' command is the specialized definition command
- for variables in typed languages. `@deftypevar' is equivalent to
- `@deftypevr Variable ...'.
-
- For example:
-
- @deftypevar int fubar
- ...
- @end deftypevar
-
- produces the following in Info:
-
- -- Variable: int fubar
- ...
-
- The template is:
-
- @deftypevar DATA-TYPE NAME
- BODY-OF-DESCRIPTION
- @end deftypevar
-
- `@deftypevar' creates an entry in the index of variables for NAME.
-
-\1f
-File: texinfo.info, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail
-
-Object-Oriented Programming
----------------------------
-
- Here are the commands for formatting descriptions about abstract
-objects, such as are used in object-oriented programming. A class is a
-defined type of abstract object. An instance of a class is a
-particular object that has the type of the class. An instance variable
-is a variable that belongs to the class but for which each instance has
-its own value.
-
- In a definition, if the name of a class is truly a name defined in the
-programming system for a class, then you should write an `@code' around
-it. Otherwise, it is printed in the usual text font.
-
-`@defcv CATEGORY CLASS NAME'
- The `@defcv' command is the general definition command for
- variables associated with classes in object-oriented programming.
- The `@defcv' command is followed by three arguments: the category
- of thing being defined, the class to which it belongs, and its
- name. Thus,
-
- @defcv {Class Option} Window border-pattern
- ...
- @end defcv
-
- illustrates how you would write the first line of a definition of
- the `border-pattern' class option of the class `Window'.
-
- The template is
-
- @defcv CATEGORY CLASS NAME
- ...
- @end defcv
-
- `@defcv' creates an entry in the index of variables.
-
-`@defivar CLASS NAME'
- The `@defivar' command is the definition command for instance
- variables in object-oriented programming. `@defivar' is
- equivalent to `@defcv {Instance Variable} ...'
-
- The template is:
-
- @defivar CLASS INSTANCE-VARIABLE-NAME
- BODY-OF-DEFINITION
- @end defivar
-
- `@defivar' creates an entry in the index of variables.
-
-`@defop CATEGORY CLASS NAME ARGUMENTS...'
- The `@defop' command is the general definition command for
- entities that may resemble methods in object-oriented programming.
- These entities take arguments, as functions do, but are associated
- with particular classes of objects.
-
- For example, some systems have constructs called "wrappers" that
- are associated with classes as methods are, but that act more like
- macros than like functions. You could use `@defop Wrapper' to
- describe one of these.
-
- Sometimes it is useful to distinguish methods and "operations".
- You can think of an operation as the specification for a method.
- Thus, a window system might specify that all window classes have a
- method named `expose'; we would say that this window system
- defines an `expose' operation on windows in general. Typically,
- the operation has a name and also specifies the pattern of
- arguments; all methods that implement the operation must accept
- the same arguments, since applications that use the operation do
- so without knowing which method will implement it.
-
- Often it makes more sense to document operations than methods. For
- example, window application developers need to know about the
- `expose' operation, but need not be concerned with whether a given
- class of windows has its own method to implement this operation.
- To describe this operation, you would write:
-
- @defop Operation windows expose
-
- The `@defop' command is written at the beginning of a line and is
- followed on the same line by the overall name of the category of
- operation, the name of the class of the operation, the name of the
- operation, and its arguments, if any.
-
- The template is:
-
- @defop CATEGORY CLASS NAME ARGUMENTS...
- BODY-OF-DEFINITION
- @end defop
-
- `@defop' creates an entry, such as ``expose' on `windows'', in the
- index of functions.
-
-`@defmethod CLASS NAME ARGUMENTS...'
- The `@defmethod' command is the definition command for methods in
- object-oriented programming. A method is a kind of function that
- implements an operation for a particular class of objects and its
- subclasses. In the Lisp Machine, methods actually were functions,
- but they were usually defined with `defmethod'.
-
- `@defmethod' is equivalent to `@defop Method ...'. The command is
- written at the beginning of a line and is followed by the name of
- the class of the method, the name of the method, and its
- arguments, if any.
-
- For example,
-
- @defmethod `bar-class' bar-method argument
- ...
- @end defmethod
-
- illustrates the definition for a method called `bar-method' of the
- class `bar-class'. The method takes an argument.
-
- The template is:
-
- @defmethod CLASS METHOD-NAME ARGUMENTS...
- BODY-OF-DEFINITION
- @end defmethod
-
- `@defmethod' creates an entry, such as ``bar-method' on
- `bar-class'', in the index of functions.
-
-`@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
- The `@deftypemethod' command is the definition command for methods
- in object-oriented typed languages, such as C++ and Java. It is
- similar to the `@defmethod' command with the addition of the
- DATA-TYPE parameter to specify the return type of the method.
-
-\1f
-File: texinfo.info, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail
-
-Data Types
-----------
-
- Here is the command for data types:
-
-`@deftp CATEGORY NAME ATTRIBUTES...'
- The `@deftp' command is the generic definition command for data
- types. The command is written at the beginning of a line and is
- followed on the same line by the category, by the name of the type
- (which is a word like `int' or `float'), and then by names of
- attributes of objects of that type. Thus, you could use this
- command for describing `int' or `float', in which case you could
- use `data type' as the category. (A data type is a category of
- certain objects for purposes of deciding which operations can be
- performed on them.)
-
- In Lisp, for example, "pair" names a particular data type, and an
- object of that type has two slots called the CAR and the CDR.
- Here is how you would write the first line of a definition of
- `pair'.
-
- @deftp {Data type} pair car cdr
- ...
- @end deftp
-
- The template is:
-
- @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
- BODY-OF-DEFINITION
- @end deftp
-
- `@deftp' creates an entry in the index of data types.
-
-\1f
-File: texinfo.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands
-
-Conventions for Writing Definitions
-===================================
-
- When you write a definition using `@deffn', `@defun', or one of the
-other definition commands, please take care to use arguments that
-indicate the meaning, as with the COUNT argument to the `forward-word'
-function. Also, if the name of an argument contains the name of a
-type, such as INTEGER, take care that the argument actually is of that
-type.
-
-\1f
-File: texinfo.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands
-
-A Sample Function Definition
-============================
-
- A function definition uses the `@defun' and `@end defun' commands.
-The name of the function follows immediately after the `@defun' command
-and it is followed, on the same line, by the parameter list.
-
- Here is a definition from *Note Calling Functions: (lispref)Calling
-Functions.
-
- - Function: apply FUNCTION &rest ARGUMENTS
- `apply' calls FUNCTION with ARGUMENTS, just like `funcall'
- but with one difference: the last of ARGUMENTS is a list of
- arguments to give to FUNCTION, rather than a single argument.
- We also say that this list is "appended" to the other
- arguments.
-
- `apply' returns the result of calling FUNCTION. As with
- `funcall', FUNCTION must either be a Lisp function or a
- primitive function; special forms and macros do not make
- sense in `apply'.
-
- (setq f 'list)
- => list
- (apply f 'x 'y 'z)
- error--> Wrong type argument: listp, z
- (apply '+ 1 2 '(3 4))
- => 10
- (apply '+ '(1 2 3 4))
- => 10
-
- (apply 'append '((a b c) nil (x y z) nil))
- => (a b c x y z)
-
- An interesting example of using `apply' is found in the
- description of `mapcar'.
-
- In the Texinfo source file, this example looks like this:
-
- @defun apply function &rest arguments
-
- @code{apply} calls @var{function} with
- @var{arguments}, just like @code{funcall} but with one
- difference: the last of @var{arguments} is a list of
- arguments to give to @var{function}, rather than a single
- argument. We also say that this list is @dfn{appended}
- to the other arguments.
-
- @code{apply} returns the result of calling
- @var{function}. As with @code{funcall},
- @var{function} must either be a Lisp function or a
- primitive function; special forms and macros do not make
- sense in @code{apply}.
-
- @example
- (setq f 'list)
- @result{} list
- (apply f 'x 'y 'z)
- @error{} Wrong type argument: listp, z
- (apply '+ 1 2 '(3 4))
- @result{} 10
- (apply '+ '(1 2 3 4))
- @result{} 10
-
- (apply 'append '((a b c) nil (x y z) nil))
- @result{} (a b c x y z)
- @end example
-
- An interesting example of using @code{apply} is found
- in the description of @code{mapcar}.@refill
- @end defun
-
-In this manual, this function is listed in the Command and Variable
-Index under `apply'.
-
- Ordinary variables and user options are described using a format like
-that for functions except that variables do not take arguments.
-
-\1f
-File: texinfo.info, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top
-
-Footnotes
-*********
-
- A "footnote" is for a reference that documents or elucidates the
-primary text.(1) (*note Footnotes-Footnotes::)
-
-* Menu:
-
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
-
-\1f
-File: texinfo.info, Node: Footnotes-Footnotes, Up: Footnotes
-
- (1) A footnote should complement or expand upon the primary text, but
-a reader should not need to read a footnote to understand the primary
-text. For a thorough discussion of footnotes, see `The Chicago Manual
-of Style', which is published by the University of Chicago Press.
-
-\1f
-File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Prev: Footnotes, Up: Footnotes
-
-Footnote Commands
-=================
-
- In Texinfo, footnotes are created with the `@footnote' command. This
-command is followed immediately by a left brace, then by the text of
-the footnote, and then by a terminating right brace. Footnotes may be
-of any length (they will be broken across pages if necessary), but are
-usually short. The template is:
-
- ordinary text@footnote{TEXT OF FOOTNOTE}
-
- As shown here, the `@footnote' command should come right after the
-text being footnoted, with no intervening space; otherwise, the
-formatters the footnote mark might end up starting up a line.
-
- For example, this clause is followed by a sample footnote(1) (*note
-Footnote Commands-Footnotes::); in the Texinfo source, it looks like
-this:
-
- ...a sample footnote@footnote{Here is the sample
- footnote.}; in the Texinfo source...
-
- *Warning:* Don't use footnotes in the argument of the `@item' command
-for a `@table' table. This doesn't work, and because of limitations of
-TeX, there is no way to fix it. You must put the footnote into the
-body text of the table.
-
- In a printed manual or book, the reference mark for a footnote is a
-small, superscripted number; the text of the footnote appears at the
-bottom of the page, below a horizontal line.
-
- In Info, the reference mark for a footnote is a pair of parentheses
-with the footnote number between them, like this: `(1)'.
-
-\1f
-File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands
-
- (1) Here is the sample footnote.
-
-\1f
-File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes
-
-Footnote Styles
-===============
-
- Info has two footnote styles, which determine where the text of the
-footnote is located:
-
- * In the `End' node style, all the footnotes for a single node are
- placed at the end of that node. The footnotes are separated from
- the rest of the node by a line of dashes with the word `Footnotes'
- within it. Each footnote begins with an `(N)' reference mark.
-
- Here is an example of a single footnote in the end of node style:
-
- --------- Footnotes ---------
-
- (1) Here is a sample footnote.
-
- * In the `Separate' node style, all the footnotes for a single node
- are placed in an automatically constructed node of their own. In
- this style, a "footnote reference" follows each `(N)' reference
- mark in the body of the node. The footnote reference is actually
- a cross reference which you use to reach the footnote node.
-
- The name of the node containing the footnotes is constructed by
- appending `-Footnotes' to the name of the node that contains the
- footnotes. (Consequently, the footnotes' node for the `Footnotes'
- node is `Footnotes-Footnotes'!) The footnotes' node has an `Up'
- node pointer that leads back to its parent node.
-
- Here is how the first footnote in this manual looks after being
- formatted for Info in the separate node style:
-
- File: texinfo.info Node: Overview-Footnotes, Up: Overview
-
- (1) Note that the first syllable of "Texinfo" is
- pronounced like "speck", not "hex". ...
-
- A Texinfo file may be formatted into an Info file with either footnote
-style.
-
- Use the `@footnotestyle' command to specify an Info file's footnote
-style. Write this command at the beginning of a line followed by an
-argument, either `end' for the end node style or `separate' for the
-separate node style.
-
- For example,
-
- @footnotestyle end
-
-or
- @footnotestyle separate
-
- Write an `@footnotestyle' command before or shortly after the
-end-of-header line at the beginning of a Texinfo file. (If you include
-the `@footnotestyle' command between the start-of-header and
-end-of-header lines, the region formatting commands will format
-footnotes as specified.)
-
- If you do not specify a footnote style, the formatting commands use
-their default style. Currently, `texinfo-format-buffer' and
-`texinfo-format-region' use the `separate' style and `makeinfo' uses
-the `end' style.
-
- This chapter contains two footnotes.
-
-\1f
-File: texinfo.info, Node: Conditionals, Next: Macros, Prev: Footnotes, Up: Top
-
-Conditionally Visible Text
-**************************
-
- Sometimes it is good to use different text for a printed manual and
-its corresponding Info file. In this case, you can use the
-"conditional commands" to specify which text is for the printed manual
-and which is for the Info file.
-
-* Menu:
-
-* Conditional Commands:: Specifying text for HTML, Info, or TeX.
-* Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
-* Raw Formatter Commands:: Using raw TeX or HTML commands.
-* set clear value:: Designating which text to format (for
- all output formats); and how to set a
- flag to a string that you can insert.
-
-\1f
-File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Prev: Conditionals, Up: Conditionals
-
-Conditional Commands
-====================
-
- `@ifinfo' begins segments of text that should be ignored by TeX when
-it typesets the printed manual. The segment of text appears only in
-the Info file. The `@ifinfo' command should appear on a line by
-itself; end the Info-only text with a line containing `@end ifinfo' by
-itself. At the beginning of a Texinfo file, the Info permissions are
-contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
-Info Summary and Permissions::.)
-
- The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
-and `@end ifinfo' commands, except that they specify text that will
-appear in the printed manual but not in the Info file. Likewise for
-`@ifhtml' and `@end ifhtml', which specify text to appear only in HTML
-output.
-
- For example,
-
- @iftex
- This text will appear only in the printed manual.
- @end iftex
- @ifinfo
- However, this text will appear only in Info.
- @end ifinfo
-
-The preceding example produces the following line: However, this text
-will appear only in Info.
-
-Note how you only see one of the two lines, depending on whether you
-are reading the Info version or the printed version of this manual.
-
- The `@titlepage' command is a special variant of `@iftex' that is
-used for making the title and copyright pages of the printed manual.
-(*Note `@titlepage': titlepage.)
-
-\1f
-File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals
-
-Conditional Not Commands
-========================
-
- You can specify text to be included in any output format *other* than
-some given one with the `@ifnot...' commands:
- @ifnothtml ... @end ifnothtml
- @ifnotinfo ... @end ifnotinfo
- @ifnottex ... @end ifnottex
-
-(The `@ifnot...' command and the `@end' command must actually appear on
-lines by themselves.)
-
- If the output file is not being made for the given format, the region
-is included. Otherwise, it is ignored.
-
- The regions delimited by these commands are ordinary Texinfo source as
-with `@iftex', not raw formatter source as with `@tex'.
-
-\1f
-File: texinfo.info, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals
-
-Raw Formatter Commands
-======================
-
- Inside a region delineated by `@iftex' and `@end iftex', you can
-embed some raw TeX commands. Info will ignore these commands since
-they are only in that part of the file which is seen by TeX. You can
-write the TeX commands as you would write them in a normal TeX file,
-except that you must replace the `\' used by TeX with an `@'. For
-example, in the `@titlepage' section of a Texinfo file, you can use the
-TeX command `@vskip' to format the copyright page. (The `@titlepage'
-command causes Info to ignore the region automatically, as it does with
-the `@iftex' command.)
-
- However, many features of plain TeX will not work, as they are
-overridden by Texinfo features.
-
- You can enter plain TeX completely, and use `\' in the TeX commands,
-by delineating a region with the `@tex' and `@end tex' commands. (The
-`@tex' command also causes Info to ignore the region, like the `@iftex'
-command.) The sole exception is that `@' chracter still introduces a
-command, so that `@end tex' can be recognized properly.
-
- For example, here is a mathematical expression written in plain TeX:
-
- @tex
- $$ \chi^2 = \sum_{i=1}^N
- \left (y_i - (a + b x_i)
- \over \sigma_i\right)^2 $$
- @end tex
-
-The output of this example will appear only in a printed manual. If
-you are reading this in Info, you will not see the equation that appears
-in the printed manual.
-
- Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
-region to be included in HTML output only, and `@html ... @end ifhtml'
-for a region of raw HTML (again, except that `@' is still the escape
-character, so the `@end' command can be recognized.)
-
-\1f
-File: texinfo.info, Node: set clear value, Prev: Raw Formatter Commands, Up: Conditionals
-
-`@set', `@clear', and `@value'
-==============================
-
- You can direct the Texinfo formatting commands to format or ignore
-parts of a Texinfo file with the `@set', `@clear', `@ifset', and
-`@ifclear' commands.
-
- In addition, you can use the `@set FLAG' command to set the value of
-FLAG to a string of characters; and use `@value{FLAG}' to insert that
-string. You can use `@set', for example, to set a date and use
-`@value' to insert the date in several places in the Texinfo file.
-
-* Menu:
-
-* ifset ifclear:: Format a region if a flag is set.
-* value:: Replace a flag with a string.
-* value Example:: An easy way to update edition information.
-
-\1f
-File: texinfo.info, Node: ifset ifclear, Next: value, Prev: set clear value, Up: set clear value
-
-`@ifset' and `@ifclear'
------------------------
-
- When a FLAG is set, the Texinfo formatting commands format text
-between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
-When the FLAG is cleared, the Texinfo formatting commands do *not*
-format the text.
-
- Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
-can be any single word. The format for the command looks like this:
-
- @set FLAG
-
- Write the conditionally formatted text between `@ifset FLAG' and
-`@end ifset' commands, like this:
-
- @ifset FLAG
- CONDITIONAL-TEXT
- @end ifset
-
- For example, you can create one document that has two variants, such
-as a manual for a `large' and `small' model:
-
- You can use this machine to dig up shrubs
- without hurting them.
-
- @set large
-
- @ifset large
- It can also dig up fully grown trees.
- @end ifset
-
- Remember to replant promptly ...
-
-In the example, the formatting commands will format the text between
-`@ifset large' and `@end ifset' because the `large' flag is set.
-
- Use the `@clear FLAG' command to turn off, or "clear", a flag.
-Clearing a flag is the opposite of setting a flag. The command looks
-like this:
-
- @clear FLAG
-
-Write the command on a line of its own.
-
- When FLAG is cleared, the Texinfo formatting commands do *not* format
-the text between `@ifset FLAG' and `@end ifset'; that text is ignored
-and does not appear in either printed or Info output.
-
- For example, if you clear the flag of the preceding example by writing
-an `@clear large' command after the `@set large' command (but before
-the conditional text), then the Texinfo formatting commands ignore the
-text between the `@ifset large' and `@end ifset' commands. In the
-formatted output, that text does not appear; in both printed and Info
-output, you see only the lines that say, "You can use this machine to
-dig up shrubs without hurting them. Remember to replant promptly ...".
-
- If a flag is cleared with an `@clear FLAG' command, then the
-formatting commands format text between subsequent pairs of `@ifclear'
-and `@end ifclear' commands. But if the flag is set with `@set FLAG',
-then the formatting commands do *not* format text between an `@ifclear'
-and an `@end ifclear' command; rather, they ignore that text. An
-`@ifclear' command looks like this:
-
- @ifclear FLAG
-
- In brief, the commands are:
-
-`@set FLAG'
- Tell the Texinfo formatting commands that FLAG is set.
-
-`@clear FLAG'
- Tell the Texinfo formatting commands that FLAG is cleared.
-
-`@ifset FLAG'
- If FLAG is set, tell the Texinfo formatting commands to format the
- text up to the following `@end ifset' command.
-
- If FLAG is cleared, tell the Texinfo formatting commands to ignore
- text up to the following `@end ifset' command.
-
-`@ifclear FLAG'
- If FLAG is set, tell the Texinfo formatting commands to ignore the
- text up to the following `@end ifclear' command.
-
- If FLAG is cleared, tell the Texinfo formatting commands to format
- the text up to the following `@end ifclear' command.
-
-\1f
-File: texinfo.info, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value
-
-`@value'
---------
-
- You can use the `@set' command to specify a value for a flag, which
-is expanded by the `@value' command. The value is a string a
-characters.
-
- Write the `@set' command like this:
-
- @set foo This is a string.
-
-This sets the value of `foo' to "This is a string."
-
- The Texinfo formatters replace an `@value{FLAG}' command with the
-string to which FLAG is set.
-
- Thus, when `foo' is set as shown above, the Texinfo formatters convert
-
- @value{foo}
-to
- This is a string.
-
- You can write an `@value' command within a paragraph; but you must
-write an `@set' command on a line of its own.
-
- If you write the `@set' command like this:
-
- @set foo
-
-without specifying a string, the value of `foo' is an empty string.
-
- If you clear a previously set flag with an `@clear FLAG' command, a
-subsequent `@value{flag}' command is invalid and the string is replaced
-with an error message that says `{No value for "FLAG"}'.
-
- For example, if you set `foo' as follows:
-
- @set how-much very, very, very
-
-then the formatters transform
-
- It is a @value{how-much} wet day.
-into
- It is a very, very, very wet day.
-
- If you write
-
- @clear how-much
-
-then the formatters transform
-
- It is a @value{how-much} wet day.
-into
- It is a {No value for "how-much"} wet day.
-
-\1f
-File: texinfo.info, Node: value Example, Prev: value, Up: set clear value
-
-`@value' Example
-----------------
-
- You can use the `@value' command to limit the number of places you
-need to change when you record an update to a manual. Here is how it
-is done in `The GNU Make Manual':
-
-Set the flags:
-
- @set EDITION 0.35 Beta
- @set VERSION 3.63 Beta
- @set UPDATED 14 August 1992
- @set UPDATE-MONTH August 1992
-
-Write text for the first `@ifinfo' section, for people reading the
-Texinfo file:
-
- This is Edition @value{EDITION},
- last updated @value{UPDATED},
- of @cite{The GNU Make Manual},
- for @code{make}, Version @value{VERSION}.
-
-Write text for the title page, for people reading the printed manual:
-
- @title GNU Make
- @subtitle A Program for Directing Recompilation
- @subtitle Edition @value{EDITION}, ...
- @subtitle @value{UPDATE-MONTH}
-
-(On a printed cover, a date listing the month and the year looks less
-fussy than a date listing the day as well as the month and year.)
-
-Write text for the Top node, for people reading the Info file:
-
- This is Edition @value{EDITION}
- of the @cite{GNU Make Manual},
- last updated @value{UPDATED}
- for @code{make} Version @value{VERSION}.
-
- After you format the manual, the text in the first `@ifinfo' section
-looks like this:
-
- This is Edition 0.35 Beta, last updated 14 August 1992,
- of `The GNU Make Manual', for `make', Version 3.63 Beta.
-
- When you update the manual, change only the values of the flags; you
-do not need to rewrite the three sections.
-
-\1f
-File: texinfo.info, Node: Macros, Next: Format/Print Hardcopy, Prev: Conditionals, Up: Top
-
-Macros: Defining New Texinfo Commands
-*************************************
-
- A Texinfo "macro" allows you to define a new Texinfo command as any
-sequence of text and/or existing commands (including other macros). The
-macro can have any number of "parameters"--text you supply each time
-you use the macro. (This has nothing to do with the `@defmac' command,
-which is for documenting macros in the subject of the manual; *note Def
-Cmd Template::..)
-
-* Menu:
-
-* Defining Macros:: Both defining and undefining new commands.
-* Invoking Macros:: Using a macro, once you've defined it.
-
-\1f
-File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Prev: Macros, Up: Macros
-
-Defining Macros
-===============
-
- You use the Texinfo `@macro' command to define a macro. For example:
-
- @macro MACRO-NAME{PARAM1, PARAM2, ...}
- TEXT ... \PARAM1\ ...
- @end macro
-
- The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
-when the macro is subsequently used in the document (see the next
-section).
-
- If a macro needs no parameters, you can define it either with an empty
-list (`@macro foo {}') or with no braces at all (`@macro foo').
-
- The definition or "body" of the macro can contain any Texinfo
-commands, including previously-defined macros. (It is not possible to
-have mutually recursive Texinfo macros.) In the body, instances of a
-parameter name surrounded by backslashes, as in `\PARAM1\' in the
-example above, are replaced by the corresponding argument from the
-macro invocation.
-
- You can undefine a macro FOO with `@unmacro FOO'. It is not an error
-to undefine a macro that is already undefined. For example:
-
- @unmacro foo
-
projects / chise / xemacs-chise.git.1 / blobdiff