This is Info file ../info/texinfo.info, produced by Makeinfo-1.63 from
the input file texinfo.texi.

  This file documents Texinfo, a documentation system that uses a single
source file to produce both on-line information and a printed manual.

  Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software
Foundation, Inc.

  This is the second edition of the Texinfo documentation,
and is consistent with version 2 of `texinfo.tex'.

  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.


File: texinfo.info,  Node: syncodeindex,  Next: synindex,  Prev: Combining Indices,  Up: Combining Indices

`@syncodeindex'
---------------

  When you want to combine functions and concepts into one index, you
should index the functions with `@findex' and index the concepts with
`@cindex', and use the `@syncodeindex' command to redirect the function
index entries into the concept index.

  The `@syncodeindex' command takes two arguments; they are the name of
the index to redirect, and the name of the index to redirect it to.
The template looks like this:

     @syncodeindex FROM TO

  For this purpose, the indices are given two-letter names:

`cp'
     concept index

`fn'
     function index

`vr'
     variable index

`ky'
     key index

`pg'
     program index

`tp'
     data type index

  Write an `@syncodeindex' command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  For example, to
merge a function index with a concept index, write the following:

     @syncodeindex fn cp

This will cause all entries designated for the function index to merge
in with the concept index instead.

  To merge both a variables index and a function index into a concept
index, write the following:

     @syncodeindex vr cp
     @syncodeindex fn cp

  The `@syncodeindex' command puts all the entries from the `from'
index (the redirected index) into the `@code' font, overriding whatever
default font is used by the index to which the entries are now
directed.  This way, if you direct function names from a function index
into a concept index, all the function names are printed in the `@code'
font as you would expect.


File: texinfo.info,  Node: synindex,  Prev: syncodeindex,  Up: Combining Indices

`@synindex'
-----------

  The `@synindex' command is nearly the same as the `@syncodeindex'
command, except that it does not put the `from' index  entries into the
`@code' font; rather it puts them in the roman font.  Thus, you use
`@synindex' when you merge a concept index into a function index.

  *Note Printing Indices & Menus::, for information about printing an
index at the end of a book or creating an index menu in an Info file.


File: texinfo.info,  Node: New Indices,  Prev: Combining Indices,  Up: Indices

Defining New Indices
====================

  In addition to the predefined indices, you may use the `@defindex'
and `@defcodeindex' commands to define new indices.  These commands
create new indexing @-commands with which you mark index entries.  The
`@defindex 'command is used like this:

     @defindex NAME

  The name of an index should be a two letter word, such as `au'.  For
example:

     @defindex au

  This defines a new index, called the `au' index.  At the same time,
it creates a new indexing command, `@auindex', that you can use to make
index entries.  Use the new indexing command just as you would use a
predefined indexing command.

  For example, here is a section heading followed by a concept index
entry and two `au' index entries.

     @section Cognitive Semantics
     @cindex kinesthetic image schemas
     @auindex Johnson, Mark
     @auindex Lakoff, George

