OS/2 Professional/OS2PRO194.ISO/os2/prgramer/unix/info/texinfo.i05

GNU Info File | 1993-06-12 | 50.9 KB | 1,435 lines

This is Info file texinfo, produced by Makeinfo-1.47 from the input
file texinfo2.tex.

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


File: texinfo,  Node: Smallcaps,  Next: Fonts,  Prev: emph & strong,  Up: Emphasis

`@sc'{TEXT}: The Small Caps Font
--------------------------------

   Use the `@sc' command to set text in the printed output in a small
caps font and set text in the Info file in upper case letters.

   Write the text between braces in lower case, like this:

     The @sc{acm} and @sc{ieee} are technical societies.

This produces:

     The ACM and IEEE are technical societies.

   TeX typesets the small caps font in a manner that prevents the
letters from `jumping out at you on the page'.  This makes small caps
text easier to read than text in all upper case.

   If the text between the braces of an `@sc' command is upper case,
TeX typesets the text in full-size capitals.  Use full-size capitals
sparingly.

   The Info formatting commands set all small caps text in upper case.

   You may also use the small caps font for a jargon word such as ATO
(a NASA word meaning `abort to orbit').

   There are subtleties to using the small caps font with a jargon word
such as CDR, a word used in Lisp programming.  In this case, you should
use the small caps font when the word refers to the second and
subsequent elements of a list (the CDR of the list), but you should use
`@code' when the word refers to the Lisp function of the same spelling.


File: texinfo,  Node: Fonts,  Prev: Smallcaps,  Up: Emphasis

Fonts for Printing, Not Info
----------------------------

   Texinfo provides four font commands that specify font changes in the
printed manual but have no effect in the Info file.  `@i' requests
italic font (in some versions of TeX, a slanted font is used), `@b'
requests bold face, `@t' requests the fixed-width, typewriter-style
font used by `@code', and `@r' requests a roman font, which is the
usual font in which text is printed.  All four commands apply to an
argument that follows, surrounded by braces.

   Only the `@r' command has much use: in example programs, you can use
the `@r' command to convert code comments from the fixed-width font to
a roman font.  This looks better in printed output.

   For example,

     @lisp
     (+ 2 2)    ; @r{Add two plus two.}
     @end lisp

produces

     (+ 2 2)    ; Add two plus two.

   If possible, you should avoid using the other three font commands.
If you need to use one, it probably indicates a gap in the Texinfo
language.


File: texinfo,  Node: Quotations and Examples,  Next: Lists and Tables,  Prev: Marking Text,  Up: Top

Quotations and Examples
***********************

   Quotations and examples are blocks of text consisting of one or more
whole paragraphs that are set off from the bulk of the text and treated
differently.  They are usually indented.

   In Texinfo, you always begin a quotation or example by writing an
@-command at the beginning of a line by itself, and end it by writing
an `@end' command that is also at the beginning of a line by itself.
For instance, you begin an example by writing `@example' by itself at
the beginning of a line and end the example by writing `@end example'
on a line by itself, at the beginning of that line.

* Menu:

* Block Enclosing Commands::    Use different constructs for
                                  different purposes.
* quotation::                   How to write a quotation.
* example::                     How to write an example in a fixed-width font.
* noindent::                    How to prevent paragraph indentation.
* Lisp Example::                How to illustrate Lisp code.
* smallexample & smalllisp::    Forms for the `@smallbook' option.
* display::                     How to write an example in the current font.
* format::                      How to write an example that does not narrow
                                  the margins.
* exdent::                      How to undo the indentation of a line.
* flushleft & flushright::      How to push text flushleft or flushright.
* cartouche::                   How to draw cartouches around examples.


File: texinfo,  Node: Block Enclosing Commands,  Next: quotation,  Up: Quotations and Examples

The Block Enclosing Commands
============================

   There are a number of commands for quotations and examples:

`@quotation'
     Indicate text that is quoted. The text is filled, indented, and
     printed in a roman font by default.

`@example'
     Illustrate code, commands, and the like. The text is printed in a
     fixed-width font, and indented but not filled.

`@lisp'
     Illustrate Lisp code. The text is printed in a fixed-width font,
     and indented but not filled.

`@smallexample'
     Illustrate code, commands, and the like.  Similar to `@example',
     except that in TeX this command typesets text in a smaller font
     for the smaller `@smallbook' format than for the 8.5 by 11 inch
     format.

`@smalllisp'
     Illustrate Lisp code.  Similar to `@lisp', except that in TeX this
     command typesets text in a smaller font for the smaller
     `@smallbook' format than for the 8.5 by 11 inch format.

`@display'
     Display illustrative text.  The text is indented but not filled,
     and no font is specified (so, by default, the font is roman).

`@format'
     Print illustrative text.  The text is not indented and not filled
     and no font is specified (so, by default, the font is roman).

   The `@exdent' command is used within the above constructs to undo
the indentation of a line.

   The `@flushleft' and `@flushright' commands are used to line up the
left or right margins of unfilled text.

   The `@noindent' command may be used after one of the above
constructs to prevent the following text from being indented as a new
paragraph.

   You can use the `@cartouche' command within one of the above
constructs to highlight the example or quotation by drawing a box with
rounded corners around it.  (The `@cartouche' command affects only the
printed manual; it has no effect in the Info file; see *Note Drawing
Cartouches Around Examples: cartouche.)


File: texinfo,  Node: quotation,  Next: example,  Prev: Block Enclosing Commands,  Up: Quotations and Examples

`@quotation'
============

   The text of a quotation is processed normally except that

   * the margins are closer to the center of the page, so the whole of
     the quotation is indented;

   * the first lines of paragraphs are indented no more than other
     lines;

   * in the printed output, interline and interparagraph spacing is
     reduced.

     This is an example of text written between an `@quotation' command
     and an `@end quotation' command.  An `@quotation' command is most
     often used to indicate text that is excerpted from another (real
     or hypothetical) printed work.

   Write an `@quotation' command as text on a line by itself.  This
line will disappear from the output.  Mark the end of the quotation
with a line beginning with and containing only `@end quotation'. The
`@end quotation' line will likewise disappear from the output.  Thus,
the input

     @quotation
     This is
     a foo.
     @end quotation

produces

     This is a foo.


File: texinfo,  Node: example,  Next: noindent,  Prev: quotation,  Up: Quotations and Examples

`@example'
==========

   The `@example' command is used to indicate an example that is not
part of the running text, such as computer input or output.

     This is an example of text written between an
     `@example' command
     and an `@end example'command.
     The text is indented but not filled.

     In the printed manual, the text is typeset in a
     fixed-width font, and extra spaces and blank lines are
     significant.  In the Info file, an analogous result is
     obtained by indenting each line with five spaces.

   Write an `@example' command at the beginning a line by itself. This
line will disappear from the output. Mark the end of the example with
an  `@end example' command, also written at the beginning a line by
itself. The `@end example' will disappear from the output.

   For example,

     @example
     mv foo bar
     @end example

produces

     mv foo bar

   Since the lines containing `@example' and `@end example' will
disappear, you should put a blank line before the `@example' and
another blank line after the `@end example'.  (Remember that blank
lines between the beginning `@example' and the ending `@end example'
will appear in the output.)

     *Caution:* Do not use tabs in lines of an example (or anywhere
     else in Texinfo, for that matter)!  TeX treats tabs like single
     spaces, and that is not what they look like.  This is a problem
     with TeX.  (If necessary, in Emacs, you can use `M-x untabify' to
     convert tabs in a region to multiple spaces.)

   Examples are often, logically speaking, "in the middle" of a
paragraph, and the text continues after an example should not be
indented.  The `@noindent' command prevents a piece of text from being
indented as if it were a new paragraph. (*Note noindent::.)

   (The `@code' command is used for examples of code that are embedded
within sentences, not set off from preceding and following text.  *Note
`@code': code.)


File: texinfo,  Node: noindent,  Next: Lisp Example,  Prev: example,  Up: Quotations and Examples

`@noindent'
===========

   If you have text following an `@example' or other similar inclusion
that reads as a continuation of the text before the `@example', it is
good to prevent this text from being indented as a new paragraph.  To
accomplish this, write `@noindent' at the beginning of a line by itself
preceding the continuation text. For example:

     @example
     This is an example
     @end example

     @noindent
     This line is not indented.  As you can see, the
     beginning of the line is fully flush left with the line
     that follows after it.  (This whole example is between
     @code{@@display} and @code{@@end display}.)

produces

          This is an example


     This line is not indented.  As you can see, the
     beginning of the line is fully flush left with the line
     that follows after it.  (This whole example is between
     `@display' and `@end display'.)

   To adjust the number of blank lines properly in the Info file output,
remember that the line containing `@noindent' does not generate a blank
line, and neither does the `@end example' line.

   In the Texinfo source file for this manual, each line that says
`produces' is preceded by a line containing `@noindent'.

   Do not put braces after an `@noindent' command; they are not
necessary, since `@noindent' is a command used outside of paragraphs
(*note Command Syntax::.).


File: texinfo,  Node: Lisp Example,  Next: smallexample & smalllisp,  Prev: noindent,  Up: Quotations and Examples

`@lisp'
=======

   The `@lisp' command is used for Lisp code.  It is synonymous with
the `@example' command.

     This is an example of text written between an
     `@lisp' command and an `@end lisp' command.

   Use `@lisp' instead of `@example' so as to preserve information
regarding the nature of the example.  This is useful, for example, if
you write a function that evaluates only and all the Lisp code in a
Texinfo file.  Then you can use the Texinfo file as a Lisp library.(1)

   Mark the end of `@lisp' with `@end lisp' on a line by itself.

   ---------- Footnotes ----------

   (1)  It would be straightforward to extend Texinfo to work in a
similar fashion for C, FORTRAN, or other languages.


File: texinfo,  Node: smallexample & smalllisp,  Next: display,  Prev: Lisp Example,  Up: Quotations and Examples

`@smallexample' and `@smalllisp'
================================

   In addition to the regular `@example' and `@lisp' commands, Texinfo
has two other "example-style" commands.  These are the `@smallexample'
and `@smalllisp' commands.  Both these commands are designed for use
with the `@smallbook' command that causes TeX to produce a printed
manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
inch format.

   In TeX, the `@smallexample' and `@smalllisp' commands typeset text
in a smaller font for the smaller `@smallbook' format than for the 8.5
by 11 inch format.  Consequently, many examples containing long lines
fit in a narrower, `@smallbook' page without needing to be shortened.
Both commands typeset in the normal font size when you format for the
8.5 by 11 inch size; indeed, in this situation, the `@smallexample' and
`@smalllisp' commands are defined to be the `@example' and `@lisp'
commands.

   In Info, the `@smallexample' and `@smalllisp' commands are
equivalent to the `@example' and `@lisp' commands, and work exactly the
same.

   Mark the end of `@smallexample' or `@smalllisp' with `@end
smallexample' or `@end smalllisp', respectively.

     This is an example of text written between `@smallexample' and
     `@end smallexample'.  In Info and in an 8.5 by 11 inch manual,
     this text appears in its normal size; but in a 7 by 9.25 inch manual,
     this text appears in a smaller font.

   The `@smallexample' and `@smalllisp' commands make it easier to
prepare smaller format manuals without forcing you to edit examples by
hand to fit them onto narrower pages.

   *Note Printing "Small" Books: smallbook, for more information about
the `@smallbook' command.


File: texinfo,  Node: display,  Next: format,  Prev: smallexample & smalllisp,  Up: Quotations and Examples

`@display'
==========

   The `@display' command begins a kind of example.  It is like the
`@example' command except that, in a printed manual, `@display' does
not select the fixed-width font.  In fact, it does not specify the font
at all, so that the text appears in the same font it would have
appeared in without the `@display' command.

     This is an example of text written between an `@display' command
     and an `@end display' command.  The `@display' command
     indents the text, but does not fill it.


File: texinfo,  Node: format,  Next: exdent,  Prev: display,  Up: Quotations and Examples

`@format'
=========

   The `@format' command is similar to `@example' except that, in the
printed manual, `@format' does not select the fixed-width font and does
not narrow the margins.

This is an example of text written between an `@format' command
and an `@end format' command.  As you can see
from this example,
the `@format' command does not fill the text.


File: texinfo,  Node: exdent,  Next: flushleft & flushright,  Prev: format,  Up: Quotations and Examples

`@exdent': Undoing a Line's Indentation
=======================================

   The `@exdent' command removes any indentation a line might have. The
command is written at the beginning of a line and applies only to the
text that follows the command that is on the same line.  Do not use
braces around the text.  In a printed manual, the text on an `@exdent'
line is printed in the roman font.

   `@exdent' is usually used within examples.  Thus,

     @example
     This line follows an @@example command.
     @exdent This line is exdented.
     This line follows the exdented line.
     The @@end example comes on the next line.
     @end group

produces

     This line follows an @example command.
This line is exdented.
     This line follows the exdented line.
     The @end example comes on the next line.

   In practice, the `@exdent' command is rarely used. Usually, you
un-indent text by ending the example and returning the page to its
normal width.


File: texinfo,  Node: flushleft & flushright,  Next: cartouche,  Prev: exdent,  Up: Quotations and Examples

`@flushleft' and `@flushright'
==============================

   The `@flushleft' and `@flushright' commands line up the ends of
lines on the left and right margins of a page, but do not fill the
text.  The commands are written on lines of their own, without braces.
The `@flushleft' and `@flushright' commands are ended by `@end
flushleft' and `@end flushright' commands on lines of their own.

   For example,

     @flushleft
     This text is
     written flushleft.
     @end flushleft

produces

     This text is
     written flushleft.

Flushright produces the type of indentation often used in the return
address of letters.


For example,

     @flushright
     Here is an example of text written
     flushright.  The @code{@flushright} command
     right justifies every line but leaves the
     left end ragged.
     @end flushright

produces

                                     Here is an example of text written
                                 flushright.  The `@flushright' command
                              right justifies every line but leaves the
                                                       left end ragged.


File: texinfo,  Node: cartouche,  Prev: flushleft & flushright,  Up: Quotations and Examples

Drawing Cartouches Around Examples
==================================

   In a printed manual, the `@cartouche' command draws a box with
rounded corners around its contents.  You can use this command to
further highlight an example or quotation.  For instance, you could
write a manual in which one type of example is surrounded by a cartouche
for emphasis.

   The `@cartouche' command affects only the printed manual; it has no
effect in the Info file.

   For example,

     @example
     @cartouche
     % pwd
     /usr/local/lib/emacs/info
     @end cartouche
     @end group

surrounds the two-line example with a box with rounded corners, in the
printed manual.


File: texinfo,  Node: Lists and Tables,  Next: Indices,  Prev: Quotations and Examples,  Up: Top

Making Lists and Tables
***********************

   Texinfo has several ways of making lists and two-column tables.
Lists can be bulleted or numbered, while two-column tables can
highlight the items in the first column.

* Menu:

* Introducing Lists::           Texinfo formats lists for you.
* itemize::                     How to construct a simple list.
* enumerate::                   How to construct a numbered list.
* Two-column Tables::           How to construct a two-column table.


File: texinfo,  Node: Introducing Lists,  Next: itemize,  Up: Lists and Tables

Introducing Lists
=================

   Texinfo automatically indents the text in lists or tables, and
numbers an enumerated list.  This last feature is useful if you modify
the list, since you do not need to renumber it yourself.

   Numbered lists and tables begin with the appropriate @-command at the
beginning of a line, and end with the corresponding `@end' command on a
line by itself.  The table and itemized-list commands also require that
you write formatting information on the same line as the beginning
@-command.

   Begin an enumerated list, for example, with an `@enumerate' command
and end the list with an `@end enumerate' command. Begin an itemized
list with an `@itemize' command, followed on the same line by a
formatting command such as `@bullet', and end the list with an `@end
itemize' command.

   Precede each element of a list with an `@item' command.

Here is an itemized list of the different kinds of table and lists:

   * Itemized lists with and without bullets.

   * Enumerated lists, using numbers or letters.

   * Two-column tables with highlighting.

Here is an enumerated list with the same items:

  1. Itemized lists with and without bullets.

  2. Enumerated lists, using numbers or letters.

  3. Two-column tables with highlighting.

And here is a two-column table with the same items and their @-commands:

`@itemize'
     Itemized lists with and without bullets.

`@enumerate'
     Enumerated lists, using numbers or letters.

`@table'
`@ftable'
`@vtable'
     Two-column tables with highlighting.


File: texinfo,  Node: itemize,  Next: enumerate,  Prev: Introducing Lists,  Up: Lists and Tables

Making an Itemized List
=======================

   The `@itemize' command is used to produce sequences of indented
paragraphs, with a bullet or other mark inside the left margin at the
beginning of each paragraph for which such a mark is desired.

   Begin an itemized list by writing `@itemize' at the beginning of a
line.  Follow the command, on the same line, with a character or a
Texinfo command that generates a mark.  Usually, you will write
`@bullet' after `@itemize', but you can use `@minus', or any character
or any special symbol that results in a single character in the Info
file.  (When you write `@bullet' or `@minus' after an `@itemize'
command, you may omit the `{}'.)

   Write the text of the indented paragraphs themselves after the
`@itemize', up to another line that says `@end itemize'.

   Before each paragraph for which a mark in the margin is desired,
write a line that says just `@item'.  Do not write any other text on
this line.

   Usually, you should put a blank line before an `@item'.  This puts a
blank line in the Info file. (TeX inserts the proper interline
whitespace in either case.)  Except when the entries are very brief,
these blank lines make the list look better.

   Here is an example of the use of `@itemize', followed by the output
it produces.  Note that `@bullet' produces an `*' in Info and a round
dot in TeX.

     @itemize @bullet
     @item
     Some text for foo.

     @item
     Some text
     for bar.
     @end itemize

This produces:

        * Some text for foo.

        * Some text for bar.

   Itemized lists may be embedded within other itemized lists.  Here is
a list marked with dashes embedded in a list marked with bullets:

     @itemize @bullet
     @item
     First item.

     @itemize @minus
     @item
     Inner item.

     @item
     Second inner item.
     @end itemize

     @item
     Second outer item.
     @end itemize

This produces:

        * First item.

             - Inner item.

             - Second inner item.

        * Second outer item.


File: texinfo,  Node: enumerate,  Next: Two-column Tables,  Prev: itemize,  Up: Lists and Tables

Making a Numbered or Lettered List
==================================

   `@enumerate' is like `@itemize' except that the marks in the left
margin contain successive integers or letters. (*Note `@itemize':
itemize.)

   Write the `@enumerate' command at the beginning of a line. The
command does not require an argument, but accepts either a number or a
letter as an option. Without an argument, `@enumerate' starts the list
with the number 1.  With a numeric argument, such as 3, the command
starts the list with that number. With an upper or lower case letter,
such as `a' or `A', the command starts the list with that letter.

   Write the text of the enumerated list in the same way you write an
itemized list: put `@item' on a line of its own before the start of
each paragraph that you want enumerated.  Do not write any other text on
the line beginning with `@item'.

   You should put a blank line between entries in the list. This
generally makes it easier to read the Info file.

   Here is an example of `@enumerate' without an argument:

     @enumerate
     @item
     Underlying causes.

     @item
     Proximate causes.
     @end enumerate

This produces:

  1. Underlying causes.

  2. Proximate causes.

   Here is an example with an argument of `3':

     @enumerate 3
     @item
     Predisposing causes.

     @item
     Precipitating causes.

     @item
     Perpetuating causes.
     @end enumerate

This produces:

  3. Predisposing causes.

  4. Precipitating causes.

  5. Perpetuating causes.

   Here is a brief summary of the alternatives.  The summary is
constructed using `@enumerate' with an argument of `a'.

  a. `@enumerate'

     Without an argument, produce a numbered list, starting with the
     number 1.

  b. `@enumerate POSITIVE-INTEGER'

     With a (positive) numeric argument, start a numbered list with that
     number.  You can use this to continue a list that you interrupted
     with other text.

  c. `@enumerate UPPER-CASE-LETTER'

     With an upper case letter as argument, start a list in which each
     item is marked by a letter, beginning with that upper case letter.

  d. `@enumerate LOWER-CASE-LETTER'

     With a lower case letter as argument, start a list in which each
     item is marked by a letter, beginning with that lower case letter.

   You can also nest enumerated lists, as in an outline.


File: texinfo,  Node: Two-column Tables,  Prev: enumerate,  Up: Lists and Tables

Making a Two-column Table
=========================

   `@table' is similar to `@itemize', but the command allows you to
specify a name or heading line for each item.  (*Note `@itemize':
itemize.)  The `@table' command is used to produce two-column tables,
and is especially useful for glossaries and explanatory exhibits.

* Menu:

* table::                       How to construct a two-column table.
* ftable vtable::               How to construct a two-column table
                                  with automatic indexing.
* itemx::                       How to put more entries in the first column.


File: texinfo,  Node: table,  Next: ftable vtable,  Up: Two-column Tables

Using the `@table' Command
--------------------------

   Use the `@table' command to produce two-column tables.

   Write the `@table' command at the beginning of a line and follow it
on the same line with an argument that is a Texinfo command such as
`@code', `@samp', `@var', or `@kbd'. Although these commands are
usually followed by arguments in braces, in this case you use the
command name without an argument because `@item' will supply the
argument.  This command will be applied to the text that goes into the
first column of each item and determines how it will be highlighted.
For example, `@samp' will cause the text in the first column to be
highlighted with an `@samp' command.

   You may also choose to use the `@asis' command as an argument to
`@table'.  `@asis' is a command that does nothing; if you use this
command after `@table', TeX and the Info formatting commands output the
first column entries without added highlighting, (`as is').

   (The `@table' command may work with other commands besides those
listed here.  However, you can only use commands that normally take
arguments in braces.)

   Begin each table entry with an `@item' command at the beginning of a
line.  Write the first column text on the same line as the `@item'
command.  Write the second column text on the line following the
`@item' line and on subsequent lines.  (You do not need to type
anything for an empty second column entry.)  You may write as many
lines of supporting text as you wish, even several paragraphs.  But
only text on the same line as the `@item' will be placed in the first
column.

   Normally, you should put a blank line before an `@item' line. This
puts a blank like in the Info file.  Except when the entries are very
brief, a blank line looks better.

   The following table, for example, highlights the text in the first
column with an `@samp' command:

     @table @samp
     @item foo
     This is the text for
     @samp{foo}.

     @item bar
     Text for @samp{bar}.
     @end table

This produces:

`foo'
     This is the text for `foo'.

`bar'
     Text for `bar'.

   If you want to list two or more named items with a single block of
text, use the `@itemx' command.  (*Note  `@itemx': itemx.)


File: texinfo,  Node: ftable vtable,  Next: itemx,  Prev: table,  Up: Two-column Tables

`@ftable' and `@vtable'
-----------------------

   The `@ftable' and `@vtable' commands are the same as the `@table'
command except that `@ftable' automatically enters each of the items in
the first column of the table into the index of functions and `@vtable'
automatically enters each of the items in the first column of the table
into the index of variables.  This simplifies the task of creating
indices.  Only the items on the same line as the `@item' commands are
indexed, and they are indexed in exactly the form that they appear on
that line.  *Note  Creating Indices: Indices, for more information
about indices.

   Begin a two-column table using `@ftable' or `@vtable' by writing the
@-command at the beginning of a line, followed on the same line by an
argument that is a Texinfo command such as `@code', exactly as you
would for an `@table' command; and end the table with an `@end ftable'
or `@end vtable' command on a line by itself.


File: texinfo,  Node: itemx,  Prev: ftable vtable,  Up: Two-column Tables

`@itemx'
--------

   Use the `@itemx' command inside a table when you have two or more
first column entries for the same item, each of which should appear on
a line of its own.  Use `@itemx' for all but the first entry.  The
`@itemx' command works exactly like `@item' except that it does not
generate extra vertical space above the first column text.  For example,

     @table @code
     @item upcase
     @itemx downcase
     These two functions accept a character or a string as
     argument, and return the corresponding upper case (lower
     case) character or string.@refill
     @end table

produces

`upcase'
`downcase'
     These two functions accept a character or a string as argument,
     and return the corresponding upper case (lower case) character or
     string.

(Note also that this example illustrates multi-line supporting text in
a two-column table.)


File: texinfo,  Node: Indices,  Next: Insertions,  Prev: Lists and Tables,  Up: Top

Creating Indices
****************

   Using Texinfo, you can generate indices without having to sort and
collate entries manually.  In an index, the entries are listed in
alphabetical order, together with information on how to find the
discussion of each entry.  In a printed manual, this information
consists of page numbers.  In an Info file, this information is a menu
entry leading to the first node referenced.

   Texinfo provides several predefined kinds of index: an index for
functions, an index for variables, an index for concepts, and so on.
You can combine indices or use them for other than their canonical
purpose.  If you wish, you can define your own indices.

* Menu:

* Index Entries::               Choose different words for index entries.
* Predefined Indices::          Use different indices for different kinds
                                  of entry.
* Indexing Commands::           How to make an index entry.
* Combining Indices::           How to combine indices.
* New Indices::                 How to define your own indices.


File: texinfo,  Node: Index Entries,  Next: Predefined Indices,  Up: Indices

Making Index Entries
====================

   When you are making index entries, it is good practice to think of
the different ways people may look for something.  Different people *do
not* think of the same words when they look something up.  A helpful
index will have items indexed under all the different words that people
may use.  For example, one reader may think it obvious that the
two-letter names for indices should be listed under "Indices,
two-letter names", since the word "Index" is the general concept. But
another reader may remember the specific concept of two-letter names
and search for the entry listed as "Two letter names for indices".  A
good index will have both entries and will help both readers.

   Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until you
need to do it yourself.

   *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,  Node: Predefined Indices,  Next: Indexing Commands,  Prev: Index Entries,  Up: Indices

Predefined Indices
==================

   Texinfo provides six predefined indices:

   * A "concept index" listing concepts that are discussed.

   * A "function index" listing functions (such as entry points of
     libraries).

   * A "variables index" listing variables (such as global variables of
     libraries).

   * A "keystroke index" listing keyboard commands.

   * A "program index" listing names of programs.

   * A "data type index" listing data types (such as structures defined
     in header files).

Not every manual needs all of these, and most manuals use two or three
of them.  This manual has two indices: a concept index and an @-command
index (that is actually the function index but is called a command
index in the chapter heading).  Two or more indices can be combined
into one using the `@synindex' or `@syncodeindex' commands.  *Note
Combining Indices::.


File: texinfo,  Node: Indexing Commands,  Next: Combining Indices,  Prev: Predefined Indices,  Up: Indices

Defining the Entries of an Index
================================

   The data to make an index come from many individual indexing commands
scattered throughout the Texinfo source file.  Each command says to add
one entry to a particular index; after formatting, the index will give
the current page number or node name as the reference.

   An index entry consists of an indexing command at the beginning of a
line followed, on the rest of the line, by the entry.

   For example, this section begins with the following five entries for
the concept index:

     @cindex Defining indexing entries
     @cindex Index entries
     @cindex Entries for an index
     @cindex Specifying index entries
     @cindex Creating index entries

   Each predefined index has its own indexing command--`@cindex' for
the concept index, `@findex' for the function index, and so on.

   The usual convention is to capitalize the first word of each index
entry, unless that word is the name of a function, variable, or other
such entity that should not be capitalized.  Thus, if you are
documenting Emacs Lisp, you should usually capitalize entries in the
concept index, but not those in the function index. However, if your
concept index entries are consistently short (one or two words each) it
may look better for each regular entry to start with a lower case
letter.  Whichever convention you adapt, please be consistent!

   By default, entries for a concept index are printed in a small roman
font and entries for the other indices are printed in a small `@code'
font.  You may change the way part of an entry is printed with the
usual Texinfo commands, such as `@file' for file names and `@emph' for
emphasis (*note Marking Text::.).

   The six indexing commands for predefined indices are:

`@cindex CONCEPT'
     Make an entry in the concept index for CONCEPT.

`@findex FUNCTION'
     Make an entry in the function index for FUNCTION.

`@vindex VARIABLE'
     Make an entry in the variable index for VARIABLE.

`@kindex KEYSTROKE'
     Make an entry in the key index for KEYSTROKE.

`@pindex PROGRAM'
     Make an entry in the program index for PROGRAM.

`@tindex DATA TYPE'
     Make an entry in the data type index for DATA TYPE.

     *Caution:* Do not use a colon in an index entry.  In Info, a colon
     separates the menu entry name from the node name.  An extra colon
     confuses Info. *Note How to Write a Menu Entry: Writing a Menu
     Entry, for more information about the structure of a menu entry.

   If you write several identical index entries in different places in a
Texinfo file, the index in the printed manual will list all the pages to
which those entries refer.  However, the index in the Info file will
list *only* the node that references the *first* of those index
entries.  Therefore, it is best to write indices in which each entry
refers to only one place in the Texinfo file.  Fortunately, this
constraint is a feature rather than a loss since it means that the index
will be easy to use.  Otherwise, you could create an index that lists
several pages for one entry and your reader would not know to which page
to turn.  If you have two identical entries for one topic, change the
topics slightly, or qualify them to indicate the difference.

   You are not actually required to use the predefined indices for their
canonical purposes.  For example, suppose you wish to index some C
preprocessor macros.  You could put them in the function index along
with actual functions, just by writing `@findex' commands for them;
then, when you print the "Function Index" as an unnumbered chapter, you
could give it the title `Function and Macro Index' and all will be
consistent for the reader.  Or you could put the macros in with the
data types by writing `@tindex' commands for them, and give that index
a suitable title so the reader will understand. (*Note Printing Indices
& Menus::.)


File: texinfo,  Node: Combining Indices,  Next: New Indices,  Prev: Indexing Commands,  Up: Indices

Combining Indices
=================

   Sometimes you will want to combine two disparate indices such as
functions and concepts, perhaps because you have few enough of one of
them that a separate index for them would look silly.

   You could put functions into the concept index by writing `@cindex'
commands for them instead of `@findex' commands, and produce a
consistent manual by printing the concept index with the title
`Function and Concept Index' and not printing the `Function Index' at
all; but this is not a robust procedure.  It works only if your
document is never included as part of another document that is designed
to have a separate function index; if your document were to be included
with such a document, the functions from your document and those from
the other would not end up together. Also, to make your function names
appear in the right font in the concept index, you would need to
enclose every one of them between the braces of `@code'.

* Menu:

* syncodeindex::                How to merge two indices, using `@code'
                                  font for the merged-from index.
* synindex::                    How to merge two indices, using the
                                  default font of the merged-to index.


File: texinfo,  Node: syncodeindex,  Next: synindex,  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,  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,  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,  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.


File: texinfo,  Node: Braces Atsigns Periods,  Next: dmn,  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,  Node: Inserting An Atsign,  Next: Inserting Braces,  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,  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,  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 U.S.A.@: is a continental nation.

produces

     The U.S.A. is a continental nation.

   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 X. and to Y@.  Give it to Z@.
     Give it to X. and to Y.  Give it to Z.

produces

     Give it to X. and to Y.  Give it to Z.
     Give it to X. and to Y.  Give it to Z.

   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,  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 `8.27in', you may write
`8.27 in.' or `8.27 inches'.


File: texinfo,  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,  Node: dots,  Next: bullet,  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.


File: texinfo,  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::.


File: texinfo,  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,  Node: tex,  Next: copyright symbol,  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,  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)'.