(Evidently, `au' serves here as an abbreviation for "author".) Texinfo
constructs the new indexing command by concatenating the name of the
index with `index'; thus, defining an `au' index leads to the automatic
creation of an `@auindex' command.

  Use the `@printindex' command to print the index, as you do with the
predefined indices.  For example:

     @node Author Index, Subject Index, , Top
     @unnumbered Author Index
     
     @printindex au

  The `@defcodeindex' is like the `@defindex' command, except that, in
the printed output, it prints entries in an `@code' font instead of a
roman font.  Thus, it parallels the `@findex' command rather than the
`@cindex' command.

  You should define new indices within or right after the end-of-header
line of a Texinfo file, before any `@synindex' or `@syncodeindex'
commands (*note Header::.).


File: texinfo.info,  Node: Insertions,  Next: Glyphs,  Prev: Indices,  Up: Top

Special Insertions
******************

  Texinfo provides several commands for formatting dimensions, for
inserting single characters that have special meaning in Texinfo, such
as braces, and for inserting special graphic symbols that do not
correspond to characters, such as dots and bullets.

* Menu:

* Braces Atsigns Periods::      How to insert braces, `@' and periods.
* dmn::                         How to format a dimension.
* Dots Bullets::                How to insert dots and bullets.
* TeX and copyright::           How to insert the TeX logo
                                  and the copyright symbol.
* minus::                       How to insert a minus sign.
* math::                        How to format a mathematical expression.


File: texinfo.info,  Node: Braces Atsigns Periods,  Next: dmn,  Prev: Insertions,  Up: Insertions

Inserting `@', Braces, and Periods
==================================

  `@' and curly braces are special characters in Texinfo.  To insert
these characters so they appear in text, you must put an `@' in front
of these characters to prevent Texinfo from misinterpreting them.

  Periods are also special.  Depending on whether the period is inside
or at the end of a sentence, less or more space is inserted after a
period in a typeset manual.  Since it is not always possible for
Texinfo to determine when a period ends a sentence and when it is used
in an abbreviation, special commands are needed in some circumstances.
(Usually, Texinfo can guess how to handle periods, so you do not need
to use the special commands; you just enter a period as you would if
you were using a typewriter, which means you put two spaces after the
period, question mark, or exclamation mark that ends a sentence.)

  Do not put braces after any of these commands; they are not necessary.

* Menu:

* Inserting An Atsign::
* Inserting Braces::            How to insert `{' and `}'
* Controlling Spacing::         How to insert the right amount of space
                                  after punctuation within a sentence.


File: texinfo.info,  Node: Inserting An Atsign,  Next: Inserting Braces,  Prev: Braces Atsigns Periods,  Up: Braces Atsigns Periods

Inserting `@' with @@
---------------------

  `@@' stands for a single `@' in either printed or Info output.

  Do not put braces after an `@@' command.


File: texinfo.info,  Node: Inserting Braces,  Next: Controlling Spacing,  Prev: Inserting An Atsign,  Up: Braces Atsigns Periods

Inserting `{' and `}'with @{ and @}
-----------------------------------

  `@{' stands for a single `{' in either printed or Info output.

  `@}' stands for a single `}' in either printed or Info output.

  Do not put braces after either an `@{' or an `@}' command.


File: texinfo.info,  Node: Controlling Spacing,  Prev: Inserting Braces,  Up: Braces Atsigns Periods

Spacing After Colons and Periods
--------------------------------

  Use the `@:' command after a period, question mark, exclamation mark,
or colon that should not be followed by extra space.  For example, use
`@:' after periods that end abbreviations which are not at the ends of
sentences.  `@:' has no effect on the Info file output.

  For example,

     The s.o.p.@: has three parts ...
     The s.o.p. has three parts ...

produces

     The s.o.p. has three parts ...
     The s.o.p. has three parts ...

`@:' has no effect on the Info output.  (`s.o.p' is an acronym for
"Standard Operating Procedure".)

  Use `@.' instead of a period at the end of a sentence that ends with
a single capital letter.  Otherwise, TeX will think the letter is an
abbreviation and will not insert the correct end-of-sentence spacing.
Here is an example:

     Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

produces

     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

  In the Info file output, `@.' is equivalent to a simple `.'.

  The meanings of `@:' and `@.' in Texinfo are designed to work well
with the Emacs sentence motion commands.  This made it necessary for
them to be incompatible with some other formatting systems that use
@-commands.

  Do not put braces after either an `@:' or an `@.' command.


File: texinfo.info,  Node: dmn,  Next: Dots Bullets,  Prev: Braces Atsigns Periods,  Up: Insertions

`@dmn'{DIMENSION}: Format a Dimension
=====================================

  At times, you may want to write `12pt' or `8.5in' with little or no
space between the number and the abbreviation for the dimension.  You
can use the `@dmn' command to do this.  On seeing the command, TeX
inserts just enough space for proper typesetting; the Info formatting
commands insert no space at all, since the Info file does not require
it.

  To use the `@dmn' command, write the number and then follow it
immediately, with no intervening space, by `@dmn', and then by the
dimension within braces.

For example,

     A4 paper is 8.27@dmn{in} wide.

produces

     A4 paper is 8.27in wide.

  Not everyone uses this style.  Instead of writing `8.27@dmn{in}' in
the Texinfo file, you may write `8.27 in.' or `8.27 inches'.  (In these
cases, the formatters may insert a line break between the number and the
dimension.  Also, if you write a period after an abbreviation within a
sentence, you should write `@:' after the period to prevent TeX from
inserting extra whitespace.  *Note Spacing After Colons and Periods:
Controlling Spacing.)


File: texinfo.info,  Node: Dots Bullets,  Next: TeX and copyright,  Prev: dmn,  Up: Insertions

Inserting Ellipsis, Dots, and Bullets
=====================================

  An "ellipsis" (a line of dots) is not typeset as a string of periods,
so a special command is used for ellipsis in Texinfo.  The `@bullet'
command is special, too.  Each of these commands is followed by a pair
of braces, `{}', without any whitespace between the name of the command
and the braces.  (You need to use braces with these commands because
you can use them next to other text; without the braces, the formatters
would be confused.  *Note @-Command Syntax: Command Syntax, for further
information.)

* Menu:

* dots::                        How to insert dots ...
* bullet::                      How to insert a bullet.


File: texinfo.info,  Node: dots,  Next: bullet,  Prev: Dots Bullets,  Up: Dots Bullets

`@dots'{}
---------

  Use the `@dots{}' command to generate an ellipsis, which is three
dots in a row, appropriately spaced, like this: `...'.  Do not simply
write three periods in the input file; that would work for the Info
file output, but would produce the wrong amount of space between the
periods in the printed manual.

  Similarly, the `@enddots{}' command helps you correctly set an
end-of-sentence ellipsis (four dots).


File: texinfo.info,  Node: bullet,  Prev: dots,  Up: Dots Bullets

`@bullet'{}
-----------

  Use the `@bullet{}' command to generate a large round dot, or the
closest possible thing to one.  In Info, an asterisk is used.

  Here is a bullet: *

  When you use `@bullet' in `@itemize', you do not need to type the
braces, because `@itemize' supplies them.  (*Note `@itemize': itemize.)


File: texinfo.info,  Node: TeX and copyright,  Next: minus,  Prev: Dots Bullets,  Up: Insertions

Inserting TeX and the Copyright Symbol
======================================

  The logo `TeX' is typeset in a special fashion and it needs an
@-command.  The copyright symbol, `(C)', is also special.  Each of
these commands is followed by a pair of braces, `{}', without any
whitespace between the name of the command and the braces.

* Menu:

* tex::                         How to insert the TeX logo.
* copyright symbol::            How to use `@copyright'{}.


File: texinfo.info,  Node: tex,  Next: copyright symbol,  Prev: TeX and copyright,  Up: TeX and copyright

`@TeX'{}
--------

  Use the `@TeX{}' command to generate `TeX'.  In a printed manual,
this is a special logo that is different from three ordinary letters.
In Info, it just looks like `TeX'.  The `@TeX{}' command is unique
among Texinfo commands in that the T and the X are in upper case.


File: texinfo.info,  Node: copyright symbol,  Prev: tex,  Up: TeX and copyright

`@copyright'{}
--------------

  Use the `@copyright{}' command to generate `(C)'.  In a printed
manual, this is a `c' inside a circle, and in Info, this is `(C)'.


File: texinfo.info,  Node: minus,  Next: math,  Prev: TeX and copyright,  Up: Insertions

`@minus'{}: Inserting a Minus Sign
==================================

  Use the `@minus{}' command to generate a minus sign.  In a
fixed-width font, this is a single hyphen, but in a proportional font,
the symbol is the customary length for a minus sign--a little longer
than a hyphen.

  You can compare the two forms:

     `-' is a minus sign generated with `@minus{}',
     
     `-' is a hyphen generated with the character `-'.

In the fixed-width font used by Info, `@minus{}' is the same as a
hyphen.

  You should not use `@minus{}' inside `@code' or `@example' because
the width distinction is not made in the fixed-width font they use.

  When you use `@minus' to specify the mark beginning each entry in an
itemized list, you do not need to type the braces (*note `@itemize':
itemize..)


File: texinfo.info,  Node: math,  Prev: minus,  Up: Insertions

`@math': Inserting Mathematical Expressions
===========================================

  You can write a short mathematical expression with the `@math'
command.  Write the mathematical expression between braces, like this:

     @math{(a + b)(a + b) = a^2 + 2ab + b^2}

This produces the following in Info:

     (a + b)(a + b) = a^2 + 2ab + b^2

  The `@math' command has no effect on the Info output.  Currently, it
has limited effect on typeset output.  However, this may change since
TeX itself is designed for mathematical typesetting and does a splendid
job.

  Certainly, for complex mathematical expressions, you could use TeX
directly.  *Note Using Ordinary TeX Commands: Using Ordinary TeX
Commands.  When you use TeX directly, remember to write the
mathematical expression between one or two `$' (dollar-signs) as
appropriate.


File: texinfo.info,  Node: Glyphs,  Next: Breaks,  Prev: Insertions,  Up: Top

Glyphs for Examples
*******************

  In Texinfo, code is often illustrated in examples that are delimited
by `@example' and `@end example', or by `@lisp' and `@end lisp'.  In
such examples, you can indicate the results of evaluation or an
expansion using `=>' or `==>'.  Likewise, there are commands to insert
glyphs to indicate printed output, error messages, equivalence of
expressions, and the location of point.

  The glyph-insertion commands do not need to be used within an
example, but most often they are.  Every  glyph-insertion command is
followed by a pair of left- and right-hand braces.

* Menu:

* Glyphs Summary::
* result::                      How to show the result of expression.
* expansion::                   How to indicate an expansion.
* Print Glyph::                 How to indicate printed output.
* Error Glyph::                 How to indicate an error message.
* Equivalence::                 How to indicate equivalence.
* Point Glyph::                 How to indicate the location of point.


File: texinfo.info,  Node: Glyphs Summary,  Next: result,  Prev: Glyphs,  Up: Glyphs

Glyphs Summary
==============

  Here are the different glyph commands:

=>
     `@result{}' points to the result of an expression.

==>
     `@expansion{}' shows the results of a macro expansion.

-|
     `@print{}' indicates printed output.

error-->
     `@error{}' indicates that the following text is an error message.

==
     `@equiv{}' indicates the exact equivalence of two forms.

-!-
     `@point{}' shows the location of point.


File: texinfo.info,  Node: result,  Next: expansion,  Prev: Glyphs Summary,  Up: Glyphs

=>: Indicating Evaluation
=========================

  Use the `@result{}' command to indicate the result of evaluating an
expression.

  The `@result{}' command is displayed as `=>' in Info and as a double
stemmed arrow in the printed output.

  Thus, the following,

     (cdr '(1 2 3))
          => (2 3)

may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".


File: texinfo.info,  Node: expansion,  Next: Print Glyph,  Prev: result,  Up: Glyphs

==>: Indicating an Expansion
============================

  When an expression is a macro call, it expands into a new expression.
You can indicate the result of the expansion with the `@expansion{}'
command.

  The `@expansion{}' command is displayed as `==>' in Info and as a
long arrow with a flat base in the printed output.

  For example, the following

     @lisp
     (third '(a b c))
          @expansion{} (car (cdr (cdr '(a b c))))
          @result{} c
     @end lisp

produces

     (third '(a b c))
          ==> (car (cdr (cdr '(a b c))))
          => c

which may be read as:

     `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
     result of evaluating the expression is `c'.

Often, as in this case, an example looks better if the `@expansion{}'
and `@result{}' commands are indented five spaces.


File: texinfo.info,  Node: Print Glyph,  Next: Error Glyph,  Prev: expansion,  Up: Glyphs

-|: Indicating Printed Output
=============================

  Sometimes an expression will print output during its execution.  You
can indicate the printed output with the `@print{}' command.

  The `@print{}' command is displayed as `-|' in Info and similarly, as
a horizontal dash butting against a vertical bar, in the printed output.

  In the following example, the printed text is indicated with `-|',
and the value of the expression follows on the last line.

     (progn (print 'foo) (print 'bar))
          -| foo
          -| bar
          => bar

In a Texinfo source file, this example is written as follows:

     @lisp
     (progn (print 'foo) (print 'bar))
          @print{} foo
          @print{} bar
          @result{} bar
     @end lisp


File: texinfo.info,  Node: Error Glyph,  Next: Equivalence,  Prev: Print Glyph,  Up: Glyphs

error-->: Indicating an Error Message
=====================================

  A piece of code may cause an error when you evaluate it.  You can
designate the error message with the `@error{}' command.

  The `@error{}' command is displayed as `error-->' in Info and as the
word `error' in a box in the printed output.

  Thus,

     @lisp
     (+ 23 'x)
     @error{} Wrong type argument: integer-or-marker-p, x
     @end lisp

produces

     (+ 23 'x)
     error--> Wrong type argument: integer-or-marker-p, x

This indicates that the following error message is printed when you
evaluate the expression:

     Wrong type argument: integer-or-marker-p, x

  Note that `error-->' itself is not part of the error message.


File: texinfo.info,  Node: Equivalence,  Next: Point Glyph,  Prev: Error Glyph,  Up: Glyphs

==: Indicating Equivalence
==========================

  Sometimes two expressions produce identical results.  You can
indicate the exact equivalence of two forms with the `@equiv{}' command.

  The `@equiv{}' command is displayed as `==' in Info and as a three
parallel horizontal lines in the printed output.

  Thus,

     @lisp
     (make-sparse-keymap) @equiv{} (list 'keymap)
     @end lisp

produces

     (make-sparse-keymap) == (list 'keymap)

This indicates that evaluating `(make-sparse-keymap)' produces
identical results to evaluating `(list 'keymap)'.


File: texinfo.info,  Node: Point Glyph,  Prev: Equivalence,  Up: Glyphs

Indicating Point in a Buffer
============================

  Sometimes you need to show an example of text in an Emacs buffer.  In
such examples, the convention is to include the entire contents of the
buffer in question between two lines of dashes containing the buffer
name.

  You can use the `@point{}' command to show the location of point in
the text in the buffer.  (The symbol for point, of course, is not part
of the text in the buffer; it indicates the place *between* two
characters where point is located.)

  The `@point{}' command is displayed as `-!-' in Info and as a small
five pointed star in the printed output.

  The following example shows the contents of buffer `foo' before and
after evaluating a Lisp command to insert the word `changed'.

     ---------- Buffer: foo ----------
     This is the -!-contents of foo.
     ---------- Buffer: foo ----------

     (insert "changed ")
          => nil
     ---------- Buffer: foo ----------
     This is the changed -!-contents of foo.
     ---------- Buffer: foo ----------

  In a Texinfo source file, the example is written like this:

     @example
     ---------- Buffer: foo ----------
     This is the @point{}contents of foo.
     ---------- Buffer: foo ----------
     
     (insert "changed ")
          @result{} nil
     ---------- Buffer: foo ----------
     This is the changed @point{}contents of foo.
     ---------- Buffer: foo ----------
     @end example


File: texinfo.info,  Node: Breaks,  Next: Definition Commands,  Prev: Glyphs,  Up: Top

Making and Preventing Breaks
****************************

  Usually, a Texinfo file is processed both by TeX and by one of the
Info formatting commands.  Line, paragraph, or page breaks sometimes
occur in the `wrong' place in one or other form of output.  You must
ensure that text looks right both in the printed manual and in the Info
file.

  For example, in a printed manual, page breaks may occur awkwardly in
the middle of an example; to prevent this, you can hold text together
using a grouping command that keeps the text from being split across
two pages.  Conversely, you may want to force a page break where none
would occur normally.  Fortunately, problems like these do not often
arise.  When they do, use the break, break prevention, or pagination
commands.

* Menu:

* Break Commands::              Cause and prevent splits.
* Line Breaks::                 How to force a single line to use two lines.
* w::                           How to prevent unwanted line breaks.
* sp::                          How to insert blank lines.
* page::                        How to force the start of a new page.
* group::                       How to prevent unwanted page breaks.
* need::                        Another way to prevent unwanted page breaks.


File: texinfo.info,  Node: Break Commands,  Next: Line Breaks,  Prev: Breaks,  Up: Breaks

The Break Commands
==================

  The break commands create line and paragraph breaks:

`@*'
     Force a line break.

`@sp N'
     Skip N blank lines.

  The line-break-prevention command holds text together all on one line:

`@w{TEXT}'
     Prevent TEXT from being split and hyphenated across two lines.

  The pagination commands apply only to printed output, since Info
files do not have pages.

`@page'
     Start a new page in the printed manual.

`@group'
     Hold text together that must appear on one printed page.

`@need MILS'
     Start a new printed page if not enough space on this one.


File: texinfo.info,  Node: Line Breaks,  Next: w,  Prev: Break Commands,  Up: Breaks

`@*': Generate Line Breaks
==========================

  The `@*' command forces a line break in both the printed manual and
in Info.

  For example,

     This line @* is broken @*in two places.

produces

     This line
      is broken
     in two places.

(Note that the space after the first `@*' command is faithfully carried
down to the next line.)

  The `@*' command is often used in a file's copyright page:

     This is edition 2.0 of the Texinfo documentation,@*
     and is for ...

In this case, the `@*' command keeps TeX from stretching the line
across the whole page in an ugly manner.

     *Please note:* Do not write braces after an `@*' command; they are
     not needed.

     Do not write an `@refill' command at the end of a paragraph
     containing an `@*' command; it will cause the paragraph to be
     refilled after the line break occurs, negating the effect of the
     line break.


File: texinfo.info,  Node: w,  Next: sp,  Prev: Line Breaks,  Up: Breaks

`@w'{TEXT}: Prevent Line Breaks
===============================

  `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.

  You can use the `@w' command to prevent TeX from automatically
hyphenating a long name or phrase that accidentally falls near the end
of a line.

     You can copy GNU software from @w{@file{prep.ai.mit.edu}}.

produces

     You can copy GNU software from `prep.ai.mit.edu'.

  In the Texinfo file, you must write the `@w' command and its argument
(all the affected text) all on one line.

     *Caution:* Do not write an `@refill' command at the end of a
     paragraph containing an `@w' command; it will cause the paragraph
     to be refilled and may thereby negate the effect of the `@w'
     command.


File: texinfo.info,  Node: sp,  Next: page,  Prev: w,  Up: Breaks

`@sp' N: Insert Blank Lines
===========================

  A line beginning with and containing only `@sp N' generates N blank
lines of space in both the printed manual and the Info file.  `@sp'
also forces a paragraph break.  For example,

     @sp 2

generates two blank lines.

  The `@sp' command is most often used in the title page.


File: texinfo.info,  Node: page,  Next: group,  Prev: sp,  Up: Breaks

`@page': Start a New Page
=========================

  A line containing only `@page' starts a new page in a printed manual.
The command has no effect on Info files since they are not paginated.
An `@page' command is often used in the `@titlepage' section of a
Texinfo file to start the copyright page.


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.


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).


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::


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.
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'.


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'.


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.


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.


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.) `@defspec' is equivalent to `@deffn {Special Form} ...'
     and works like `@defun'.


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', write
     braces around it.  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.
     `@defopt' is equivalent to `@defvr {User Option} ...' and works
     like `@defvar'.


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 C or any other language in which you must declare types of
variables and functions.

`@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.


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.

