This is texinfo.info, produced by texi2any version 5.1 from texinfo.txi.

This manual is for GNU Texinfo (version 5.1, 11 March 2013), a
documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

  Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998,
1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
2012, 2013 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover Texts
     being "A GNU Manual", and with the Back-Cover Texts as in (a)
     below. A copy of the license is included in the section entitled
     "GNU Free Documentation License".

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual. Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* makeinfo: (texinfo)Invoking makeinfo.         Translate Texinfo source.
* pod2texi: (pod2texi)Invoking pod2texi.        Translate Perl POD to Texinfo.
* texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
* texi2pdf: (texinfo)PDF Output.                PDF output for Texinfo.
* pdftexi2dvi: (texinfo)PDF Output.             PDF output for Texinfo.
* texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
END-INFO-DIR-ENTRY


File: texinfo.info,  Node: Multitable Column Widths,  Next: Multitable Rows,  Up: Multi-column Tables

11.5.1 Multitable Column Widths
-------------------------------

You can define the column widths for a multitable in two ways: as
fractions of the line length; or with a prototype row.  Mixing the two
methods is not supported.  In either case, the widths are defined
entirely on the same line as the '@multitable' command.

  1. To specify column widths as fractions of the line length, write
     '@columnfractions' and the decimal numbers (presumably less than 1;
     a leading zero is allowed and ignored) after the '@multitable'
     command, as in:

          @multitable @columnfractions .33 .33 .33

     The fractions need not add up exactly to 1.0, as these do not.
     This allows you to produce tables that do not need the full line
     length.

  2. To specify a prototype row, write the longest entry for each column
     enclosed in braces after the '@multitable' command.  For example:

          @multitable {some text for column one} {for column two}

     The first column will then have the width of the typeset 'some text
     for column one', and the second column the width of 'for column
     two'.

     The prototype entries need not appear in the table itself.

     Although we used simple text in this example, the prototype entries
     can contain Texinfo commands; markup commands such as '@code' are
     particularly likely to be useful.


File: texinfo.info,  Node: Multitable Rows,  Prev: Multitable Column Widths,  Up: Multi-column Tables

11.5.2 Multitable Rows
----------------------

After the '@multitable' command defining the column widths (see the
previous section), you begin each row in the body of a multitable with
'@item', and separate the column entries with '@tab'.  Line breaks are
not special within the table body, and you may break input lines in your
source file as necessary.

  You can also use '@headitem' instead of '@item' to produce a "heading
row".  The TeX output for such a row is in bold, and the HTML and
Docbook output uses the '<thead>' tag.  In Info, the heading row is
followed by a separator line made of dashes ('-' characters).

  The command '@headitemfont' can be used in templates when the entries
in an '@headitem' row need to be used in a template.  It is a synonym
for '@b', but using '@headitemfont' avoids any dependency on that
particular font style, in case we provide a way to change it in the
future.

  Here is a complete example of a multi-column table (the text is from
'The GNU Emacs Manual', *note Splitting Windows: (emacs)Split Window.):

     @multitable @columnfractions .15 .45 .4
     @headitem Key @tab Command @tab Description
     @item C-x 2
     @tab @code{split-window-vertically}
     @tab Split the selected window into two windows,
     with one above the other.
     @item C-x 3
     @tab @code{split-window-horizontally}
     @tab Split the selected window into two windows
     positioned side by side.
     @item C-Mouse-2
     @tab
     @tab In the mode line or scroll bar of a window,
     split that window.
     @end multitable

produces:

Key         Command                          Description
---------------------------------------------------------------------------
C-x 2       'split-window-vertically'        Split the selected window
                                             into two windows, with one
                                             above the other.
C-x 3       'split-window-horizontally'      Split the selected window
                                             into two windows positioned
                                             side by side.
C-Mouse-2                                    In the mode line or scroll
                                             bar of a window, split that
                                             window.


File: texinfo.info,  Node: Special Displays,  Next: Indices,  Prev: Lists and Tables,  Up: Top

12 Special Displays
*******************

The commands in this chapter allow you to write text that is specially
displayed (output format permitting), outside of the normal document
flow.

  One set of such commands is for creating "floats", that is, figures,
tables, and the like, set off from the main text, possibly numbered,
captioned, and/or referred to from elsewhere in the document.  Images
are often included in these displays.

  Another group of commands is for creating footnotes in Texinfo.

* Menu:

* Floats::                      Figures, tables, and the like.
* Images::                      Including graphics and images.
* Footnotes::                   Writing footnotes.


File: texinfo.info,  Node: Floats,  Next: Images,  Up: Special Displays

12.1 Floats
===========

A "float" is a display which is set off from the main text.  It is
typically labeled as being a "Figure", "Table", "Example", or some
similar type.

  A float is so-named because, in principle, it can be moved to the
bottom or top of the current page, or to a following page, in the
printed output.  (Floating does not make sense in other output formats.)
In the present version of Texinfo, however, this floating is
unfortunately not yet implemented.  Instead, the floating material is
simply output at the current location, more or less as if it were an
'@group' (*note @group::).

* Menu:

* @float::                      Producing floating material.
* @caption @shortcaption::      Specifying descriptions for floats.
* @listoffloats::               A table of contents for floats.


File: texinfo.info,  Node: @float,  Next: @caption @shortcaption,  Up: Floats

12.1.1 '@float' [TYPE][,LABEL]: Floating Material
-------------------------------------------------

To produce floating material, enclose the material you want to be
displayed separate between '@float' and '@end float' commands, on lines
by themselves.

  Floating material often uses '@image' to display an already-existing
graphic (*note Images::), or '@multitable' to display a table (*note
Multi-column Tables::).  However, the contents of the float can be
anything.  Here's an example with simple text:

     @float Figure,fig:ex1
     This is an example float.
     @end float

And the output:

This is an example float.

Figure 12.1

  As shown in the example, '@float' takes two arguments (separated by a
comma), TYPE and LABEL.  Both are optional.

TYPE
     Specifies the sort of float this is; typically a word such as
     "Figure", "Table", etc.  If this is not given, and LABEL is, any
     cross referencing will simply use a bare number.

LABEL
     Specifies a cross reference label for this float.  If given, this
     float is automatically given a number, and will appear in any
     '@listoffloats' output (*note @listoffloats::).  Cross references
     to LABEL are allowed.

     On the other hand, if LABEL is not given, then the float will not
     be numbered and consequently will not appear in the '@listoffloats'
     output or be cross-referenceable.

Ordinarily, you specify both TYPE and LABEL, to get a labeled and
numbered float.

  In Texinfo, all floats are numbered in the same way: with the chapter
number (or appendix letter), a period, and the float number, which
simply counts 1, 2, 3, ..., and is reset at each chapter.  Each float
type is counted independently.

  Floats within an '@unnumbered', or outside of any chapter, are simply
numbered consecutively from 1.

  These numbering conventions are not, at present, changeable.


File: texinfo.info,  Node: @caption @shortcaption,  Next: @listoffloats,  Prev: @float,  Up: Floats

12.1.2 '@caption' & '@shortcaption'
-----------------------------------

You may write an '@caption' anywhere within an '@float' environment, to
define a caption for the float.  It is not allowed in any other context.
'@caption' takes a single argument, enclosed in braces.  Here's an
example:

     @float
     An example float, with caption.
     @caption{Caption for example float.}
     @end float

The output is:

An example float, with caption.

Caption for example float.

  '@caption' can appear anywhere within the float; it is not processed
until the '@end float'.  The caption text is usually a sentence or two,
but may consist of several paragraphs if necessary.

  In the output, the caption always appears below the float; this is not
currently changeable.  It is preceded by the float type and/or number,
as specified to the '@float' command (see the previous section).

  The '@shortcaption' command likewise may be used only within '@float',
and takes a single argument in braces.  The short caption text is used
instead of the caption text in a list of floats (see the next section).
Thus, you can write a long caption for the main document, and a short
title to appear in the list of floats.  For example:

     @float
     ... as above ...
     @shortcaption{Text for list of floats.}
     @end float

  The text for '@shortcaption' may not contain comments ('@c'), verbatim
text ('@verb'), environments such as '@example', footnotes ('@footnote')
or other complex constructs.  The same constraints apply to '@caption'
unless there is an '@shortcaption'.


File: texinfo.info,  Node: @listoffloats,  Prev: @caption @shortcaption,  Up: Floats

12.1.3 '@listoffloats': Tables of Contents for Floats
-----------------------------------------------------

You can write an '@listoffloats' command to generate a list of floats
for a given float type (*note @float::), analogous to the document's
overall table of contents.  Typically, it is written in its own
'@unnumbered' node to provide a heading and structure, rather like
'@printindex' (*note Printing Indices & Menus::).

  '@listoffloats' takes one optional argument, the float type.  Here's
an example:

     @node List of Figures
     @unnumbered List of Figures
     @listoffloats Figure

And the output from '@listoffloats':

* Menu:

*      Figure 12.1:      fig:ex1.        

  Without any argument, '@listoffloats' generates a list of floats for
which no float type was specified, i.e., no first argument to the
'@float' command (*note @float::).

  Each line in the list of floats contains the float type (if any), the
float number, and the caption, if any--the '@shortcaption' argument, if
it was specified, else the '@caption' argument.  In Info, the result is
a menu where each float can be selected.  In HTML, each line is a link
to the float.  In printed output, the page number is included.

  Unnumbered floats (those without cross reference labels) are omitted
from the list of floats.


File: texinfo.info,  Node: Images,  Next: Footnotes,  Prev: Floats,  Up: Special Displays

12.2 Inserting Images
=====================

You can insert an image given in an external file with the '@image'
command.  Although images can be used anywhere, including the middle of
a paragraph, we describe them in this chapter since they are most often
part of a displayed figure or example.

* Menu:

* Image Syntax::
* Image Scaling::


File: texinfo.info,  Node: Image Syntax,  Next: Image Scaling,  Up: Images

12.2.1 Image Syntax
-------------------

Here is the synopsis of the '@image' command:

     @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}

  The FILENAME argument is mandatory, and must not have an extension,
because the different processors support different formats:

   * TeX (DVI output) reads the file 'FILENAME.eps' (Encapsulated
     PostScript format).

   * pdfTeX reads 'FILENAME.pdf', 'FILENAME.png', 'FILENAME.jpg', or
     'FILENAME.jpeg' (in that order).  It also tries uppercase versions
     of the extensions.  The PDF format does not support EPS images, so
     such must be converted first.

   * For Info, 'makeinfo' includes 'FILENAME.txt' verbatim (more or less
     as if it were in '@verbatim').  The Info output may also include a
     reference to 'FILENAME.png' or 'FILENAME.jpg'.  (See below.)

   * For HTML, 'makeinfo' outputs a reference to 'FILENAME.png',
     'FILENAME.jpg', 'FILENAME.jpeg' or 'FILENAME.gif' (in that order).
     If none of those exist, it gives an error, and outputs a reference
     to 'FILENAME.jpg' anyway.

   * For Docbook, 'makeinfo' outputs references to 'FILENAME.eps',
     'FILENAME.gif' 'FILENAME.jpg', 'FILENAME.pdf', 'FILENAME.png' and
     'FILENAME.svg', for every file found.  Als, 'FILENAME.txt' is
     included verbatim, if present.

   * For Info and HTML output, 'makeinfo' uses the optional fifth
     argument EXTENSION to '@image' for the filename extension, if it is
     specified and the file is found.  Any leading period should be
     included in EXTENSION.  For example:

          @image{foo,,,,.xpm}

  If you want to install image files for use by Info readers too, we
recommend putting them in a subdirectory like 'FOO-figures' for a
package FOO.  Copying the files into '$(infodir)/FOO-figures/' should be
done in your 'Makefile'.

  The WIDTH and HEIGHT arguments are described in the next section.

  For TeX output, if an image is the only thing in a paragraph it will
ordinarily be displayed on a line by itself, respecting the current
environment indentation, but without the normal paragraph indentation.
If you want it centered, use '@center' (*note @titlefont @center @sp::).

  For HTML output, 'makeinfo' sets the "alt attribute" for inline images
to the optional ALTTEXT (fourth) argument to '@image', if supplied.  If
not supplied, 'makeinfo' uses the full file name of the image being
displayed.  The ALTTEXT is processed as Texinfo text, so special
characters such as '"' and '<' and '&' are escaped in the HTML output;
also, you can get an empty 'alt' string with '@-' (a command that
produces no output; *note @- @hyphenation::).

  For Info output, the 'alt' string is also processed as Texinfo text
and output.  In this case, '\' is escaped as '\\' and '"' as '\"'; no
other escapes are done.

  In Info output, 'makeinfo' writes a reference to the binary image file
(trying FILENAME suffixed with 'EXTENSION', '.EXTENSION', '.png', or
'.jpg', in that order) if one exists.  It also literally includes the
'.txt' file if one exists.  This way, Info readers which can display
images (such as the Emacs Info browser, running under X) can do so,
whereas Info readers which can only use text (such as the standalone
Info reader) can display the textual version.

  The implementation of this is to put the following construct into the
Info output:

     ^@^H[image src="BINARYFILE" text="TXTFILE"
                alt="ALTTEXT ... ^@^H]

where '^@' and '^H' stand for the actual null and backspace control
characters.  If one of the files is not present, the corresponding
argument is omitted.

  The reason for mentioning this here is that older Info browsers (this
feature was introduced in Texinfo version 4.6) will display the above
literally, which, although not pretty, should not be harmful.


File: texinfo.info,  Node: Image Scaling,  Prev: Image Syntax,  Up: Images

12.2.2 Image Scaling
--------------------

The optional WIDTH and HEIGHT arguments to the '@image' command (see the
previous section) specify the size to which to scale the image.  They
are only taken into account in TeX.  If neither is specified, the image
is presented in its natural size (given in the file); if only one is
specified, the other is scaled proportionately; and if both are
specified, both are respected, thus likely distorting the original image
by changing its aspect ratio.

  The WIDTH and HEIGHT may be specified using any valid TeX dimension,
namely:

pt
     point (72.27pt = 1in)
pc
     pica (1pc = 12pt)
bp
     big point (72bp = 1in)
in
     inch
cm
     centimeter (2.54cm = 1in)
mm
     millimeter (10mm = 1cm)
dd
     dido^t point (1157dd = 1238pt)
cc
     cicero (1cc = 12dd)
sp
     scaled point (65536sp = 1pt)

  For example, the following will scale a file 'ridt.eps' to one inch
vertically, with the width scaled proportionately:

     @image{ridt,,1in}

  For '@image' to work with TeX, the file 'epsf.tex' must be installed
somewhere that TeX can find it.  (The standard location is
'TEXMF/tex/generic/dvips/epsf.tex', where TEXMF is a root of your TeX
directory tree.)  This file is included in the Texinfo distribution and
is also available from <ftp://tug.org/tex/epsf.tex>, among other places.

  '@image' can be used within a line as well as for displayed figures.
Therefore, if you intend it to be displayed, be sure to leave a blank
line before the command, or the output will run into the preceding text.

  Image scaling is presently implemented only in TeX, not in HTML or any
other sort of output.


File: texinfo.info,  Node: Footnotes,  Prev: Images,  Up: Special Displays

12.3 Footnotes
==============

A "footnote" is for a reference that documents or elucidates the primary
text.(1)  Footnotes are distracting; use them sparingly at most, and it
is best to avoid them completely.  Standard bibliographical references
are better placed in a bibliography at the end of a document instead of
in footnotes throughout.

* Menu:

* Footnote Commands::           How to write a footnote in Texinfo.
* Footnote Styles::             Controlling how footnotes appear in Info.

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

   (1) A footnote should complement or expand upon the primary text, but
a reader should not need to read a footnote to understand the primary
text.  For a thorough discussion of footnotes, see 'The Chicago Manual
of Style', which is published by the University of Chicago Press.


File: texinfo.info,  Node: Footnote Commands,  Next: Footnote Styles,  Up: Footnotes

12.3.1 Footnote Commands
------------------------

In Texinfo, footnotes are created with the '@footnote' command.  This
command is followed immediately by a left brace, then by the text of the
footnote, and then by a terminating right brace.  Footnotes may be of
any length (they will be broken across pages if necessary), but are
usually short.  The template is:

     ordinary text@footnote{TEXT OF FOOTNOTE}

  As shown here, the '@footnote' command should come right after the
text being footnoted, with no intervening space; otherwise, the footnote
marker might end up starting a line.

  For example, this clause is followed by a sample footnote(1); in the
Texinfo source, it looks like this:

     ...a sample footnote@footnote{Here is the sample
     footnote.}; in the Texinfo source...

  As you can see, the source includes two punctuation marks next to each
other; in this case, '.};' is the sequence.  This is normal (the first
ends the footnote and the second belongs to the sentence being
footnoted), so don't worry that it looks odd.

  In a printed manual or book, the reference mark for a footnote is a
small, superscripted number; the text of the footnote appears at the
bottom of the page, below a horizontal line.

  In Info, the reference mark for a footnote is a pair of parentheses
with the footnote number between them, like this: '(1)'.  The reference
mark is followed by a cross reference link to the footnote text if
footnotes are put in separate nodes (*note Footnote Styles::).

  In the HTML output, footnote references are generally marked with a
small, superscripted number which is rendered as a hypertext link to the
footnote text.

  By the way, footnotes in the argument of an '@item' command for an
'@table' must be on the same line as the '@item' (as usual).  *Note
Two-column Tables::.

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

   (1) Here is the sample footnote.


File: texinfo.info,  Node: Footnote Styles,  Prev: Footnote Commands,  Up: Footnotes

12.3.2 Footnote Styles
----------------------

Info has two footnote styles, which determine where the text of the
footnote is located:

   * In the 'End' node style, all the footnotes for a single node are
     placed at the end of that node.  The footnotes are separated from
     the rest of the node by a line of dashes with the word 'Footnotes'
     within it.  Each footnote begins with an '(N)' reference mark.

     Here is an example of the Info output for a single footnote in the
     end-of-node style:

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

          (1)  Here is a sample footnote.

   * In the 'Separate' node style, all the footnotes for a single node
     are placed in an automatically constructed node of their own.  In
     this style, a "footnote reference" follows each '(N)' reference
     mark in the body of the node.  The footnote reference is actually a
     cross reference which you use to reach the footnote node.

     The name of the node with the footnotes is constructed by appending
     '-Footnotes' to the name of the node that contains the footnotes.
     (Consequently, the footnotes' node for the 'Footnotes' node is
     'Footnotes-Footnotes'!)  The footnotes' node has an 'Up' node
     pointer that leads back to its parent node.

     Here is how the first footnote in this manual looks after being
     formatted for Info in the separate node style:

          File: texinfo.info  Node: Overview-Footnotes, Up: Overview

          (1) The first syllable of "Texinfo" is pronounced like "speck", not
          "hex". ...

  Unless your document has long and important footnotes (as in, say,
Gibbon's 'Decline and Fall ...'), we recommend the 'end' style, as it is
simpler for readers to follow.

  Use the '@footnotestyle' command to specify an Info file's footnote
style.  Write this command at the beginning of a line followed by an
argument, either 'end' for the end node style or 'separate' for the
separate node style.

  For example,

     @footnotestyle end
or
     @footnotestyle separate

  Write an '@footnotestyle' command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  (You should
include any '@footnotestyle' command between the start-of-header and
end-of-header lines, so the region formatting commands will format
footnotes as specified.)

  In HTML, when the footnote style is 'end', or if the output is not
split, footnotes are put at the end of the output.  If set to
'separate', and the output is split, they are placed in a separate file.


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

13 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.  Lastly, you can define your own new indices.

  *Note Printing Indices & Menus::, for information on how to print
indices.

* Menu:

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


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

13.1 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 "Indices" are 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 skilled art, the
subtleties of which may not be 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.info,  Node: Predefined Indices,  Next: Indexing Commands,  Prev: Index Entries,  Up: Indices

13.2 Predefined Indices
=======================

Texinfo provides six predefined indices.  Here are their nominal
meanings, abbreviations, and the corresponding index entry commands:

'cp'
     ('@cindex') concept index, for general concepts.
'fn'
     ('@findex') function index, for function and function-like names
     (such as entry points of libraries).
'ky'
     ('@kindex') keystroke index, for keyboard commands.
'pg'
     ('@pindex') program index, for names of programs.
'tp'
     ('@tindex') data type index, for type names (such as structures
     defined in header files).
'vr'
     ('@vindex') variable index, for variable names (such as global
     variables of libraries).

Not every manual needs all of these, and most manuals use only two or
three at most.  The present manual, for example, 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).

  You are not required to use the predefined indices strictly 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.

  On the other hand, it is best not to stray too far from the meaning of
the predefined indices.  Otherwise, in the event that your text is
combined with other text from other manuals, the index entries will not
match up.  Instead, define your own new index (*note New Indices::).

  We recommend having a single index in the final document whenever
possible, however many source indices you use, since then readers have
only one place to look.  Two or more source indices can be combined into
one output index using the '@synindex' or '@syncodeindex' commands
(*note Combining Indices::).


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

13.3 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, defining
     @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, as listed in
the previous section.

  Concept index entries consist of text.  The best way to write an index
is to devise entries which are terse yet clear.  If you can do this, the
index usually looks better if the entries are written just as they would
appear in the middle of a sentence, that is, capitalizing only proper
names and acronyms that always call for uppercase letters.  This is the
case convention we use in most GNU manuals' indices.

  If you don't see how to make an entry terse yet clear, make it longer
and clear--not terse and confusing.  If many of the entries are several
words long, the index may look better if you use a different convention:
to capitalize the first word of each entry.  Whichever case convention
you use, use it consistently.

  In any event, do not ever capitalize a case-sensitive name such as a C
or Lisp function name or a shell command; that would be a spelling
error.  Entries in indices other than the concept index are symbol names
in programming languages, or program names; these names are usually
case-sensitive, so likewise use upper- and lowercase as required.

  It is a good idea to make index entries unique wherever feasible.
That way, people using the printed output or online completion of index
entries don't see undifferentiated lists.  Consider this an opportunity
to make otherwise-identical index entries be more specific, so readers
can more easily find the exact place they are looking for.

  Index entries should precede the visible material that is being
indexed.  For instance:

     @cindex hello
     Hello, there!

Among other reasons, that way following indexing links (in whatever
context) ends up before the material, where readers want to be, instead
of after.

  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 (*note Marking Text::),
and '@r' for the normal roman font (*note Fonts::).

     Caution: Do not use a colon in an index entry.  In Info, a colon
     separates the menu entry name from the node name, so a colon in the
     entry itself confuses Info.  *Note Menu Parts::, for more
     information about the structure of a menu entry.


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

13.4 Combining Indices
======================

Sometimes you will want to combine two disparate indices such as
functions and concepts, perhaps because you have few enough entries that
a separate index 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
                                 roman font for the merged-from index.


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

13.4.1 '@syncodeindex': Combining indices using '@code'
-------------------------------------------------------

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

13.4.2 '@synindex': Combining indices
-------------------------------------

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

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

In addition to the predefined indices (*note 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

  New index names are usually two-letter words, 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 this 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 'xy' index leads to the
automatic creation of an '@xyindex' command.

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

     @node Author Index
     @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 by default
instead of a roman font.

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

  As mentioned earlier (*note Predefined Indices::), we recommend having
a single index in the final document whenever possible, however many
source indices you use, since then readers have only one place to look.

  When creating an index, TeX creates a file whose extension is the name
of the index (*note Names of index files::).  Therefore you should avoid
using index names that collide with extensions used for other purposes,
such as '.aux' or '.xml'.  'makeinfo' already reports an error if a new
index conflicts well-known extension name.


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

14 Special Insertions
*********************

Texinfo provides several commands for inserting characters that have
special meaning in Texinfo, such as braces, and for other graphic
elements that do not correspond to simple characters you can type.

* Menu:

* Special Characters::          Inserting @ {} , \ #
* Inserting Quote Characters::  Inserting left and right quotes, in code.
* Inserting Space::             Inserting the right amount of whitespace.
* Inserting Accents::           Inserting accents and special characters.
* Inserting Quotation Marks::   Inserting quotation marks.
* Inserting Math::              Formatting mathematical expressions.
* Glyphs for Text::             Inserting Dots, bullets, currencies, etc.
* Glyphs for Programming::      Indicating results of evaluation,
                                 expansion of macros, errors, etc.


File: texinfo.info,  Node: Special Characters,  Next: Inserting Quote Characters,  Up: Insertions

14.1 Special Characters: Inserting @ {} , \ #
=============================================

'@' and curly braces are the basic 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.
Alphabetic commands are also provided.

  The other characters (comma, backslash, hash) are special only in
restricted contexts, as explained in the respective sections.

* Menu:

* Inserting an Atsign::         '@@', '@atchar{}'.
* Inserting Braces::            '@{ @}', '@l rbracechar{}'.
* Inserting a Comma::           , and '@comma{}'.
* Inserting a Backslash::       \ and '@backslashchar{}'.
* Inserting a Hashsign::        # and '@hashchar{}'.


File: texinfo.info,  Node: Inserting an Atsign,  Next: Inserting Braces,  Up: Special Characters

14.1.1 Inserting '@' with '@@' and '@atchar{}'
----------------------------------------------

'@@' produces a single '@' character in the output.  Do not put braces
after an '@@' command.

  '@atchar{}' also produces a single '@' character in the output.  It
does need following braces, as usual for alphabetic commands.  In inline
conditionals (*note Inline Conditionals::), it can be necessary to avoid
using the literal '@' character in the source (and may be clearer in
other contexts).


File: texinfo.info,  Node: Inserting Braces,  Next: Inserting a Comma,  Prev: Inserting an Atsign,  Up: Special Characters

14.1.2 Inserting '{ '}' with '@{ @}' and '@l rbracechar{}'
----------------------------------------------------------

'@{' produces a single '{' in the output, and '@}' produces a single
'}'.  Do not put braces after either an '@{' or an '@}' command.

  '@lbracechar{}' and '@rbracechar{}' also produce single '{' and '}'
characters in the output.  They do need following braces, as usual for
alphabetic commands.  In inline conditionals (*note Inline
Conditionals::), it can be necessary to avoid using literal brace
characters in the source (and may be clearer in other contexts).


File: texinfo.info,  Node: Inserting a Comma,  Next: Inserting a Backslash,  Prev: Inserting Braces,  Up: Special Characters

14.1.3 Inserting ',' with '@comma{}'
------------------------------------

Ordinarily, a comma ',' is a normal character that can be simply typed
in your input where you need it.

  However, Texinfo uses the comma as a special character only in one
context: to separate arguments to those Texinfo commands, such as
'@acronym' (*note @acronym::) and '@xref' (*note Cross References::), as
well as user-defined macros (*note Defining Macros::), which take more
than one argument.

  Since a comma character would confuse Texinfo's parsing for these
commands, you must use the command '@comma{}' instead if you want to
pass an actual comma.  Here are some examples:

     @acronym{ABC, A Bizarre @comma{}}
     @xref{Comma,, The @comma{} symbol}
     @mymac{One argument@comma{} containing a comma}

  Although '@comma{}' can be used nearly anywhere, there is no need for
it anywhere except in this unusual case.

  (Incidentally, the name '@comma' lacks the 'char' suffix used in its
companion commands only for historical reasons.  It didn't seem
important enough to define a synonym.)


File: texinfo.info,  Node: Inserting a Backslash,  Next: Inserting a Hashsign,  Prev: Inserting a Comma,  Up: Special Characters

14.1.4 Inserting '\' with '@backslashchar{}'
--------------------------------------------

Ordinarily, a backslash '\' is a normal character in Texinfo that can be
simply typed in your input where you need it.  The result is to typeset
the backslash from the typewriter font.

  However, Texinfo uses the backslash as a special character in one
restricted context: to delimit formal arguments in the bodies of
user-defined macros (*note Defining Macros::).

  Due to the vagaries of macro argument parsing, it is more reliable to
pass an alphabetic command that produces a backslash instead of using a
literal \.  Hence '@backslashchar{}'.  Here is an example macro call:

     @mymac{One argument@backslashchar{} with a backslash}

  Texinfo documents may also use \ as a command character inside '@math'
(*note Inserting Math::).  In this case, '@\' or '\backslash' produces a
"math" backslash (from the math symbol font), while '@backslashchar{}'
produces a typewriter backslash as usual.

  Although '@backslashchar{}' can be used nearly anywhere, there is no
need for it except in these unusual cases.


File: texinfo.info,  Node: Inserting a Hashsign,  Prev: Inserting a Backslash,  Up: Special Characters

14.1.5 Inserting '#' with '@hashchar{}'
---------------------------------------

Ordinarily, a hash '#' is a normal character in Texinfo that can be
simply typed in your input where you need it.  The result is to typeset
the hash character from the current font.

  This character has many other names, varying by locale, such as
"number sign", "pound", and "octothorp".  It is also sometimes called
"sharp" or "sharp sign" since it vaguely resembles the musical symbol by
that name.  In situations where Texinfo is used, "hash" is the most
common in our experience.

  However, Texinfo uses the hash character as a special character in one
restricted context: to introduce the so-called '#line' directive and
variants (*note External Macro Processors::).

  So, in order to typeset an actual hash character in such a place (for
example, in a program that needs documentation about '#line'), it's
necessary to use '@hashchar{}' or some other construct.  Here's an
example:

     @hashchar{} 10 "example.c"

  Although '@hashchar{}' can be used nearly anywhere, there is no need
for it anywhere except this unusual case.


File: texinfo.info,  Node: Inserting Quote Characters,  Next: Inserting Space,  Prev: Special Characters,  Up: Insertions

14.2 Inserting Quote Characters
===============================

As explained in the early section on general Texinfo input conventions
(*note Conventions::), Texinfo source files use the ASCII character '`'
(96 decimal) to produce a left quote ('), and ASCII ''' (39 decimal) to
produce a right quote (').  Doubling these input characters ('``' and
'''') produces double quotes (" and ").  These are the conventions used
by TeX.

  This works all right for text.  However, in examples of computer code,
readers are especially likely to cut and paste the text verbatim--and,
unfortunately, some document viewers will mangle these characters.  (The
free PDF reader 'xpdf' works fine, but other PDF readers, both free and
nonfree, have problems.)

  If this is a concern for you, Texinfo provides these two commands:

'@codequoteundirected ON-OFF'
     causes the output for the ''' character in code environments to be
     the undirected single quote, like this: '''.

'@codequotebacktick ON-OFF'
     causes the output for the '`' character in code environments to be
     the backtick character (standalone grave accent), like this: '`'.

  If you want these settings for only part of the document,
'@codequote... off' will restore the normal behavior, as in
'@codequoteundirected off'.

  These settings affect '@code', '@example', '@kbd', '@samp', '@verb',
and '@verbatim'.  *Note Useful Highlighting::.

  This feature used to be controlled by '@set' variable names; they are
still supported, but the command interface is preferred.


File: texinfo.info,  Node: Inserting Space,  Next: Inserting Accents,  Prev: Inserting Quote Characters,  Up: Insertions

14.3 Inserting Space
====================

The following sections describe commands that control spacing of various
kinds within and after sentences.

* Menu:

* Multiple Spaces::             Inserting multiple spaces.
* Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
* Ending a Sentence::           Sometimes it does.
* @frenchspacing::              Specifying end-of-sentence spacing.
* @dmn::                        Formatting a dimension.


File: texinfo.info,  Node: Multiple Spaces,  Next: Not Ending a Sentence,  Up: Inserting Space

14.3.1 Multiple Spaces
----------------------

Ordinarily, multiple whitespace characters (space, tab, and newline) are
collapsed into a single space.

  Occasionally, you may want to produce several consecutive spaces,
either for purposes of example (e.g., what your program does with
multiple spaces as input), or merely for purposes of appearance in
headings or lists.  Texinfo supports three commands: '@SPACE', '@TAB',
and '@NL', all of which insert a single space into the output.  (Here,
'@SPACE' represents an '@' character followed by a space, i.e., '@ ',
'TAB' represents an actual tab character, and 'NL' represent the tab
character and end-of-line, i.e., when '@' is the last character on a
line.)

  For example,
     Spacey@ @ @ @
     example.

produces

     Spacey    example.

  Other possible uses of '@SPACE' have been subsumed by '@multitable'
(*note Multi-column Tables::).

  Do not follow any of these commands with braces.

  To produce a non-breakable space, see *note @tie::.


File: texinfo.info,  Node: Not Ending a Sentence,  Next: Ending a Sentence,  Prev: Multiple Spaces,  Up: Inserting Space

14.3.2 Not Ending a Sentence
----------------------------

Depending on whether a period or exclamation point or question mark is
inside or at the end of a sentence, slightly less or more space is
inserted after a period in a typeset manual.  Since it is not always
possible to determine automatically when a period ends a sentence,
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: put two spaces after the period, question mark, or
exclamation mark that ends a sentence.

  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 (lowercase) abbreviations which are not at
the ends of sentences.

  Also, when a parenthetical remark in the middle of a sentence (like
this one!) ends with a period, exclamation point, or question mark, '@:'
should be used after the right parenthesis.  Similarly for right
brackets and right quotes (both single and double).

  For example,

     foo vs.@: bar (or?)@: baz
     foo vs. bar (or?) baz

produces

     foo vs. bar (or?) baz
     foo vs.  bar (or?)  baz

'@:' has no effect on the HTML or Docbook output.

  Do not put braces after '@:' (or any non-alphabetic command).

  A few Texinfo commands force normal interword spacing, so that you
don't have to insert '@:' where you otherwise would.  These are the
code-like highlighting commands, '@var', '@abbr', and '@acronym' (*note
Useful Highlighting::).  For example, in '@code{foo. bar}' the period is
not considered the end of a sentence, and no extra space is inserted.


File: texinfo.info,  Node: Ending a Sentence,  Next: @frenchspacing,  Prev: Not Ending a Sentence,  Up: Inserting Space

14.3.3 Ending a Sentence
------------------------

As mentioned above, Texinfo normally inserts additional space after the
end of a sentence.  It uses a simple heuristic for this: a sentence ends
with a period, exclamation point, or question mark followed by optional
closing punctuation and then whitespace, and _not_ preceded by a capital
letter.

  Use '@.' instead of a period, '@!' instead of an exclamation point,
and '@?' instead of a question mark at the end of a sentence that does
end with a capital letter.  For 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.

The output follows.  In printed output and Info, you can see the desired
extra whitespace after the 'W' in the first line.

     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 HTML output, '@.' is equivalent to a simple '.'; likewise for
'@!' and '@?'.

  The meanings of '@:' and '@.', etc. in Texinfo are designed to work
well with the Emacs sentence motion commands (*note (emacs)Sentences::).

  Do not put braces after any of these commands.

  A few Texinfo commands are not considered as being an abbreviation,
even though they may end with a capital letter when expanded, so that
you don't have to insert '@.' and companions.  This is the case for
code-like highlighting commands, '@var' arguments ending with a capital
letter, and '@TeX'.  For example, that sentence ended with
'@code{@@TeX}.'; '@.' was not needed.  Also in '... @var{VARNAME}. Text'
the period after VARNAME ends the sentence; there is no need to use
'@.'.


File: texinfo.info,  Node: @frenchspacing,  Next: @dmn,  Prev: Ending a Sentence,  Up: Inserting Space

14.3.4 '@frenchspacing' VAL: Control Sentence Spacing
-----------------------------------------------------

In American typography, it is traditional and correct to put extra space
at the end of a sentence.  This is the default in Texinfo (implemented
in Info and printed output; for HTML, we don't try to override the
browser).  In French typography (and others), this extra space is wrong;
all spaces are uniform.

  Therefore Texinfo provides the '@frenchspacing' command to control the
spacing after punctuation.  It reads the rest of the line as its
argument, which must be the single word 'on' or 'off' (always these
words, regardless of the language of the document).  Here is an example:

     @frenchspacing on
     This is text. Two sentences. Three sentences. French spacing.

     @frenchspacing off
     This is text. Two sentences. Three sentences. Non-French spacing.

produces:

  This is text. Two sentences. Three sentences. French spacing.

  This is text.  Two sentences.  Three sentences.  Non-French spacing.

  '@frenchspacing' also affects the output after '@.', '@!', and '@?'
(*note Ending a Sentence::).

  '@frenchspacing' has no effect on the HTML or Docbook output; for XML,
it outputs a transliteration of itself (*note Output Formats::).


File: texinfo.info,  Node: @dmn,  Prev: @frenchspacing,  Up: Inserting Space

14.3.5 '@dmn'{DIMENSION}: Format a Dimension
--------------------------------------------

You can use the '@dmn' command to format a dimension with a little extra
space in the printed output.  That is, on seeing '@dmn', TeX inserts
just enough space for proper typesetting; in other output formats, the
formatting commands insert no space at all.

  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.  Some people prefer '8.27 in.' or
'8.27 inches'.  In these cases, however, you need to use '@tie' (*note
@tie::) or '@w' (*note @w::) so that no line break can occur between the
number and the dimension.  Also, if you write a period after an
abbreviation within a sentence (as with the 'in.' above), you should
write '@:' after the period to prevent TeX from inserting extra
whitespace, as shown here.  *Note Not Ending a Sentence::.


File: texinfo.info,  Node: Inserting Accents,  Next: Inserting Quotation Marks,  Prev: Inserting Space,  Up: Insertions

14.4 Inserting Accents
======================

Here is a table with the commands Texinfo provides for inserting
floating accents.  They all need an argument, the character to accent,
which can either be given in braces as usual ('@'{e}'), or, as a special
case, the braces can be omitted, in which case the argument is the next
character ('@'e').  This is to make the source as convenient as possible
to type and read, since accented characters are very common in some
languages.

  If the command is alphabetic, such as '@dotaccent', then there must be
a space between the command name and argument if braces are not used.
If the command is non-alphabetic, such as '@'', then there must _not_ be
a space; the argument is the very next character.

  Exception: the argument to '@tieaccent' must be enclosed in braces
(since it is two characters instead of one).

  To get the true accented characters output in Info, not just the ASCII
transliterations, it is necessary to specify '@documentencoding' with an
encoding which supports the required characters (*note
@documentencoding::).  In this case, you can also use non-ASCII (e.g.,
pre-accented) characters in the source file.

Command           Output   What
------------------------------------------------------
@"o               o"       umlaut accent
@'o               o'       acute accent
@,{c}             c,       cedilla accent
@=o               o=       macron/overbar accent
@^o               o^       circumflex accent
@`o               o`       grave accent
@~o               o~       tilde accent
@dotaccent{o}     o.       overdot accent
@H{o}             o''      long Hungarian umlaut
@ogonek{a}        a;       ogonek
@ringaccent{o}    o*       ring accent
@tieaccent{oo}    oo[      tie-after accent
@u{o}             o(       breve accent
@ubaraccent{o}    o_       underbar accent
@udotaccent{o}    .o       underdot accent
@v{o}             o<       hacek/check/caron accent

  This table lists the Texinfo commands for inserting other characters
commonly used in languages other than English.

@exclamdown{}     !       upside-down !
@questiondown{}   ?       upside-down ?
@aa{} @AA{}       aa AA   a,A with circle
@ae{} @AE{}       ae AE   ae,AE ligatures
@dh{} @DH{}       d D     Icelandic eth
@dotless{i}       i       dotless i
@dotless{j}       j       dotless j
@l{} @L{}         /l /L   suppressed-L,l
@o{} @O{}         /o /O   O,o with slash
@oe{} @OE{}       oe OE   oe,OE ligatures
@ordf{} @ordm{}   a o     Spanish ordinals
@ss{}             ss      es-zet or sharp S
@th{} @TH{}       th TH   Icelandic thorn


File: texinfo.info,  Node: Inserting Quotation Marks,  Next: Inserting Math,  Prev: Inserting Accents,  Up: Insertions

14.5 Inserting Quotation Marks
==============================

Use doubled single-quote characters to begin and end quotations:
``...''.  TeX converts two single quotes to left- and right-hand doubled
quotation marks, and Info converts doubled single-quote characters to
ASCII double-quotes: ``...'' becomes "...".

  You may occasionally need to produce two consecutive single quotes;
for example, in documenting a computer language such as Maxima where ''
is a valid command.  You can do this with the input '@w{}'; the empty
'@w' command stops the combination into the double-quote characters.

  The left quote character (`, ASCII code 96) used in Texinfo is a grave
accent in ANSI and ISO character set standards.  We use it as a quote
character because that is how TeX is set up, by default.

  Texinfo supports several other quotation marks used in languages other
than English.  Below is a table with the commands Texinfo provides for
inserting quotation marks.

  In order to get the symbols for the quotation marks in encoded Info
output, it is necessary to specify '@documentencoding UTF-8'.  (*Note
@documentencoding::.)  Double guillemets are also present in ISO 8859-1
(aka Latin 1) and ISO 8859-15 (aka Latin 9).

  The standard TeX fonts support the usual quotation marks used in
English (the ones produced with single and doubled ASCII single-quotes).
For the other quotation marks, TeX uses European Computer Modern (EC)
fonts ('ecrm1000' and other variants).  These fonts are freely
available, of course; you can download them from
<http://www.ctan.org/tex-archive/fonts/ec>, among other places.

  The free EC fonts are bitmap fonts created with Metafont.  Especially
for on-line viewing, Type 1 (vector) versions of the fonts are
preferable; these are available in the CM-Super font package
(<http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super>).

  Both distributions include installation instructions.

Command               Glyph   Unicode name (point)
------------------------------------------------------------------------------------
@quotedblleft{} ``    ``      Left double quotation mark (U+201C)
@quotedblright{} ''   ''      Right double quotation mark (U+201D)
@quoteleft{} `        `       Left single quotation mark (U+2018)
@quoteright{} '       '       Right single quotation mark (U+2019)
@quotedblbase{}       ,,      Double low-9 quotation mark (U+201E)
@quotesinglbase{}     ,       Single low-9 quotation mark (U+201A)
@guillemetleft{}      <<      Left-pointing double angle quotation mark (U+00AB)
@guillemetright{}     >>      Right-pointing double angle quotation mark (U+00BB)
@guilsinglleft{}      <       Single left-pointing angle quotation mark (U+2039)
@guilsinglright{}     >       Single right-pointing angle quotation mark (U+203A)

  For the double angle quotation marks, Adobe and LaTeX glyph names are
also supported: '@guillemotleft' and '@guillemotright'.  These names are
incorrect; a "guillemot" is a bird species (a type of auk).

  Traditions for quotation mark usage vary to a great extent between
languages
(<http://en.wikipedia.org/wiki/Quotation_mark%2C_non-English_usage#Overview>).
Texinfo does not provide commands for typesetting quotation marks
according to the numerous traditions.  Therefore, you have to choose the
commands appropriate for the language of your manual.  Sometimes aliases
(*note @alias::) can simplify the usage and make the source code more
readable.  For example, in German, '@quotedblbase' is used for the left
double quote, and the right double quote is the glyph produced by
'@quotedblleft', which is counter-intuitive.  Thus, in this case the
following aliases would be convenient:

     @alias lgqq = quotedblbase
     @alias rgqq = quotedblleft


File: texinfo.info,  Node: Inserting Math,  Next: Glyphs for Text,  Prev: Inserting Quotation Marks,  Up: Insertions

14.6 '@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 and HTML:

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

  The '@math' command has no special effect on the Info and HTML output.
'makeinfo' expands any @-commands as usual, but it does not try to
produce good mathematical formatting in any way.

  However, as far as the TeX output is concerned, plain TeX mathematical
commands are allowed in '@math', starting with '\', and the plain TeX
math characters like '^' and '_' are also recognized.  In essence,
'@math' drops you into plain TeX math mode.

  This allows you to conveniently write superscripts and subscripts (as
in the above example), and also to use all the plain TeX math control
sequences for symbols, functions, and so on, and thus get proper
formatting in the TeX output, at least.

  It's best to use '\' instead of '@' for any such mathematical
commands; otherwise, 'makeinfo' will complain.  On the other hand,
'makeinfo' allows input with matching (but unescaped) braces, such as
'k_{75}', although it complains about such bare braces in regular input.

  Here's an example:

     @math{\sin 2\pi \equiv \cos 3\pi}

which looks like the input in Info and HTML:
     \sin 2\pi \equiv \cos 3\pi

  Since '\' is an escape character inside '@math', you can use '@\' to
get a literal backslash ('\\' will work in TeX, but you'd get the
literal two characters '\\' in Info).  '@\' is not defined outside of
'@math', since a '\' ordinarily produces a literal (typewriter) '\'.
You can also use '@backslashchar{}' in any mode to get a typewriter
backslash.  *Note Inserting a Backslash::.

  For displayed equations, you must at present use TeX directly (*note
Raw Formatter Commands::).


File: texinfo.info,  Node: Glyphs for Text,  Next: Glyphs for Programming,  Prev: Inserting Math,  Up: Insertions

14.7 Glyphs for Text
====================

Texinfo has support for a few additional glyphs that are commonly used
in printed text but not available in ASCII.  Of course, there are many
thousands more.  It is possible to use Unicode characters as-is as far
as 'makeinfo' is concerned, but TeX is not so lucky.

* Menu:

* @TeX @LaTeX::                 The TeX logos.
* @copyright::                  The copyright symbol (c in a circle).
* @registeredsymbol::           The registered symbol (R in a circle).
* @dots::                       How to insert ellipses: ... and ...
* @bullet::                     How to insert a bullet: *
* @euro::                       How to insert the euro currency symbol.
* @pounds::                     How to insert the pounds currency symbol.
* @textdegree::                 How to insert the degrees symbol.
* @minus::                      How to insert a minus sign.
* @geq @leq::                   How to insert greater/less-than-or-equal signs.


File: texinfo.info,  Node: @TeX @LaTeX,  Next: @copyright,  Up: Glyphs for Text

14.7.1 '@TeX'{} (TeX) and '@LaTeX'{} (LaTeX)
--------------------------------------------

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

  Similarly, use the '@LaTeX{}' command to generate 'LaTeX', which is
even more special in printed manuals (and different from the incorrect
'La@TeX{}'.  In Info, the result is just 'LaTeX'.  (LaTeX is another
macro package built on top of TeX, very loosely analogous to Texinfo in
that it emphasizes logical structure, but much (much) larger.)

  The spelling of these commands are unusual for Texinfo, in that they
use both uppercase and lowercase letters.


File: texinfo.info,  Node: @copyright,  Next: @registeredsymbol,  Prev: @TeX @LaTeX,  Up: Glyphs for Text

14.7.2 '@copyright{}' ((C))
---------------------------

Use the '@copyright{}' command to generate the copyright symbol, '(C)'.
Where possible, this is a 'c' inside a circle; in Info, this is '(C)'.

  Legally, it's not necessary to use the copyright symbol; the English
word 'Copyright' suffices, according to international treaty.


File: texinfo.info,  Node: @registeredsymbol,  Next: @dots,  Prev: @copyright,  Up: Glyphs for Text

14.7.3 '@registeredsymbol{}' ((R))
----------------------------------

Use the '@registeredsymbol{}' command to generate the registered symbol,
'(R)'.  Where possible, this is an 'R' inside a circle; in Info, this is
'(R)'.


File: texinfo.info,  Node: @dots,  Next: @bullet,  Prev: @registeredsymbol,  Up: Glyphs for Text

14.7.4 '@dots' (...) and '@enddots' (...)
-----------------------------------------

An "ellipsis" (a sequence of dots) would be spaced wrong when typeset as
a string of periods, so a special command is used in Texinfo: use the
'@dots{}' command to generate a normal ellipsis, which is three dots in
a row, appropriately spaced ... like so.  To emphasize: 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.

  The '@enddots{}' command generates an end-of-sentence ellipsis, which
also has three dots, but with different spacing afterwards, ...  Look
closely to see the difference.

  Here is an ellipsis: ... Here are three periods in a row: ...

  In printed (and usually HTML) output, the three periods in a row are
much closer together than the dots in the ellipsis.


File: texinfo.info,  Node: @bullet,  Next: @euro,  Prev: @dots,  Up: Glyphs for Text

14.7.5 '@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.info,  Node: @euro,  Next: @pounds,  Prev: @bullet,  Up: Glyphs for Text

14.7.6 '@euro' (Euro): Euro Currency Symbol
-------------------------------------------

Use the '@euro{}' command to generate 'Euro'.  Where possible, this is
the symbol for the Euro currency.  Otherwise, the word 'Euro' is used.

  Texinfo cannot magically synthesize support for the Euro symbol where
the underlying system (fonts, software, whatever) does not support it.
Therefore, you may find it preferable to use the word "Euro".  (In
banking contexts, the abbreviation for the Euro is EUR.)

  In order to get the Euro symbol in encoded Info output, for example,
it is necessary to specify '@documentencoding ISO-8859-15' or
'@documentencoding UTF-8' (*Note @documentencoding::.)  The Euro symbol
is in ISO 8859-15 (aka Latin 9), and is _not_ in the more widely-used
ISO 8859-1 (Latin 1).

  The Euro symbol does not exist in the standard TeX fonts (which were
designed before the Euro was legislated into existence).  Therefore, TeX
uses an additional font, named 'feymr10' (along with other variables).
It is freely available, of course; you can download it from
<http://www.ctan.org/tex-archive/fonts/eurosym>, among other places.
The distribution includes installation instructions.


File: texinfo.info,  Node: @pounds,  Next: @textdegree,  Prev: @euro,  Up: Glyphs for Text

14.7.7 '@pounds' (#): Pounds Sterling
-------------------------------------

Use the '@pounds{}' command to generate '#'.  Where possible, this is
the symbol for the pounds sterling British currency.  Otherwise, it is
'#'.


File: texinfo.info,  Node: @textdegree,  Next: @minus,  Prev: @pounds,  Up: Glyphs for Text

14.7.8 '@textdegree' (o): Degrees Symbol
----------------------------------------

Use the '@textdegree{}' command to generate 'o'.  Where possible, this
is the normal symbol for degrees.  Otherwise, it is an 'o'.


File: texinfo.info,  Node: @minus,  Next: @geq @leq,  Prev: @textdegree,  Up: Glyphs for Text

14.7.9 '@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,
shorter than an em-dash:

     '-' is a minus sign generated with '@minus{}',

     '-' is a hyphen generated with the character '-',

     '--' is an em-dash for text.

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

  If you actually want to typeset some math that does a subtraction, it
is better to use '@math'.  Then the regular '-' character produces a
minus sign, as in '@math{a-b}' (*note Inserting Math::).


File: texinfo.info,  Node: @geq @leq,  Prev: @minus,  Up: Glyphs for Text

14.7.10 '@geq' (>=) and '@leq' (<=): Inserting Relations
--------------------------------------------------------

Use the '@geq{}' and '@leq{}' commands to generate greater-than-or-equal
and less-than-equal-signs, '>=' and '<='.  When those symbols are not
available, the ASCII sequences '>=' and '<=' are output.


File: texinfo.info,  Node: Glyphs for Programming,  Prev: Glyphs for Text,  Up: Insertions

14.8 Glyphs for Programming
===========================

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, the
location of point in an editor, and GUI operation sequences.

  The glyph-insertion commands do not need to be used within an example,
but most often they are.  All glyph-insertion commands are followed by
empty braces.

* Menu:

* Glyphs Summary::
* @result::                     How to show the result of expression.
* @expansion::                  How to indicate an expansion.
* @print::                      How to indicate generated output.
* @error::                      How to indicate an error message.
* @equiv::                      How to indicate equivalence.
* @point::                      How to indicate the location of point.
* Click Sequences::             Inserting GUI usage sequences.


File: texinfo.info,  Node: Glyphs Summary,  Next: @result,  Up: Glyphs for Programming

14.8.1 Glyphs Summary
---------------------

Here is a summary of the glyph commands:

=>
     '@result{}' indicates the result of an expression.

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

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

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

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

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

A -> B
     '@clicksequence{A @click{} B' indicates a GUI operation sequence:
     first A, then clicking B, or choosing B from a menu, or otherwise
     selecting it.


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

14.8.2 '@result{}' (=>): Result of an Expression
------------------------------------------------

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

  The '@result{}' command is displayed as '=>', either a double stemmed
arrow or (when that is not available) the ASCII sequence '=>'.

  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,  Prev: @result,  Up: Glyphs for Programming

14.8.3 '@expansion{}' (==>): 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 '==>', either a long arrow
with a flat base or (when that is not available) the ASCII sequence
'==>'.

  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.


File: texinfo.info,  Node: @print,  Next: @error,  Prev: @expansion,  Up: Glyphs for Programming

14.8.4 '@print{}' (-|): Indicating Generated Output
---------------------------------------------------

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

  The '@print{}' command is displayed as '-|', either a horizontal dash
butting against a vertical bar or (when that is not available) the ASCII
sequence '-|'.

  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,  Next: @equiv,  Prev: @print,  Up: Glyphs for Programming

14.8.5 '@error{}' (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->', either the word
'error' in a box in the printed output, the word error followed by an
arrow in other formats or (when no arrow is available) 'error-->'.

  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

  The word 'error->' itself is not part of the error message.


File: texinfo.info,  Node: @equiv,  Next: @point,  Prev: @error,  Up: Glyphs for Programming

14.8.6 '@equiv{}' (==): 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 '==', either a standard mathematical
equivalence sign (three parallel horizontal lines) or (when that is not
available) as the ASCII sequence '=='.

  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,  Next: Click Sequences,  Prev: @equiv,  Up: Glyphs for Programming

14.8.7 '@point{}' (-!-): 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 '-!-', either a pointed star or
(when that is not available) the ASCII sequence '-!-'.

  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: Click Sequences,  Prev: @point,  Up: Glyphs for Programming

14.8.8 Click Sequences
----------------------

When documenting graphical interfaces, it is necessary to describe
sequences such as 'Click on 'File', then choose 'Open', then ...'.
Texinfo offers commands '@clicksequence' and 'click' to represent this,
typically used like this:

     ... @clicksequence{File @click{} Open} ...

which produces:

     ... File -> Open ...

  The '@click' command produces a right arrow by default; this glyph is
also available independently via the command '@arrow{}'.

  You can change the glyph produced by '@click' with the command
'@clickstyle', which takes a command name as its single argument on the
rest of the line, much like '@itemize' and friends (*note @itemize::).
The command should produce a glyph, and the usual empty braces '{}' are
omitted.  Here's an example:

     @clickstyle @result
     ... @clicksequence{File @click{} Open} ...

now produces:

     ... File => Open ...


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

15 Forcing and Preventing Breaks
********************************

Line and page breaks can sometimes occur in the 'wrong' place in one or
another form of output.  It's up to you to ensure that text looks right
in all the output formats.

  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.

  You can use the break, break prevention, or pagination commands to fix
problematic line and page breaks.

* Menu:

* Break Commands::              Summary of break-related commands.
* Line Breaks::                 Forcing line breaks.
* @-  @hyphenation::            Helping TeX with hyphenation points.
* @allowcodebreaks::            Controlling line breaks within @code text.
* @w::                          Preventing unwanted line breaks in text.
* @tie::                        Inserting an unbreakable but varying space.
* @sp::                         Inserting blank lines.
* @page::                       Forcing the start of a new page.
* @group::                      Preventing unwanted page breaks.
* @need::                       Another way to prevent unwanted page breaks.


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

15.1 Break Commands
===================

The break commands create or allow line and paragraph breaks:

'@*'
     Force a line break.

'@sp N'
     Skip N blank lines.

'@-'
     Insert a discretionary hyphen.

'@hyphenation{HY-PHEN-A-TED WORDS}'
     Define hyphen points in HY-PHEN-A-TED WORDS.

  These commands hold text together on a single line:

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

'@tie{}'
     Insert a normal interword space at which a line break may not
     occur.

  The pagination commands apply only to printed output, since other
output formats do not have pages.

'@page'
     Start a new page.

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

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


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

15.2 '@*' and '@/': Generate and Allow Line Breaks
==================================================

The '@*' command forces a line break in all output formats.  The '@/'
command allows a line break (printed manual only).

  Here is an example with '@*':

     This sentence is broken @*into two lines.

produces

     This sentence is broken
     into two lines.

  The '@/' command can often be useful within urls (*note @url::), which
tend to be long and are otherwise unbreakable.  For example:

     The official Texinfo home page is on the GNU web site:
     @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.

produces

     The official Texinfo home page is on the GNU web site:
     <http://www.gnu.org/software/gnu/texinfo>.

Without the '@/' commands, TeX would have nowhere to break the url.
'@/' has no effect in other output formats.


File: texinfo.info,  Node: @- @hyphenation,  Next: @allowcodebreaks,  Prev: Line Breaks,  Up: Breaks

15.3 '@-' and '@hyphenation': Helping TeX Hyphenate
===================================================

Although TeX's hyphenation algorithm is generally pretty good, it does
miss useful hyphenation points from time to time.  (Or, far more rarely,
insert an incorrect hyphenation.)  So, for documents with an unusual
vocabulary or when fine-tuning for a printed edition, you may wish to
help TeX out.  Texinfo supports two commands for this:

'@-'
     Insert a discretionary hyphen, i.e., a place where TeX can (but
     does not have to) hyphenate.  This is especially useful when you
     notice an overfull hbox is due to TeX missing a hyphenation (*note
     Overfull hboxes::).  TeX will not insert any hyphenation points
     itself into a word containing '@-'.

'@hyphenation{HY-PHEN-A-TED WORDS}'
     Tell TeX how to hyphenate HY-PHEN-A-TED WORDS.  As shown, you put a
     '-' at each hyphenation point.  For example:
          @hyphenation{man-u-script man-u-scripts}
     TeX only uses the specified hyphenation points when the words match
     exactly, so give all necessary variants, such as plurals.

  Info, HTML, and other non-TeX output is not hyphenated, so none of
these commands have any effect there.


File: texinfo.info,  Node: @allowcodebreaks,  Next: @w,  Prev: @- @hyphenation,  Up: Breaks

15.4 '@allowcodebreaks': Control Line Breaks in '@code'
=======================================================

Ordinarily, TeX considers breaking lines at '-' and '_' characters
within '@code' and related commands (*note @code::), more or less as if
they were "empty" hyphenation points.

  This is necessary since many manuals, especially for Lisp-family
languages, must document very long identifiers.  On the other hand, some
manuals don't have this problems, and you may not wish to allow a line
break at the underscore in, for example, 'SIZE_MAX', or even worse,
after any of the four underscores in '__typeof__'.

  So Texinfo provides this command:

     @allowcodebreaks false

to prevent from breaking at '-' or '_' within '@code'.  You can go back
to allowing such breaks with '@allowcodebreaks true'.  Write these
commands on lines by themselves.

  These commands can be given anywhere in the document.  For example,
you may have just one problematic paragraph where you need to turn off
the breaks, but want them in general, or vice versa.

  This command has no effect except in HTML and TeX output.


File: texinfo.info,  Node: @w,  Next: @tie,  Prev: @allowcodebreaks,  Up: Breaks

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

'@w{TEXT}' outputs TEXT, while prohibiting line breaks within TEXT.

  Thus, you can use '@w' to produce a non-breakable space, fixed at the
width of a normal interword space:

     @w{ } @w{ } @w{ } indentation.

produces:

           indentation.

  The space from '@w{ }', as well as being non-breakable, also will not
stretch or shrink.  Sometimes that is what you want, for instance if
you're doing manual indenting.  However, usually you want a normal
interword space that does stretch and shrink (in the printed output);
for that, see the '@tie' command in the next section.

  You can also use the '@w' command to prevent TeX from automatically
hyphenating a long name or phrase that happens to fall near the end of a
line.  'makeinfo' does not ever hyphenate words.

  You can also use '@w' to avoid unwanted keyword expansion in source
control systems.  For example, to literally write $Id$ in your document,
use '@w{$}Id$'.  This trick isn't effective in Info or plain text
output, though.


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

15.6 '@tie{}': Inserting an Unbreakable Space
=============================================

The '@tie{}' command produces a normal interword space at which a line
break may not occur.  Always write it with following (empty) braces, as
usual for commands used within a paragraph.  Here's an example:

     @TeX{} was written by Donald E.@tie{}Knuth.

produces:

     TeX was written by Donald E. Knuth.

  There are two important differences between '@tie{}' and '@w{ }':

   * The space produced by '@tie{}' will stretch and shrink slightly
     along with the normal interword spaces in the paragraph; the space
     produced by '@w{ }' will not vary.

   * '@tie{}' allows hyphenation of the surrounding words, while '@w{ }'
     inhibits hyphenation of those words (for TeXnical reasons, namely
     that it produces an '\hbox').


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

15.7 '@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

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

A line containing only '@page' starts a new page in a printed manual.
In other formats, without the concept of pages, it starts a new
paragraph.  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

15.9 '@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

15.10 '@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 other output formats 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: Internationalization,  Prev: Breaks,  Up: Top

16 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 (*note Predefined
Indices::).

  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::            Writing descriptions using definition commands.
* Def Cmd Continuation Lines::  Continuing the heading over source lines.
* Optional Arguments::          Handling optional and repeated arguments.
* @deffnx::                     Group two or more 'first' lines.
* Def Cmds in Detail::          Reference for all the definition commands.
* Def Cmd Conventions::         Conventions for writing definitions.
* Sample Function Definition::  An example.


File: texinfo.info,  Node: Def Cmd Template,  Next: Def Cmd Continuation Lines,  Up: Definition Commands

16.1 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: a line with the
'@def...' command and whatever arguments are appropriate for that
command; the body of the definition; and a corresponding '@end' line.

  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 command 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',
enclose it in braces.  For example:

     @deffn {Interactive Command} isearch-forward
     ...
     @end deffn

Otherwise, the second word will be mistaken for the name of the entity.
As a general rule, when any of the arguments in the heading line
_except_ the last one are more than one word, you need to enclose them
in braces.  This may also be necessary if the text contains commands,
for example, '{declaraci@'on}' if you are writing in Spanish.

  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.
Three predefined, specialized variations ('@defun', '@defmac', and
'@defspec') specify the category for you: "Function", "Macro", and
"Special Form" respectively.  (In Lisp, a special form is an entity much
like a function.)  Similarly, the general '@defvr' command is
accompanied by several specialized variations for describing particular
kinds of variables.

  *Note Sample Function Definition::, for a detailed example of a
function definition, including the use of '@example' inside the
definition.


File: texinfo.info,  Node: Def Cmd Continuation Lines,  Next: Optional Arguments,  Prev: Def Cmd Template,  Up: Definition Commands

16.2 Definition Command Continuation Lines
==========================================

The heading line of a definition command can get very long.  Therefore,
Texinfo has a special syntax allowing them to be continued over multiple
lines of the source file: a lone '@' at the end of each line to be
continued.  Here's an example:

     @defun fn-name @
       arg1 arg2 arg3
     This is the basic continued defun.
     @end defun

produces:

 -- Function: fn-name arg1 arg2 arg3
     This is the basic continued defun.

As you can see, the continued lines are combined, as if they had been
typed on one source line.

  Although this example only shows a one-line continuation,
continuations may extend over any number of lines, in the same way; put
an '@' at the end of each line to be continued.

  In general, any number of spaces or tabs before the '@' continuation
character are collapsed into a single space.  There is one exception:
the Texinfo processors will not fully collapse whitespace around a
continuation inside braces.  For example:

     @deffn {Category @
       Name} ...

The output (not shown) has excess space between 'Category' and 'Name'.
To avoid this, elide the unwanted whitespace in your input, or put the
continuation '@' outside braces.

  '@' does not function as a continuation character in _any_ other
context.  Ordinarily, '@' followed by a whitespace character (space,
tab, newline) produces a normal interword space (*note Multiple
Spaces::).


File: texinfo.info,  Node: Optional Arguments,  Next: @deffnx,  Prev: Def Cmd Continuation Lines,  Up: Definition Commands

16.3 Optional and Repeated Arguments
====================================

Some entities take optional or repeated arguments, conventionally
specified by using square brackets and ellipses: an argument enclosed
within square brackets is optional, and an argument followed by an
ellipsis is optional and may be repeated more than once.

  Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional and
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
(complicated) 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,
including a continuation to avoid a long source line.

     @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

16.4 '@deffnx', et al.: 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 definition command has an 'x' form: '@defunx', '@defvrx',
'@deftypefunx', etc.

  The 'x' forms work similarly to '@itemx' (*note @itemx::).


File: texinfo.info,  Node: Def Cmds in Detail,  Next: Def Cmd Conventions,  Prev: @deffnx,  Up: Definition Commands

16.5 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.
* Data Types::                  The definition command for data types.
* Abstract Objects::            Commands for object-oriented programming.


File: texinfo.info,  Node: Functions Commands,  Next: Variables Commands,  Up: Def Cmds in Detail

16.5.1 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 slanted type in
     the printed output, because we think of these names as
     metasyntactic variables--they stand for the actual argument values.
     Within the text of the description, however, 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.

     In the extremely unusual case when an argument name contains '--',
     or another character sequence which is treated specially (*note
     Conventions::), use '@code' around the special characters.  This
     avoids the conversion to typographic en-dashes and em-dashes.

     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 ...'.  Terminate the
     definition with '@end defun' on a line of its own.  Thus, the
     template is:

          @defun FUNCTION-NAME ARGUMENTS...
          BODY-OF-DEFINITION
          @end defun

'@defmac NAME ARGUMENTS...'
     The '@defmac' command is the definition command for macros.
     '@defmac' is equivalent to '@deffn Macro ...' and works like
     '@defun'.

'@defspec NAME ARGUMENTS...'
     The '@defspec' command is the definition command for special forms.
     (In Lisp, a special form is an entity much like a function; *note
     (elisp)Special Forms::.)  '@defspec' is equivalent to '@deffn
     {Special Form} ...' and works like '@defun'.

  All these commands create entries in the index of functions.


File: texinfo.info,  Node: Variables Commands,  Next: Typed Functions,  Prev: Functions Commands,  Up: Def Cmds in Detail

16.5.2 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 follow it on the
     same line by the category of the entity and the name of the entity.

     We recommend capitalizing the category name like a title.  If the
     name of the category contains spaces, as in the name "User Option",
     enclose it in braces.  Otherwise, the second word will be mistaken
     for the name of the entity.  For example,

          @defvr {User Option} fill-column
          This buffer-local variable specifies
          the maximum width of filled lines.
          ...
          @end defvr

     Terminate the definition with '@end defvr' on a line of its own.

     The template is:

          @defvr CATEGORY NAME
          BODY-OF-DEFINITION
          @end defvr

     '@defvr' creates an entry in the index of variables for NAME.

'@defvar NAME'
     The '@defvar' command is the definition command for variables.
     '@defvar' is equivalent to '@defvr Variable ...'.

     For example:

          @defvar kill-ring
          ...
          @end defvar

     The template is:

          @defvar NAME
          BODY-OF-DEFINITION
          @end defvar

     '@defvar' creates an entry in the index of variables for NAME.

'@defopt NAME'
     The '@defopt' command is the definition command for "user options",
     i.e., variables intended for users to change according to taste;
     Emacs has many such (*note (emacs)Variables::).  '@defopt' is
     equivalent to '@defvr {User Option} ...' and works like '@defvar'.
     It creates an entry in the index of variables.


File: texinfo.info,  Node: Typed Functions,  Next: Typed Variables,  Prev: Variables Commands,  Up: Def Cmds in Detail

16.5.3 Functions in Typed Languages
-----------------------------------

The '@deftypefn' command and its variations are for describing functions
in languages in which you must declare types of variables and functions,
such as C and C++.

'@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
     The '@deftypefn' command is the general definition command for
     functions and similar entities that may take arguments and that are
     typed.  The '@deftypefn' command is written at the beginning of a
     line and is followed on the same line by the category of entity
     being described, the type of the returned value, the name of this
     particular entity, and its arguments, if any.

     For example,

          @deftypefn {Library Function} int foobar @
            (int @var{foo}, float @var{bar})
          ...
          @end deftypefn

     produces:

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

     Since in typed languages, the actual names of the arguments are
     typically scattered among data type names and keywords, Texinfo
     cannot find them without help.  You can either (a) write everything
     as straight text, and it will be printed in slanted type; (b) use
     '@var' for the variable names, which will uppercase the variable
     names in Info and use the slanted typewriter font in printed
     output; (c) use '@var' for the variable names and '@code' for the
     type names and keywords, which will be dutifully obeyed.

     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

     (In these examples the '@deftypefn' arguments are shown using
     continuations (*note Def Cmd Continuation Lines::), but could be on
     a single line.)

     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 ...'.  The template is:

          @deftypefun TYPE NAME ARGUMENTS...
          BODY-OF-DESCRIPTION
          @end deftypefun

     '@deftypefun' creates an entry in the index of functions for NAME.

  Ordinarily, the return type is printed on the same line as the
function name and arguments, as shown above.  In source code, GNU style
is to put the return type on a line by itself.  So Texinfo provides an
option to do that: '@deftypefnnewline on'.

  This affects typed functions only--not untyped functions, not typed
variables, etc..  Specifically, it affects the commands in this section,
and the analogous commands for object-oriented languages, namely
'@deftypeop' and '@deftypemethod' (*note Object-Oriented Methods::).

  Specifying '@deftypefnnewline off' reverts to the default.


File: texinfo.info,  Node: Typed Variables,  Next: Data Types,  Prev: Typed Functions,  Up: Def Cmds in Detail

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

           -- Global Flag: int enable
               ...

     The template is:

          @deftypevr CATEGORY DATA-TYPE NAME
          BODY-OF-DESCRIPTION
          @end deftypevr

'@deftypevar DATA-TYPE NAME'
     The '@deftypevar' command is the specialized definition command for
     variables in typed languages.  '@deftypevar' is equivalent to
     '@deftypevr Variable ...'.  The template is:

          @deftypevar DATA-TYPE NAME
          BODY-OF-DESCRIPTION
          @end deftypevar

  These commands create entries in the index of variables.


File: texinfo.info,  Node: Data Types,  Next: Abstract Objects,  Prev: Typed Variables,  Up: Def Cmds in Detail

16.5.5 Data Types
-----------------

Here is the command for data types:

'@deftp CATEGORY NAME ATTRIBUTES...'
     The '@deftp' command is the generic definition command for data
     types.  The command is written at the beginning of a line and is
     followed on the same line by the category, by the name of the type
     (which is a word like 'int' or 'float'), and then by names of
     attributes of objects of that type.  Thus, you could use this
     command for describing 'int' or 'float', in which case you could
     use 'data type' as the category.  (A data type is a category of
     certain objects for purposes of deciding which operations can be
     performed on them.)

     In Lisp, for example, "pair" names a particular data type, and an
     object of that type has two slots called the CAR and the CDR.  Here
     is how you would write the first line of a definition of 'pair'.

          @deftp {Data type} pair car cdr
          ...
          @end deftp

     The template is:

          @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
          BODY-OF-DEFINITION
          @end deftp

     '@deftp' creates an entry in the index of data types.


File: texinfo.info,  Node: Abstract Objects,  Prev: Data Types,  Up: Def Cmds in Detail

16.5.6 Object-Oriented Programming
----------------------------------

Here are the commands for formatting descriptions about abstract
objects, such as are used in object-oriented programming.  A class is a
defined type of abstract object.  An instance of a class is a particular
object that has the type of the class.  An instance variable is a
variable that belongs to the class but for which each instance has its
own value.

* Menu:

* Variables: Object-Oriented Variables.
* Methods:   Object-Oriented Methods.


File: texinfo.info,  Node: Object-Oriented Variables,  Next: Object-Oriented Methods,  Up: Abstract Objects

16.5.6.1 Object-Oriented Variables
..................................

These commands allow you to define different sorts of variables in
object-oriented programming languages.

'@defcv CATEGORY CLASS NAME'
     The '@defcv' command is the general definition command for
     variables associated with classes in object-oriented programming.
     The '@defcv' command is followed by three arguments: the category
     of thing being defined, the class to which it belongs, and its
     name.  For instance:

          @defcv {Class Option} Window border-pattern
          ...
          @end defcv

     produces:
      -- Class Option of Window: border-pattern
          ...

     '@defcv' creates an entry in the index of variables.

'@deftypecv CATEGORY CLASS DATA-TYPE NAME'
     The '@deftypecv' command is the definition command for typed class
     variables in object-oriented programming.  It is analogous to
     '@defcv' with the addition of the DATA-TYPE parameter to specify
     the type of the instance variable.  Ordinarily, the data type is a
     programming language construct that should be marked with '@code'.
     For instance:

          @deftypecv {Class Option} Window @code{int} border-pattern
          ...
          @end deftypecv

     produces:

      -- Class Option of Window: 'int' border-pattern
          ...

     '@deftypecv' creates an entry in the index of variables.

'@defivar CLASS NAME'
     The '@defivar' command is the definition command for instance
     variables in object-oriented programming.  '@defivar' is equivalent
     to '@defcv {Instance Variable} ...'.  For instance:

          @defivar Window border-pattern
          ...
          @end defivar

     produces:

      -- Instance Variable of Window: border-pattern
          ...

     '@defivar' creates an entry in the index of variables.

'@deftypeivar CLASS DATA-TYPE NAME'
     The '@deftypeivar' command is the definition command for typed
     instance variables in object-oriented programming.  It is analogous
     to '@defivar' with the addition of the DATA-TYPE parameter to
     specify the type of the instance variable.  Ordinarily, the data
     type is a programming language construct that should be marked with
     '@code'.  For instance:

          @deftypeivar Window @code{int} border-pattern
          ...
          @end deftypeivar

     produces:

      -- Instance Variable of Window: 'int' border-pattern
          ...

     '@deftypeivar' creates an entry in the index of variables.


File: texinfo.info,  Node: Object-Oriented Methods,  Prev: Object-Oriented Variables,  Up: Abstract Objects

16.5.6.2 Object-Oriented Methods
................................

These commands allow you to define different sorts of function-like
entities resembling methods in object-oriented programming languages.
These entities take arguments, as functions do, but are associated with
particular classes of objects.

'@defop CATEGORY CLASS NAME ARGUMENTS...'
     The '@defop' command is the general definition command for these
     method-like entities.

     For example, some systems have constructs called "wrappers" that
     are associated with classes as methods are, but that act more like
     macros than like functions.  You could use '@defop Wrapper' to
     describe one of these.

     Sometimes it is useful to distinguish methods and "operations".
     You can think of an operation as the specification for a method.
     Thus, a window system might specify that all window classes have a
     method named 'expose'; we would say that this window system defines
     an 'expose' operation on windows in general.  Typically, the
     operation has a name and also specifies the pattern of arguments;
     all methods that implement the operation must accept the same
     arguments, since applications that use the operation do so without
     knowing which method will implement it.

     Often it makes more sense to document operations than methods.  For
     example, window application developers need to know about the
     'expose' operation, but need not be concerned with whether a given
     class of windows has its own method to implement this operation.
     To describe this operation, you would write:

          @defop Operation windows expose

     The '@defop' command is written at the beginning of a line and is
     followed on the same line by the overall name of the category of
     operation, the name of the class of the operation, the name of the
     operation, and its arguments, if any.

     The template is:
          @defop CATEGORY CLASS NAME ARGUMENTS...
          BODY-OF-DEFINITION
          @end defop

     '@defop' creates an entry, such as ''expose' on 'windows'', in the
     index of functions.

'@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
     The '@deftypeop' command is the definition command for typed
     operations in object-oriented programming.  It is similar to
     '@defop' with the addition of the DATA-TYPE parameter to specify
     the return type of the method.  '@deftypeop' creates an entry in
     the index of functions.

'@defmethod CLASS NAME ARGUMENTS...'
     The '@defmethod' command is the definition command for methods in
     object-oriented programming.  A method is a kind of function that
     implements an operation for a particular class of objects and its
     subclasses.

     '@defmethod' is equivalent to '@defop Method ...'.  The command is
     written at the beginning of a line and is followed by the name of
     the class of the method, the name of the method, and its arguments,
     if any.

     For example:
          @defmethod bar-class bar-method argument
          ...
          @end defmethod

     illustrates the definition for a method called 'bar-method' of the
     class 'bar-class'.  The method takes an argument.

     '@defmethod' creates an entry in the index of functions.

'@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
     The '@deftypemethod' command is the definition command for methods
     in object-oriented typed languages, such as C++ and Java.  It is
     similar to the '@defmethod' command with the addition of the
     DATA-TYPE parameter to specify the return type of the method.
     '@deftypemethod' creates an entry in the index of functions.

  The typed commands are affected by the '@deftypefnnewline' option
(*note Functions in Typed Languages: Typed Functions.).


File: texinfo.info,  Node: Def Cmd Conventions,  Next: Sample Function Definition,  Prev: Def Cmds in Detail,  Up: Definition Commands

16.6 Conventions for Writing Definitions
========================================

When you write a definition using '@deffn', '@defun', or one of the
other definition commands, please take care to use arguments that
indicate the meaning, as with the COUNT argument to the 'forward-word'
function.  Also, if the name of an argument contains the name of a type,
such as INTEGER, take care that the argument actually is of that type.


File: texinfo.info,  Node: Sample Function Definition,  Prev: Def Cmd Conventions,  Up: Definition Commands

16.7 A Sample Function Definition
=================================

A function definition uses the '@defun' and '@end defun' commands.  The
name of the function follows immediately after the '@defun' command and
it is followed, on the same line, by the parameter list.

  Here is a definition from *note (elisp)Calling Functions::.

      -- Function: apply function &rest arguments
          'apply' calls FUNCTION with ARGUMENTS, just like 'funcall' but
          with one difference: the last of ARGUMENTS is a list of
          arguments to give to FUNCTION, rather than a single argument.
          We also say that this list is "appended" to the other
          arguments.

          'apply' returns the result of calling FUNCTION.  As with
          'funcall', FUNCTION must either be a Lisp function or a
          primitive function; special forms and macros do not make sense
          in 'apply'.

               (setq f 'list)
                   => list
               (apply f 'x 'y 'z)
               error-> Wrong type argument: listp, z
               (apply '+ 1 2 '(3 4))
                   => 10
               (apply '+ '(1 2 3 4))
                   => 10

               (apply 'append '((a b c) nil (x y z) nil))
                   => (a b c x y z)

          An interesting example of using 'apply' is found in the
          description of 'mapcar'.

  In the Texinfo source file, this example looks like this:

     @defun apply function &rest arguments
     @code{apply} calls @var{function} with
     @var{arguments}, just like @code{funcall} but with one
     difference: the last of @var{arguments} is a list of
     arguments to give to @var{function}, rather than a single
     argument.  We also say that this list is @dfn{appended}
     to the other arguments.

     @code{apply} returns the result of calling
     @var{function}.  As with @code{funcall},
     @var{function} must either be a Lisp function or a
     primitive function; special forms and macros do not make
     sense in @code{apply}.

     @example
     (setq f 'list)
         @result{} list
     (apply f 'x 'y 'z)
     @error{} Wrong type argument: listp, z
     (apply '+ 1 2 '(3 4))
         @result{} 10
     (apply '+ '(1 2 3 4))
         @result{} 10

     (apply 'append '((a b c) nil (x y z) nil))
         @result{} (a b c x y z)
     @end example

     An interesting example of using @code{apply} is found
     in the description of @code{mapcar}.
     @end defun

In this manual, this function is listed in the Command and Variable
Index under 'apply'.

  Ordinary variables and user options are described using a format like
that for functions except that variables do not take arguments.


File: texinfo.info,  Node: Internationalization,  Next: Conditionals,  Prev: Definition Commands,  Up: Top

17 Internationalization
***********************

Texinfo has some support for writing in languages other than English,
although this area still needs considerable work.  (If you are yourself
helping to translate the fixed strings written to documents, *note
Internationalization of Document Strings::.)

  For a list of the various accented and special characters Texinfo
supports, see *note Inserting Accents::.

* Menu:

* @documentlanguage::           Declaring the current language.
* @documentencoding::           Declaring the input encoding.


File: texinfo.info,  Node: @documentlanguage,  Next: @documentencoding,  Up: Internationalization

17.1 '@documentlanguage LL[_CC]': Set the Document Language
===========================================================

The '@documentlanguage' command declares the current document locale.
Write it on a line by itself, near the beginning of the file, but after
'@setfilename' (*note @setfilename::):

     @documentlanguage LL[_CC]

  Include a two-letter ISO 639-2 language code (LL) following the
command name, optionally followed by an underscore and two-letter
ISO 3166 two-letter country code (CC).  If you have a multilingual
document, the intent is to be able to use this command multiple times,
to declare each language change.  If the command is not used at all, the
default is 'en_US' for US English.

  As with GNU Gettext (*note (gettext)Top::), if the country code is
omitted, the main dialect is assumed where possible.  For example, 'de'
is equivalent to 'de_DE' (German as spoken in Germany).

  For Info and other online output, this command changes the translation
of various "document strings" such as "see" in cross references (*note
Cross References::), "Function' in defuns (*note Definition Commands::),
and so on.  Some strings, such as "Node:", "Next:", "Menu:", etc., are
keywords in Info output, so are not translated there; they are
translated in other output formats.

  For TeX, this command causes a file 'txi-LOCALE.tex' to be read (if it
exists).  If '@documentlanguage' argument contains the optional '_CC'
suffix, this is tried first.  For example, with '@documentlanguage
de_DE', TeX first looks for 'txi-de_DE.tex', then 'txi-de.tex'.

  Such a 'txi-*' file is intended to redefine the various English words
used in TeX output, such as 'Chapter', 'See', and so on.  We are aware
that individual words like these cannot always be translated in
isolation, and that a very different strategy would be required for
ideographic (among other) scripts.  Help in improving Texinfo's language
support is welcome.

  '@documentlanguage' also changes TeX's current hyphenation patterns,
if the TeX program being run has the necessary support included.  This
will generally not be the case for 'tex' itself, but will often be the
case for recent distributions of extended TeX programs 'etex' (DVI
output) and 'pdftex' (PDF output), such as TeX Live 2008.  'texi2dvi'
will use the extended TeXs if they are available (*note Format with
texi2dvi::).

  In September 2006, the W3C Internationalization Activity released a
new recommendation for specifying languages:
<http://www.rfc-editor.org/rfc/bcp/bcp47.txt>.  When Gettext supports
this new scheme, Texinfo will too.

  Since the lists of language codes and country codes are updated
relatively frequently, we don't attempt to list them here.  The valid
language codes are on the official home page for ISO 639,
<http://www.loc.gov/standards/iso639-2/>.  The country codes and the
official web site for ISO 3166 can be found via
<http://en.wikipedia.org/wiki/ISO_3166>.


File: texinfo.info,  Node: @documentencoding,  Prev: @documentlanguage,  Up: Internationalization

17.2 '@documentencoding ENC': Set Input Encoding
================================================

The '@documentencoding' command declares the input document encoding.
Write it on a line by itself, with a valid encoding specification
following, near the beginning of the file but after '@setfilename'
(*note @setfilename::):

     @documentencoding ENC

  At present, Texinfo supports only these encodings:

'US-ASCII'
     This has no particular effect, but it's included for completeness.

'UTF-8'
     The vast global character encoding, expressed in 8-bit bytes.

'ISO-8859-2'
'ISO-8859-1'
'ISO-8859-15'
     These specify the standard encodings for Western European (the
     first two) and Eastern European languages (the third),
     respectively.  ISO 8859-15 replaces some little-used characters
     from 8859-1 (e.g., precomposed fractions) with more commonly needed
     ones, such as the Euro symbol (Euro).

     A full description of the encodings is beyond our scope here; one
     useful reference is <http://czyborra.com/charsets/iso8859.html>.

'koi8-r'
     This is the commonly used encoding for the Russian language.

'koi8-u'
     This is the commonly used encoding for the Ukrainian language.

  Specifying an encoding ENC has the following effects:

  In Info output, a so-called 'Local Variables' section (*note
(emacs)File Variables::) is output including ENC.  This allows Info
readers to set the encoding appropriately.  It looks like this:

     Local Variables:
     coding: ENC
     End:

  Also, in Info and plain text output, unless the option
'--disable-encoding' is given to 'makeinfo', accent constructs and
special characters, such as '@'e', are output as the actual 8-bit or
UTF-8 character in the given encoding where possible.

  In HTML output, a '<meta>' tag is output, in the '<head>' section of
the HTML, that specifies ENC.  Web servers and browsers cooperate to use
this information so the correct encoding is used to display the page, if
supported by the system.  That looks like this:

     <meta http-equiv="Content-Type" content="text/html;
          charset=ENC">

  In XML and Docbook output, UTF-8 is always used for the output file,
since all XML processors are supposed to be able to process that
encoding.

  In TeX output, the characters which are supported in the standard
Computer Modern fonts are output accordingly.  (For example, this means
using constructed accents rather than precomposed glyphs.)  Using a
missing character generates a warning message, as does specifying an
unimplemented encoding.

  Although modern TeX systems support nearly every script in use in the
world, this wide-ranging support is not available in 'texinfo.tex', and
it's not feasible to duplicate or incorporate all that effort.  Our plan
to support other scripts is to create a LaTeX back-end to 'texi2any',
where the support is already present.


File: texinfo.info,  Node: Conditionals,  Next: Defining New Texinfo Commands,  Prev: Internationalization,  Up: Top

18 Conditionally Visible Text
*****************************

The "conditional commands" allow you to use different text for different
output formats, or for general conditions that you define.  For example,
you can use them to specify different text for the printed manual and
the Info output.

  The conditional commands comprise the following categories.

   * Commands specific to an output format (Info, TeX, HTML, ...).

   * Commands specific to any output format _excluding_ a given one
     (e.g., not Info, not TeX, ...).

   * 'Raw' formatter text for any output format, passed straight through
     with minimal (but not zero) interpretation of @-commands.

   * Format-independent variable substitutions, and testing if a
     variable is set or clear.

* Menu:

* Conditional Commands::        Text for a given format.
* Conditional Not Commands::    Text for any format other than a given one.
* Raw Formatter Commands::      Using raw formatter commands.
* Inline Conditionals::         Brace-delimited conditional text.
* @set @clear @value::          Variable tests and substitutions.
* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
* Conditional Nesting::         Using conditionals inside conditionals.


File: texinfo.info,  Node: Conditional Commands,  Next: Conditional Not Commands,  Up: Conditionals

18.1 Conditional Commands
=========================

Texinfo has an '@ifFORMAT' environment for each output format, to allow
conditional inclusion of text for a particular output format.

  '@ifinfo' begins segments of text that should be ignored by TeX when
it typesets the printed manual, and by 'makeinfo' when not producing
Info output.  The segment of text appears only in the Info file and, for
historical compatibility, the plain text output.

  The environments for the other formats are analogous, but without the
special historical case:

'@ifdocbook ... @end ifdocbook'
     Text to appear only in the Docbook output.

'@ifhtml ... @end ifhtml'
     Text to appear only in the HTML output.

'@ifplaintext ... @end ifplaintext'
     Text to appear only in the plain text output.

'@iftex ... @end iftex'
     Text to appear only in the printed manual.

'@ifxml ... @end ifxml'
     Text to appear only in the XML output.

  The '@if...' and '@end if...' commands must appear on lines by
themselves in your source file.  The newlines following the commands are
(more or less) treated as whitespace, so that the conditional text is
flowed normally into a surrounding paragraph.

  The '@if...' constructs are intended to conditionalize normal Texinfo
source; *note Raw Formatter Commands::, for using underlying format
commands directly.

  Here is an example showing all these conditionals:

     @iftex
     This text will appear only in the printed manual.
     @end iftex
     @ifinfo
     However, this text will appear only in Info and plain text.
     @end ifinfo
     @ifhtml
     And this text will only appear in HTML.
     @end ifhtml
     @ifplaintext
     Whereas this text will only appear in plain text.
     @end ifplaintext
     @ifxml
     Notwithstanding that this will only appear in XML.
     @end ifxml
     @ifdocbook
     Nevertheless, this will only appear in Docbook.
     @end ifdocbook

The preceding example produces the following line:

  However, this text will appear only in Info and plain text.

Notice that you only see one of the input lines, depending on which
version of the manual you are reading.

  In complex documents, you may want Texinfo to issue an error message
in some conditionals that should not ever be processed.  The
'@errormsg{TEXT}' command will do this; it takes one argument, the text
of the error message, which is expanded more or less as if it were Info
text.

  We mention '@errormsg{}' here even though it is not strictly related
to conditionals, since in practice it is most likely to be useful in
that context.  Technically, it can be used anywhere.  *Note External
Macro Processors::, for a caveat regarding the line numbers which
'@errormsg' emits in TeX.


File: texinfo.info,  Node: Conditional Not Commands,  Next: Raw Formatter Commands,  Prev: Conditional Commands,  Up: Conditionals

18.2 Conditional Not Commands
=============================

You can specify text to be included in any output format _other_ than a
given one with the '@ifnot...' environments:

     @ifnotdocbook ... @end ifnotdocbook
     @ifnothtml ... @end ifnothtml
     @ifnotinfo ... @end ifnotinfo
     @ifnotplaintext ... @end ifnotplaintext
     @ifnottex ... @end ifnottex
     @ifnotxml ... @end ifnotxml

The '@ifnot...' command and the '@end' command must appear on lines by
themselves in your actual source file.

  If the output file is being made in the given format, the region is
_ignored_.  Otherwise, it is included.

  There is one exception (for historical compatibility): '@ifnotinfo'
text is omitted for both Info and plain text output, not just Info.  To
specify text which appears only in Info and not in plain text, use
'@ifnotplaintext', like this:

     @ifinfo
     @ifnotplaintext
     This will be in Info, but not plain text.
     @end ifnotplaintext
     @end ifinfo

  The regions delimited by these commands are ordinary Texinfo source as
with '@iftex', not raw formatter source as with '@tex' (*note Raw
Formatter Commands::).


File: texinfo.info,  Node: Raw Formatter Commands,  Next: Inline Conditionals,  Prev: Conditional Not Commands,  Up: Conditionals

18.3 Raw Formatter Commands
===========================

The '@if...' conditionals just described must be used only with normal
Texinfo source.  For instance, most features of plain TeX will not work
within '@iftex'.  The purpose of '@if...' is to provide conditional
processing for Texinfo source, not provide access to underlying
formatting features.  For that, Texinfo provides so-called "raw
formatter commands".  They should only be used when truly required (most
documents do not need them).

  The first raw formatter command is '@tex'.  You can enter plain TeX
completely, and use '\' in the TeX commands, by delineating a region
with the '@tex' and '@end tex' commands.  All plain TeX commands and
category codes are restored within an '@tex' region.  The sole exception
is that the '@' character still introduces a command, so that '@end tex'
can be recognized.  Texinfo processors will not output material in such
a region, unless TeX output is being produced.

  In complex cases, you may wish to define new TeX macros within '@tex'.
You must use '\gdef' to do this, not '\def', because '@tex' regions are
processed in a TeX group.  If you need to make several definitions, you
may wish to set '\globaldefs=1' (its value will be restored to zero as
usual when the group ends at '@end tex', so it won't cause problems with
the rest of the document).

  As an example, here is a displayed equation written in plain TeX:

     @tex
     $$ \chi^2 = \sum_{i=1}^N
              \left (y_i - (a + b x_i)
              \over \sigma_i\right)^2 $$
     @end tex

The output of this example will appear only in a printed manual.  If you
are reading this in a format not generated by TeX, you will not see the
equation that appears in the printed manual.

  Analogously, you can use '@ifhtml ... @end ifhtml' to delimit Texinfo
source to be included in HTML output only, and '@html ... @end html' for
a region of raw HTML.

  Likewise, you can use '@ifxml ... @end ifxml' to delimit Texinfo
source to be included in XML output only, and '@xml ... @end xml' for a
region of raw XML.  Regions of raw text in other formats will also be
present in the XML output, but with protection of XML characters and
within corresponding elements.  For example, the raw HTML text:

     @html
     <br />
     @end html

will be included in the XML output as:

     <html>
     &lt;br /&gt;
     </html>

  Again likewise, you can use '@ifdocbook ... @end ifdocbook' to delimit
Texinfo source to be included in Docbook output only, and '@docbook ...
@end docbook' for a region of raw Docbook.

  The behavior of newlines in raw regions is unspecified.

  In all cases, in raw processing, '@' retains the same meaning as in
the remainder of the document.  Thus, the Texinfo processors recognize
and even execute, to some extent, the contents of the raw regions,
regardless of the final output format.  Therefore, specifying changes
that globally affect the document inside a raw region leads to
unpredictable and generally undesirable behavior.  For example, giving
the '@kbdinputstyle' command inside a raw region.

  The remedy is simple: don't do that.  Use the raw formatter commands
for their intended purpose, of providing material directly in the
underlying format.  When you simply want to give different Texinfo
specifications for different output formats, use the '@if...'
conditionals and stay in Texinfo syntax.


File: texinfo.info,  Node: Inline Conditionals,  Next: @set @clear @value,  Prev: Raw Formatter Commands,  Up: Conditionals

18.4 Inline Conditionals: '@inline', '@inlineraw'
=================================================

Texinfo provides two conditional commands with arguments given within
braces:

'@inlinefmt{FORMAT, TEXT}'
     Process the Texinfo TEXT if FORMAT output is being generated.

'@inlineraw{FORMAT, TEXT}'
     Similar, but for raw TEXT (*note Raw Formatter Commands::).

  For example,

     @inlinefmt{html, @emph{HTML-only text}}

is nearly equivalent to

     @ifhtml
     @emph{HTML-only text}
     @end ifhtml

except that no whitespace is added, as happens in the latter
(environment) case.

  In these commands, whitespace is ignored after the comma separating
the two arguments, as usual, but is _not_ ignored at the end of TEXT.

  In the case of '@inlineraw', to insert a literal at sign, left brace,
or right brace, you must use the alphabetic commands '@atchar{}' (*note
Inserting an Atsign::), and '@lbracechar{}' or '@rbracechar{}' (*note
Inserting Braces::), or the parsing will become confused.  (By the way,
it is not necessary to use '@comma{}', since these commands always have
exactly two arguments, so a ',' cannot be mistaken for an argument
separator.)


File: texinfo.info,  Node: @set @clear @value,  Next: Testing for Texinfo Commands,  Prev: Inline Conditionals,  Up: Conditionals

18.5 '@set', '@clear', and '@value'
===================================

You can direct the Texinfo formatting commands to format or ignore parts
of a Texinfo file with the '@set', '@clear', '@ifset', and '@ifclear'
commands.

  Here are brief descriptions of these commands, see the following
sections for more details:

'@set FLAG [VALUE]'
     Set the variable FLAG, to the optional VALUE if specified.

'@clear FLAG'
     Undefine the variable FLAG, whether or not it was previously
     defined.

'@ifset FLAG'
     If FLAG is set, text through the next '@end ifset' command is
     formatted.  If FLAG is clear, text through the following '@end
     ifset' command is ignored.

'@ifclear FLAG'
     If FLAG is set, text through the next '@end ifclear' command is
     ignored.  If FLAG is clear, text through the following '@end
     ifclear' command is formatted.

* Menu:

* @set @value::                 Expand a flag variable to a string.
* @ifset @ifclear::             Format a region if a flag is set.
* @value Example::              An easy way to update edition information.


File: texinfo.info,  Node: @set @value,  Next: @ifset @ifclear,  Up: @set @clear @value

18.5.1 '@set' and '@value'
--------------------------

You use the '@set' command to specify a value for a flag, which is later
expanded by the '@value' command.

  A "flag" (aka "variable") name is an identifier starting with an
alphanumeric, '-', or '_'.  Subsequent characters, if any, may not be
whitespace, '@', braces, angle brackets, or any of '~`^+|'; other
characters, such as '%', may work.  However, it is best to use only
letters and numerals in a flag name, not '-' or '_' or others--they will
work in some contexts, but not all, due to limitations in TeX.

  The value is the remainder of the input line, and can contain
anything.  However, unlike most other commands which take the rest of
the line as a value, '@set' need not appear at the beginning of a line.

  Write the '@set' command like this:

     @set foo This is a string.

This sets the value of the flag 'foo' to "This is a string.".

  The Texinfo formatters then replace an '@value{FLAG}' command with the
string to which FLAG is set.  Thus, when 'foo' is set as shown above,
the Texinfo formatters convert this:

     @value{foo}
to this:
     This is a string.

  You can write an '@value' command within a paragraph; but you must
write an '@set' command on a line of its own.

  If you write the '@set' command like this:

     @set foo

without specifying a string, the value of 'foo' is the empty string.

  If you clear a previously set flag with '@clear FLAG', a subsequent
'@value{flag}' command will report an error.

  For example, if you set 'foo' as follows:

     @set howmuch very, very, very

then the formatters transform

     It is a @value{howmuch} wet day.
into
     It is a very, very, very wet day.

  If you write

     @clear howmuch

then the formatters transform

     It is a @value{howmuch} wet day.
into
     It is a {No value for "howmuch"} wet day.

  '@value' cannot be reliably used as the argument to an accent command
(*note Inserting Accents::).  For example, this fails:

     @set myletter a
     @'@value{myletter}    


File: texinfo.info,  Node: @ifset @ifclear,  Next: @value Example,  Prev: @set @value,  Up: @set @clear @value

18.5.2 '@ifset' and '@ifclear'
------------------------------

When a FLAG is set, the Texinfo formatting commands format text between
subsequent pairs of '@ifset FLAG' and '@end ifset' commands.  When the
FLAG is cleared, the Texinfo formatting commands do _not_ format the
text.  '@ifclear' operates analogously.

  Write the conditionally formatted text between '@ifset FLAG' and '@end
ifset' commands, like this:

     @ifset FLAG
     CONDITIONAL-TEXT
     @end ifset

  For example, you can create one document that has two variants, such
as a manual for a 'large' and 'small' model:

     You can use this machine to dig up shrubs
     without hurting them.

     @set large

     @ifset large
     It can also dig up fully grown trees.
     @end ifset

     Remember to replant promptly ...

In the example, the formatting commands will format the text between
'@ifset large' and '@end ifset' because the 'large' flag is set.

  When FLAG is cleared, the Texinfo formatting commands do _not_ format
the text between '@ifset FLAG' and '@end ifset'; that text is ignored
and does not appear in either printed or Info output.

  For example, if you clear the flag of the preceding example by writing
an '@clear large' command after the '@set large' command (but before the
conditional text), then the Texinfo formatting commands ignore the text
between the '@ifset large' and '@end ifset' commands.  In the formatted
output, that text does not appear; in both printed and Info output, you
see only the lines that say, "You can use this machine to dig up shrubs
without hurting them.  Remember to replant promptly ...".

  If a flag is cleared with an '@clear FLAG' command, then the
formatting commands format text between subsequent pairs of '@ifclear'
and '@end ifclear' commands.  But if the flag is set with '@set FLAG',
then the formatting commands do _not_ format text between an '@ifclear'
and an '@end ifclear' command; rather, they ignore that text.  An
'@ifclear' command looks like this:

     @ifclear FLAG


File: texinfo.info,  Node: @value Example,  Prev: @ifset @ifclear,  Up: @set @clear @value

18.5.3 '@value' Example
-----------------------

You can use the '@value' command to minimize the number of places you
need to change when you record an update to a manual.  *Note GNU Sample
Texts::, for the full text of an example of using this to work with
Automake distributions.

  This example is adapted from *note (make)Top::.

  1. Set the flags:

          @set EDITION 0.35 Beta
          @set VERSION 3.63 Beta
          @set UPDATED 14 August 1992
          @set UPDATE-MONTH August 1992

  2. Write text for the '@copying' section (*note @copying::):

          @copying
          This is Edition @value{EDITION},
          last updated @value{UPDATED},
          of @cite{The GNU Make Manual},
          for @code{make}, version @value{VERSION}.

          Copyright ...

          Permission is granted ...
          @end copying

  3. Write text for the title page, for people reading the printed
     manual:

          @titlepage
          @title GNU Make
          @subtitle A Program for Directing Recompilation
          @subtitle Edition @value{EDITION}, ...
          @subtitle @value{UPDATE-MONTH}
          @page
          @insertcopying
          ...
          @end titlepage

     (On a printed cover, a date listing the month and the year looks
     less fussy than a date listing the day as well as the month and
     year.)

  4. Write text for the Top node, for people reading the Info file:

          @ifnottex
          @node Top
          @top Make

          @insertcopying
          ...
          @end ifnottex

     After you format the manual, the '@value' constructs have been
     expanded, so the output contains text like this:

          This is Edition 0.35 Beta, last updated 14 August 1992,
          of `The GNU Make Manual', for `make', Version 3.63 Beta.

  When you update the manual, you change only the values of the flags;
you do not need to edit the three sections.


File: texinfo.info,  Node: Testing for Texinfo Commands,  Next: Conditional Nesting,  Prev: @set @clear @value,  Up: Conditionals

18.6 Testing for Texinfo Commands: '@ifcommanddefined', '@ifcommandnotdefined'
==============================================================================

Occasionally, you may want to arrange for your manual to test if a given
Texinfo command is available and (presumably) do some sort of fallback
formatting if not.  There are conditionals '@ifcommanddefined' and
'@ifcommandnotdefined' to do this.  For example:

     @ifcommanddefined node
     Good, @samp{@@node} is defined.
     @end ifcommanddefined

will output the expected 'Good, '@node' is defined.'.

  This conditional will also consider true any new commands defined by
the document via '@macro', '@alias', '@definfoenclose', and
'@def(code)index' (*note Defining New Texinfo Commands::).  Caveat: the
TeX implementation reports internal TeX commands, in addition to all the
Texinfo commands, as being "defined"; the 'makeinfo' implementation is
reliable in this regard, however.

  You can check the 'NEWS' file in the Texinfo source distribution and
linked from the Texinfo home page
(<http://www.gnu.org/software/texinfo>) to see when a particular command
was added.

  These command-checking conditionals themselves were added in
Texinfo 5.0, released in 2013--decades after Texinfo's inception.  In
order to test if they themselves are available, the predefined flag
'txicommandconditionals' can be tested, like this:

     @ifset txicommandconditionals
     @ifcommandnotdefined foobarnode
     (Good, @foobarnode is not defined.)
     @end ifcommandnotdefined
     @end ifset

  Since flags (see the previous section) were added early in the
existence of Texinfo, there is no problem with assuming they are
available.

  We recommend avoiding these tests whenever possible--which is usually
the case.  For many software packages, it is reasonable for all
developers to have a given version of Texinfo (or newer) installed, and
thus no reason to worry about older versions.  (It is simple to download
and install the Texinfo source; it does not have any problematic
dependencies.)

  The issue of Texinfo versions does not generally arise for end-users.
With properly distributed packages, users need not process the Texinfo
manual simply to build and install the package; they can use
preformatted Info (or other) output files.  This is desirable in
general, to avoid unnecessary dependencies between packages (*note
(standard)Releases::).


File: texinfo.info,  Node: Conditional Nesting,  Prev: Testing for Texinfo Commands,  Up: Conditionals

18.7 Conditional Nesting
========================

Conditionals can be nested; however, the details are a little tricky.
The difficulty comes with failing conditionals, such as '@ifhtml' when
HTML is not being produced, where the included text is to be ignored.
However, it is not to be _completely_ ignored, since it is useful to
have one '@ifset' inside another, for example--that is a way to include
text only if two conditions are met.  Here's an example:

     @ifset somevar
     @ifset anothervar
     Both somevar and anothervar are set.
     @end ifset
     @ifclear anothervar
     Somevar is set, anothervar is not.
     @end ifclear
     @end ifset

  Technically, Texinfo requires that for a failing conditional, the
ignored text must be properly nested with respect to that failing
conditional.  Unfortunately, it's not always feasible to check that
_all_ conditionals are properly nested, because then the processors
could have to fully interpret the ignored text, which defeats the
purpose of the command.  Here's an example illustrating these rules:

     @ifset a
     @ifset b
     @ifclear ok  - ok, ignored
     @end junky   - ok, ignored
     @end ifset
     @c WRONG - missing @end ifset.

  Finally, as mentioned above, all conditional commands must be on lines
by themselves, with no text (even spaces) before or after.  Otherwise,
the processors cannot reliably determine which commands to consider for
nesting purposes.


File: texinfo.info,  Node: Defining New Texinfo Commands,  Next: Include Files,  Prev: Conditionals,  Up: Top

19 Defining New Texinfo Commands
********************************

Texinfo provides several ways to define new commands:

   * A Texinfo "macro" allows you to define a new Texinfo command as any
     sequence of text and/or existing commands (including other macros).
     The macro can have any number of "parameters"--text you supply each
     time you use the macro.

     Incidentally, these macros have nothing to do with the '@defmac'
     command, which is for documenting macros in the subject area of the
     manual (*note Def Cmd Template::).

   * '@alias' is a convenient way to define a new name for an existing
     command.

   * '@definfoenclose' allows you to define new commands with customized
     output for all non-TeX output formats.

  Most generally of all, not just for defining new commands, it is
possible to invoke an external macro processor and have Texinfo
recognize so-called '#line' directives for error reporting.

  If you want to do simple text substitution, '@set' and '@value' is the
simplest approach (*note @set @clear @value::).

* Menu:

* Defining Macros::             Defining and undefining new commands.
* Invoking Macros::             Using a macro, once you've defined it.
* Macro Details::               Limitations of Texinfo macros.
* @alias::                      Command aliases.
* @definfoenclose::             Customized highlighting.
* External Macro Processors::   '#line' directives.


File: texinfo.info,  Node: Defining Macros,  Next: Invoking Macros,  Up: Defining New Texinfo Commands

19.1 Defining Macros
====================

You use the Texinfo '@macro' command to define a macro, like this:

     @macro MACRONAME{PARAM1, PARAM2, ...}
     TEXT ... \PARAM1\ ...
     @end macro

  The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
when the macro is subsequently used in the document (described in the
next section).

  For a macro to work consistently with TeX, MACRONAME must consist
entirely of letters: no digits, hyphens, underscores, or other special
characters.  So, we recommend using only letters.  However, 'makeinfo'
will accept anything consisting of alphanumerics, and (except as the
first character) '-'.  The '_' character is excluded so that macros can
be called inside '@math' without a following space (*note Inserting
Math::).

  If a macro needs no parameters, you can define it either with an empty
list ('@macro foo {}') or with no braces at all ('@macro foo').

  The definition or "body" of the macro can contain most Texinfo
commands, including macro invocations.  However, a macro definition that
defines another macro does not work in TeX due to limitations in the
design of '@macro'.

  In the macro body, instances of a parameter name surrounded by
backslashes, as in '\PARAM1\' in the example above, are replaced by the
corresponding argument from the macro invocation.  You can use parameter
names any number of times in the body, including zero.

  To get a single '\' in the macro expansion, use '\\'.  Any other use
of '\' in the body yields a warning.

  The newline characters after the '@macro' line and before the '@end
macro' line are ignored, that is, not included in the macro body.  All
other whitespace is treated according to the usual Texinfo rules.
However, there are still undesirable and unpredictable interactions
between newlines, macros, and commands which are line-delimited, as
warned about below (*note Macro Details::).

  To allow a macro to be used recursively, that is, in an argument to a
call to itself, you must define it with '@rmacro', like this:

     @rmacro rmac {arg}
     a\arg\b
     @end rmacro
     ...
     @rmac{1@rmac{text}2}

  This produces the output 'a1atextb2b'.  With '@macro' instead of
'@rmacro', an error message is given.

  You can undefine a macro FOO with '@unmacro FOO'.  It is not an error
to undefine a macro that is already undefined.  For example:

     @unmacro foo


File: texinfo.info,  Node: Invoking Macros,  Next: Macro Details,  Prev: Defining Macros,  Up: Defining New Texinfo Commands

19.2 Invoking Macros
====================

After a macro is defined (see the previous section), you can "invoke"
(use) it in your document like this:

     @MACRONAME {ARG1, ARG2, ...}

and the result will be more or less as if you typed the body of
MACRONAME at that spot.  For example:

     @macro foo {p, q}
     Together: \p\ & \q\.
     @end macro
     @foo{a, b}

produces:

     Together: a & b.

  Thus, the arguments and parameters are separated by commas and
delimited by braces; any whitespace after (but not before) a comma is
ignored.  The braces are required in the invocation even when the macro
takes no arguments, consistent with other Texinfo commands.  For
example:

     @macro argless {}
     No arguments here.
     @end macro
     @argless{}

produces:

     No arguments here.

  Passing macro arguments containing commas requires special care, since
commas also separate the arguments.  To include a comma character in an
argument, the most reliable method is to use the '@comma{}' command.
For 'makeinfo', you can also prepend a backslash character, as in '\,',
but this does not work with TeX.

  It's not always necessary to worry about commas.  To facilitate use of
macros, 'makeinfo' implements two rules for "automatic quoting" in some
circumstances:

  1. If a macro takes only one argument, all commas in its invocation
     are quoted by default.  For example:

          @macro TRYME{text}
          @strong{TRYME: \text\}
          @end macro

          @TRYME{A nice feature, though it can be dangerous.}

     will produce the following output

          *TRYME: A nice feature, though it can be dangerous.*

     And indeed, it can.  Namely, 'makeinfo' does not control the number
     of arguments passed to one-argument macros, so be careful when you
     invoke them.

  2. If a macro invocation includes another command (including a
     recursive invocation of itself), any commas in the nested command
     invocation(s) are quoted by default.  For example, in

          @say{@strong{Yes, I do}, person one}

     the comma after 'Yes' is implicitly quoted.  Here's another
     example, with a recursive macro:

          @rmacro cat{a,b}
          \a\\b\
          @end rmacro

          @cat{@cat{foo, bar}, baz}

     will produce the string 'foobarbaz'.

  3. Otherwise, a comma should be explicitly quoted, as above, for it to
     be treated as a part of an argument.

  In addition to the comma, characters that need to be quoted in macro
arguments are curly braces and backslash.  For example:

     @MACNAME {\\\{\}\,}

will pass the (almost certainly error-producing) argument '\{},' to
MACNAME.

  Unfortunately, this has not been reliably implemented in TeX.  When
macros are used in the argument to other commands, for example, errors
or incorrect output (the '\' "escape" being included literally) are
likely to result.

  If a macro is defined to take exactly one argument, it can (but need
not) be invoked without any braces; then the entire rest of the line
after the macro name is used as the argument.  (Braces around the
argument(s) are required in all other cases, i.e., if the macro takes
either zero or more than one argument.)  For example:

     @macro bar {p}
     Twice: \p\ & \p\.
     @end macro
     @bar aah

produces:

     Twice: aah & aah.

  Likewise, if a macro is defined to take exactly one argument, and is
invoked with braces, the braced text is passed as the argument, also
regardless of commas.  For example:

     @macro bar {p}
     Twice: \p\ & \p\.
     @end macro
     @bar{a,b}

produces:

     Twice: a,b & a,b.

  If a macro is defined to take more than one argument, but is called
with only one (in braces), the remaining arguments are set to the empty
string, and no error is given.  For example:

     @macro addtwo {p, q}
     Both: \p\\q\.
     @end macro
     @addtwo{a}

produces simply:

     Both: a.


File: texinfo.info,  Node: Macro Details,  Next: @alias,  Prev: Invoking Macros,  Up: Defining New Texinfo Commands

19.3 Macro Details and Caveats
==============================

By design, macro expansion does not happen in the following contexts in
'makeinfo':

   * '@macro' and '@unmacro' lines;

   * '@if...' lines, including '@ifset' and similar;

   * '@set', '@clear', '@value';

   * '@clickstyle' lines;

   * '@end' lines.

Unfortunately, TeX may do some expansion in these situations, possibly
yielding errors.

  Also, quite a few macro-related constructs cause problems with TeX;
some of the caveats are listed below.  Thus, if you get macro-related
errors when producing the printed version of a manual, you might try
expanding the macros with 'makeinfo' by invoking 'texi2dvi' with the
'-E' option (*note Format with texi2dvi::).  Or, more reliably, eschew
Texinfo macros altogether and use a language designed for macro
processing, such as M4 (*note External Macro Processors::).

   * As mentioned earlier, macro names must consist entirely of letters.

   * It is not advisable to redefine any TeX primitive, plain, or
     Texinfo command name as a macro.  Unfortunately this is a large and
     open-ended set of names, and the possible resulting errors are
     unpredictable.

   * All macros are expanded inside at least one TeX group.

   * Macro arguments cannot cross lines.

   * Macros containing a command which must be on a line by itself, such
     as a conditional, cannot be invoked in the middle of a line.
     Similarly, macros containing line-oriented commands or text, such
     as '@example' environments, may behave unpredictably in TeX.

   * White space is ignored at the beginnings of lines.

   * Macros can't be reliably used in the argument to accent commands
     (*note Inserting Accents::).

   * The backslash escape for commas in macro arguments does not work;
     '@comma{}' must be used.

   * As a consequence, if a macro takes two or more arguments, and you
     want to pass an argument with the Texinfo command '@,' (to produce
     a cedilla, *note Inserting Accents::), you have to use '@value' or
     another work-around.  Otherwise, TeX takes the comma as separating
     the arguments.  Example:

          @macro mactwo{argfirst, argsecond}
          \argfirst\+\argsecond\.
          @end macro
          @set fc Fran@,cois
          @mactwo{@value{fc}}

     produces:

          Franc,ois+.

     The natural-seeming '@mactwo{Fran@,cois}' passes the two arguments
     'Fran@' and 'cois' to the macro, and nothing good results.  And, as
     just mentioned, although the comma can be escaped with a backslash
     for 'makeinfo' ('@\,'), that doesn't work in TeX, so there is no
     other solution.

   * It is usually best to avoid comments inside macro definitions, but
     see the next item.

   * In general, the interaction of newlines in the macro definitions
     and invocations depends on the precise commands and context,
     notwithstanding the previous statements.  You may be able to work
     around some problems with judicious use of '@c'.  Suppose you
     define a macro that is always used on a line by itself:

          @macro linemac
          @cindex whatever @c
          @end macro
          ...
          foo
          @linemac
          bar

     Without the '@c', there will be a unwanted blank line between the
     '@cindex whatever' and the 'bar' (one newline comes from the macro
     definition, one from after the invocation), causing an unwanted
     paragraph break.

     On the other hand, you wouldn't want the '@c' if the macro was
     sometimes invoked in the middle of a line (the text after the
     invocation would be treated as a comment).

   * In general, you can't arbitrarily substitute a macro (or '@value')
     call for Texinfo command arguments, even when the text is the same.
     Texinfo is not M4 (or even plain TeX).  It might work with some
     commands, it fails with others.  Best not to do it at all.  For
     instance, this fails:

          @macro offmacro
          off
          @end macro
          @headings @offmacro

     This looks equivalent to '@headings off', but for TeXnical reasons,
     it fails with a mysterious error message (namely, 'Paragraph ended
     before @headings was complete').

   * Macros cannot define macros in the natural way.  To do this, you
     must use conditionals and raw TeX.  For example:

          @ifnottex
          @macro ctor {name, arg}
          @macro \name\
          something involving \arg\ somehow
          @end macro
          @end macro
          @end ifnottex
          @tex
          \gdef\ctor#1{\ctorx#1,}
          \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}}
          @end tex

  The 'makeinfo' implementation also has the following limitations (by
design):

   * '@verbatim' and macros do not mix; for instance, you can't start a
     verbatim block inside a macro and end it outside (*note
     @verbatim::).  Starting any environment inside a macro and ending
     it outside may or may not work, for that matter.

   * Macros that completely define macros are ok, but it's not possible
     to have incompletely nested macro definitions.  That is, '@macro'
     and '@end macro' (likewise for '@rmacro') must be correctly paired.
     For example, you cannot start a macro definition within a macro,
     and then end that nested definition outside the macro.

  In the 'makeinfo' implementation before Texinfo 5.0, ends of lines
from expansion of an '@macro' definition did not end an @-command
line-delimited argument ('@chapter', '@center', etc.).  This is no
longer the case.  For example:

     @macro twolines{}
     aaa
     bbb
     @end macro
     @center @twolines{}

  In the current 'makeinfo', this is equivalent to:

     @center aaa
     bbb

with just 'aaa' as the argument to '@center'.  In the earlier
implementation, it would have been parsed as this:

     @center aaa bbb


File: texinfo.info,  Node: @alias,  Next: @definfoenclose,  Prev: Macro Details,  Up: Defining New Texinfo Commands

19.4 '@alias NEW=EXISTING'
==========================

The '@alias' command defines a new command to be just like an existing
one.  This is useful for defining additional markup names, thus
preserving additional semantic information in the input even though the
output result may be the same.

  Write the '@alias' command on a line by itself, followed by the new
command name, an equals sign, and the existing command name.  Whitespace
around the equals sign is optional and ignored if present.  Thus:

     @alias NEW = EXISTING

  For example, if your document contains citations for both books and
some other media (movies, for example), you might like to define a macro
'@moviecite{}' that does the same thing as an ordinary '@cite{}' but
conveys the extra semantic information as well.  You'd do this as
follows:

     @alias moviecite = cite

  Macros do not always have the same effect as aliases, due to vagaries
of argument parsing.  Also, aliases are much simpler to define than
macros.  So the command is not redundant.

  Unfortunately, it's not possible to alias Texinfo environments; for
example, '@alias lang=example' is an error.

  Aliases must not be recursive, directly or indirectly.

  It is not advisable to redefine any TeX primitive, plain TeX, or
Texinfo command name as an alias.  Unfortunately this is a very large
set of names, and the possible resulting errors from TeX are
unpredictable.

  'makeinfo' will accept the same identifiers for aliases as it does for
macro names, that is, alphanumerics and (except as the first character)
'-'.


File: texinfo.info,  Node: @definfoenclose,  Next: External Macro Processors,  Prev: @alias,  Up: Defining New Texinfo Commands

19.5 '@definfoenclose': Customized Highlighting
===============================================

An '@definfoenclose' command may be used to define a highlighting
command for all the non-TeX output formats.  A command defined using
'@definfoenclose' marks text by enclosing it in strings that precede and
follow the text.  You can use this to get closer control of your output.

  Presumably, if you define a command with '@definfoenclose', you will
create a corresponding command for TeX, either in 'texinfo.tex',
'texinfo.cnf', or within an '@iftex' of '@tex' in your document.

  Write an '@definfoenclose' command at the beginning of a line followed
by three comma-separated arguments.  The first argument to
'@definfoenclose' is the @-command name (without the '@'); the second
argument is the start delimiter string; and the third argument is the
end delimiter string.  The latter two arguments enclose the highlighted
text in the output.

  A delimiter string may contain spaces.  Neither the start nor end
delimiter is required.  If you do not want a start delimiter but do want
an end delimiter, you must follow the command name with two commas in a
row; otherwise, the end delimiter string you intended will naturally be
(mis)interpreted as the start delimiter string.

  If you do an '@definfoenclose' on the name of a predefined command
(such as '@emph', '@strong', '@t', or '@i'), the enclosure definition
will override the built-in definition.  We don't recommend this.

  An enclosure command defined this way takes one argument in braces,
since it is intended for new markup commands (*note Marking Text::).

  For example, you can write:

     @definfoenclose phoo,//,\\

near the beginning of a Texinfo file to define '@phoo' as an Info
formatting command that inserts '//' before and '\\' after the argument
to '@phoo'.  You can then write '@phoo{bar}' wherever you want '//bar\\'
highlighted in Info.

  For TeX formatting, you could write

     @iftex
     @global@let@phoo=@i
     @end iftex

to define '@phoo' as a command that causes TeX to typeset the argument
to '@phoo' in italics.

  Each definition applies to its own formatter: one for TeX, the other
for everything else.  The raw TeX commands need to be in '@iftex'.
'@definfoenclose' command need not be within '@ifinfo', unless you want
to use different definitions for different output formats.

  Here is another example: write

     @definfoenclose headword, , :

near the beginning of the file, to define '@headword' as an Info
formatting command that inserts nothing before and a colon after the
argument to '@headword'.

  '@definfoenclose' definitions must not be recursive, directly or
indirectly.


File: texinfo.info,  Node: External Macro Processors,  Prev: @definfoenclose,  Up: Defining New Texinfo Commands

19.6 External Macro Processors: Line Directives
===============================================

Texinfo macros (and its other text substitution facilities) work fine in
straightforward cases.  If your document needs unusually complex
processing, however, their fragility and limitations can be a problem.
In this case, you may want to use a different macro processor
altogether, such as M4 (*note (m4)Top::) or CPP (*note (cpp)Top::).

  With one exception, Texinfo does not need to know whether its input is
"original" source or preprocessed from some other source file.
Therefore, you can arrange your build system to invoke whatever programs
you like to handle macro expansion or other preprocessing needs.
Texinfo does not offer built-in support for any particular preprocessor,
since no one program seemed likely to suffice for the requirements of
all documents.

  The one exception is line numbers in error messages.  In that case,
the line number should refer to the original source file, whatever it
may be.  There's a well-known mechanism for this: the so-called '#line'
directive.  Texinfo supports this.

* Menu:

* #line Directive::
* TeX: #line and TeX.
* Syntax: #line Syntax Details.


File: texinfo.info,  Node: #line Directive,  Next: #line and TeX,  Up: External Macro Processors

19.6.1 '#line' Directive
------------------------

An input line such as this:

     #line 100 "foo.ptexi"

indicates that the next line was line 100 of the file 'foo.ptexi', and
so that's what an error message should refer to.  Both M4 (*note
(m4)Preprocessor features::) and CPP (*note (cpp)Line Control::, and
*note (cpp)Preprocessor Output::) can generate such lines.

  The 'makeinfo' program recognizes these lines by default, except
within '@verbatim' blocks (*note @verbatim::.  Their recognition can be
turned off completely with 'CPP_LINE_DIRECTIVES' (*note Other
Customization Variables::), though there is normally no reason to do so.

  For those few programs (M4, CPP, Texinfo) which need to document
'#line' directives and therefore have examples which would otherwise
match the pattern, the command '@hashchar{}' can be used (*note
Inserting a Hashsign::).  The example line above looks like this in the
source for this manual:

     @hashchar{}line 100 "foo.ptexi"

  The '@hashchar' command was added to Texinfo in 2013.  If you don't
want to rely on it, you can also use '@set' and '@value' to insert the
literal '#':

     @set hash #
     @value{hash}line 1 "example.c"

  Or, if suitable, an '@verbatim' environment can be used instead of
'@example'.  As mentioned above, '#line'-recognition is disabled inside
verbatim blocks.


File: texinfo.info,  Node: #line and TeX,  Next: #line Syntax Details,  Prev: #line Directive,  Up: External Macro Processors

19.6.2 '#line' and TeX
----------------------

As mentioned, 'makeinfo' recognizes the '#line' directives described in
the previous section.  However, 'texinfo.tex' does not and cannot.
Therefore, such a line will be incorrectly typeset verbatim if TeX sees
it.  The solution is to use 'makeinfo''s macro expansion options before
running TeX.  There are three approaches:

   * If you run 'texi2dvi' or its variants (*note Format with
     texi2dvi::), you can pass '-E' and 'texi2dvi' will run 'makeinfo'
     first to expand macros and eliminate '#line'.

   * If you run 'makeinfo' or its variants (*note Generic Translator
     texi2any::), you can specify '--no-ifinfo --iftex -E somefile.out',
     and then give 'somefile.out' to 'texi2dvi' in a separate command.

   * Or you can run 'makeinfo --dvi --Xopt -E'.  (Or '--pdf' instead of
     '--dvi'.)  'makeinfo' will then call 'texi2dvi -E'.

  One last caveat regarding use with TeX: since the '#line' directives
are not recognized, the line numbers emitted by the '@errormsg{}'
command (*note Conditional Commands::), or by TeX itself, are the
(incorrect) line numbers from the derived file which TeX is reading,
rather than the preprocessor-specified line numbers.  This is another
example of why we recommend running 'makeinfo' for the best diagnostics
(*note makeinfo Advantages::).


File: texinfo.info,  Node: #line Syntax Details,  Prev: #line and TeX,  Up: External Macro Processors

19.6.3 '#line' Syntax Details
-----------------------------

Syntax details for the '#line' directive: the '#' character can be
preceded or followed by whitespace, the word 'line' is optional, and the
file name can be followed by a whitespace-separated list of integers
(these are so-called "flags" output by CPP in some cases).  For those
who like to know the gory details, the actual (Perl) regular expression
which is matched is this:

     /^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/

  As far as we've been able to tell, the trailing integer flags only
occur in conjunction with a filename, so that is reflected in the
regular expression.

  As an example, the following is a syntactically valid '#line'
directive, meaning line 1 of '/usr/include/stdio.h':

     # 1 "/usr/include/stdio.h" 2 3 4

  Unfortunately, the quoted filename ('"..."') has to be optional,
because M4 (especially) can often generate '#line' directives within a
single file.  Since the 'line' is also optional, the result is that
lines might match which you wouldn't expect, e.g.,

     # 1

  The possible solutions are described above (*note #line Directive::).


File: texinfo.info,  Node: Include Files,  Next: Hardcopy,  Prev: Defining New Texinfo Commands,  Up: Top

20 Include Files
****************

When a Texinfo processor sees an '@include' command in a Texinfo file,
it processes the contents of the file named by the '@include' and
incorporates them into the output files being created.  Include files
thus let you keep a single large document as a collection of
conveniently small parts.

* Menu:

* Using Include Files::         How to use the '@include' command.
* texinfo-multiple-files-update:: How to create and update nodes and
                                     menus when using included files.
* Include Files Requirements::  'texinfo-multiple-files-update' needs.
* Sample Include File::         A sample outer file with included files
                                     within it; and a sample included file.
* Include Files Evolution::     How use of the '@include' command
                                     has changed over time.


File: texinfo.info,  Node: Using Include Files,  Next: texinfo-multiple-files-update,  Up: Include Files

20.1 How to Use Include Files
=============================

To include another file within a Texinfo file, write the '@include'
command at the beginning of a line and follow it on the same line by the
name of a file to be included.  For example:

     @include buffers.texi

  @-commands are expanded in file names.  The one most likely to be
useful is '@value' (*note @set @value::), and even then only in
complicated situations.

  An included file should simply be a segment of text that you expect to
be included as is into the overall or "outer" Texinfo file; it should
not contain the standard beginning and end parts of a Texinfo file.  In
particular, you should not start an included file with a line saying
'\input texinfo'; if you do, that text is inserted into the output file
literally.  Likewise, you should not end an included file with an '@bye'
command; nothing after '@bye' is formatted.

  In the long-ago past, you were required to write an '@setfilename'
line at the beginning of an included file, but no longer.  Now, it does
not matter whether you write such a line.  If an '@setfilename' line
exists in an included file, it is ignored.


File: texinfo.info,  Node: texinfo-multiple-files-update,  Next: Include Files Requirements,  Prev: Using Include Files,  Up: Include Files

20.2 'texinfo-multiple-files-update'
====================================

GNU Emacs Texinfo mode provides the 'texinfo-multiple-files-update'
command.  This command creates or updates 'Next', 'Previous', and 'Up'
pointers of included files as well as those in the outer or overall
Texinfo file, and it creates or updates a main menu in the outer file.
Depending on whether you call it with optional arguments, the command
updates only the pointers in the first '@node' line of the included
files or all of them:

'M-x texinfo-multiple-files-update'
     Called without any arguments:

        - Create or update the 'Next', 'Previous', and 'Up' pointers of
          the first '@node' line in each file included in an outer or
          overall Texinfo file.

        - Create or update the 'Top' level node pointers of the outer or
          overall file.

        - Create or update a main menu in the outer file.

'C-u M-x texinfo-multiple-files-update'
     Called with 'C-u' as a prefix argument:

        - Create or update pointers in the first '@node' line in each
          included file.

        - Create or update the 'Top' level node pointers of the outer
          file.

        - Create and insert a master menu in the outer file.  The master
          menu is made from all the menus in all the included files.

'C-u 8 M-x texinfo-multiple-files-update'
     Called with a numeric prefix argument, such as 'C-u 8':

        - Create or update *all* the 'Next', 'Previous', and 'Up'
          pointers of all the included files.

        - Create or update *all* the menus of all the included files.

        - Create or update the 'Top' level node pointers of the outer or
          overall file.

        - And then create a master menu in the outer file.  This is
          similar to invoking 'texinfo-master-menu' with an argument
          when you are working with just one file.

  Note the use of the prefix argument in interactive use: with a regular
prefix argument, just 'C-u', the 'texinfo-multiple-files-update' command
inserts a master menu; with a numeric prefix argument, such as 'C-u 8',
the command updates *every* pointer and menu in *all* the files and then
inserts a master menu.


File: texinfo.info,  Node: Include Files Requirements,  Next: Sample Include File,  Prev: texinfo-multiple-files-update,  Up: Include Files

20.3 Include Files Requirements
===============================

If you plan to use the 'texinfo-multiple-files-update' command, the
outer Texinfo file that lists included files within it should contain
nothing but the beginning and end parts of a Texinfo file, and a number
of '@include' commands listing the included files.  It should not even
include indices, which should be listed in an included file of their
own.

  Moreover, each of the included files must contain exactly one highest
level node (conventionally, '@chapter' or equivalent), and this node
must be the first node in the included file.  Furthermore, each of these
highest level nodes in each included file must be at the same
hierarchical level in the file structure.  Usually, each is an
'@chapter', an '@appendix', or an '@unnumbered' node.  Thus, normally,
each included file contains one, and only one, chapter or
equivalent-level node.

  The outer file should contain only _one_ node, the 'Top' node.  It
should _not_ contain any nodes besides the single 'Top' node.  The
'texinfo-multiple-files-update' command will not process them.


File: texinfo.info,  Node: Sample Include File,  Next: Include Files Evolution,  Prev: Include Files Requirements,  Up: Include Files

20.4 Sample File with '@include'
================================

Here is an example of an outer Texinfo file with '@include' files within
it before running 'texinfo-multiple-files-update', which would insert a
main or master menu:

     \input texinfo @c -*-texinfo-*-
     @setfilename include-example.info
     @settitle Include Example

     ... *Note Sample Texinfo Files::, for
     examples of the rest of the frontmatter ...

     @ifnottex
     @node Top
     @top Include Example
     @end ifnottex

     @include foo.texinfo
     @include bar.texinfo
     @include concept-index.texinfo
     @bye

  An included file, such as 'foo.texinfo', might look like this:

     @node First
     @chapter First Chapter

     Contents of first chapter ...

  The full contents of 'concept-index.texinfo' might be as simple as
this:

     @node Concept Index
     @unnumbered Concept Index

     @printindex cp

  The outer Texinfo source file for 'The GNU Emacs Lisp Reference
Manual' is named 'elisp.texi'.  This outer file contains a master menu
with 417 entries and a list of 41 '@include' files.


File: texinfo.info,  Node: Include Files Evolution,  Prev: Sample Include File,  Up: Include Files

20.5 Evolution of Include Files
===============================

When Info was first created, it was customary to create many small Info
files on one subject.  Each Info file was formatted from its own Texinfo
source file.  This custom meant that Emacs did not need to make a large
buffer to hold the whole of a large Info file when someone wanted
information; instead, Emacs allocated just enough memory for the small
Info file that contained the particular information sought.  This way,
Emacs could avoid wasting memory.

  References from one file to another were made by referring to the file
name as well as the node name.  (*Note Referring to Other Info Files:
Other Info Files.  Also, see *note '@xref' with Four and Five Arguments:
Four and Five Arguments.)

  Include files were designed primarily as a way to create a single,
large printed manual out of several smaller Info files.  In a printed
manual, all the references were within the same document, so TeX could
automatically determine the references' page numbers.  The Info
formatting commands used include files only for creating joint indices;
each of the individual Texinfo files had to be formatted for Info
individually.  (Each, therefore, required its own '@setfilename' line.)

  However, because large Info files are now split automatically, it is
no longer necessary to keep them small.

  Nowadays, multiple Texinfo files are used mostly for large documents,
such as 'The GNU Emacs Lisp Reference Manual', and for projects in which
several different people write different sections of a document
simultaneously.

  In addition, the Info formatting commands have been extended to work
with the '@include' command so as to create a single large Info file
that is split into smaller files if necessary.  This means that you can
write menus and cross references without naming the different Texinfo
files.


File: texinfo.info,  Node: Hardcopy,  Next: Generic Translator texi2any,  Prev: Include Files,  Up: Top

21 Formatting and Printing Hardcopy
***********************************

Running the 'texi2dvi' or 'texi2pdf' command is the simplest way to
create printable output.  These commands are installed as part of the
Texinfo package.

  More specifically, three major shell commands are used to print
formatted output from a Texinfo manual: one converts the Texinfo source
into something printable, a second sorts indices, and a third actually
prints the formatted document.  When you use the shell commands, you can
either work directly in the operating system shell or work within a
shell inside GNU Emacs (or some other computing environment).

  If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands.  In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
print queue, and delete a job from the print queue.

  Details are in the following sections.

* Menu:

* Use TeX::                     Use TeX to format for hardcopy.
* Format with tex/texindex::    How to format with explicit shell commands.
* Format with texi2dvi::        A simpler way to format.
* Print with lpr::              How to print.
* Within Emacs::                How to format and print from an Emacs shell.
* Texinfo Mode Printing::       How to format and print in Texinfo mode.
* Compile-Command::             How to print using Emacs's compile command.
* Requirements Summary::        TeX formatting requirements summary.
* Preparing for TeX::           What to do before you use TeX.
* Overfull hboxes::             What are and what to do with overfull hboxes.
* @smallbook::                  How to print small format books and manuals.
* A4 Paper::                    How to print on A4 or A5 paper.
* @pagesizes::                  How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
                                 of pages and how to print scaled up output.
* PDF Output::                  Portable Document Format output.
* Obtaining TeX::               How to obtain TeX.


File: texinfo.info,  Node: Use TeX,  Next: Format with tex/texindex,  Up: Hardcopy

21.1 Use TeX
============

The typesetting program called TeX is used for formatting a Texinfo
file.  TeX is a very powerful typesetting program and, when used
correctly, does an exceptionally good job.

  *Note Obtaining TeX::, for information on how to obtain TeX.  It is
not included in the Texinfo package, being a vast suite of software
itself.


File: texinfo.info,  Node: Format with tex/texindex,  Next: Format with texi2dvi,  Prev: Use TeX,  Up: Hardcopy

21.2 Format with 'tex'/'texindex'
=================================

You can format the Texinfo file with the shell command 'tex' followed by
the name of the Texinfo file.  For example:

     tex foo.texi

TeX will produce a "DVI file" as well as several auxiliary files
containing information for indices, cross references, etc.  The DVI file
(for "DeVice Independent" file) can be printed on virtually any device
(see the following sections).

  The 'tex' formatting command itself does not sort the indices; it
writes an output file of unsorted index data.  To generate a printed
index after running the 'tex' command, you first need a sorted index to
work from.  The 'texindex' command sorts indices.  (The source file
'texindex.c' comes as part of the standard Texinfo distribution, among
other places.)  ('texi2dvi' runs 'tex' and 'texindex' as necessary.)

  'tex' formatting command outputs unsorted index files under names that
obey a standard convention: the name of your main input file with any
'.texinfo' (or similar, *note What a Texinfo File Must Have: Minimum.),
followed by the two letter names of indices.  For example, the raw index
output files for the input file 'foo.texinfo' would be 'foo.cp',
'foo.vr', 'foo.fn', 'foo.tp', 'foo.pg' and 'foo.ky'.  Those are exactly
the arguments to give to 'texindex'.

  Instead of specifying all the unsorted index file names explicitly,
you can use '??' as shell wildcards and give the command in this form:

     texindex foo.??

This command will run 'texindex' on all the unsorted index files,
including any two letter indices that you have defined yourself using
'@defindex' or '@defcodeindex'.  You can safely run 'texindex foo.??'
even if there are files with two letter extensions that are not index
files, such as 'foo.el'.  The 'texindex' command reports but otherwise
ignores such files.

  For each file specified, 'texindex' generates a sorted index file
whose name is made by appending 's' to the input file name.  The
'@printindex' command looks for a file with that name (*note Printing
Indices & Menus::).  'texindex' does not alter the raw index output
file.

  After you have sorted the indices, you need to rerun 'tex' on the
Texinfo file.  This regenerates the DVI file, this time with up-to-date
index entries.

  Finally, you may need to run 'tex' one more time, to get the page
numbers in the cross references correct.

  To summarize, this is a five step process:

  1. Run 'tex' on your Texinfo file.  This generates a DVI file (with
     undefined cross references and no indices), and the raw index files
     (with two letter extensions).

  2. Run 'texindex' on the raw index files.  This creates the
     corresponding sorted index files (with three letter extensions).

  3. Run 'tex' again on your Texinfo file.  This regenerates the DVI
     file, this time with indices and defined cross references, but with
     page numbers for the cross references from the previous run,
     generally incorrect.

  4. Sort the indices again, with 'texindex'.

  5. Run 'tex' one last time.  This time the correct page numbers are
     written for the cross references.

  Alternatively, it's a one-step process: run 'texi2dvi' (*note Format
with texi2dvi::).

  You need not run 'texindex' each time after you run 'tex'.  If you do
not, on the next run, the 'tex' formatting command will use whatever
sorted index files happen to exist from the previous use of 'texindex'.
This is usually ok while you are debugging.

  Sometimes you may wish to print a document while you know it is
incomplete, or to print just one chapter of a document.  In that case,
the usual auxiliary files that TeX creates and warnings TeX gives when
cross references are not satisfied are just nuisances.  You can avoid
them with the '@novalidate' command, which you must give _before_ the
'@setfilename' command (*note @setfilename::).  Thus, the beginning of
your file would look approximately like this:

     \input texinfo
     @novalidate
     @setfilename myfile.info
     ...

'@novalidate' also turns off validation in 'makeinfo', just like its
'--no-validate' option (*note Pointer Validation::).


File: texinfo.info,  Node: Format with texi2dvi,  Next: Print with lpr,  Prev: Format with tex/texindex,  Up: Hardcopy

21.3 Format with 'texi2dvi'
===========================

The 'texi2dvi' command automatically runs both TeX and 'texindex' as
many times as necessary to produce a DVI file with sorted indices and
all cross references resolved.  It is therefore simpler than manually
executing the 'tex'--'texindex'--'tex'--'tex' sequence described in the
previous section.

  To run 'texi2dvi' on an input file 'foo.texi', do this (where 'prompt$
' is your shell prompt):

     prompt$ texi2dvi foo.texi

  As shown in this example, the input filenames to 'texi2dvi' must
include any extension ('.texi', '.texinfo', etc.).  Under MS-DOS and
perhaps in other circumstances, you may need to run 'sh texi2dvi
foo.texi' instead of relying on the operating system to invoke the shell
on the 'texi2dvi' script.

  One useful option to 'texi2dvi' is '--command=CMD'.  This inserts CMD
on a line by itself after the '@setfilename' in a temporary copy of the
input file before running TeX.  With this, you can specify different
printing formats, such as '@smallbook' (*note @smallbook::),
'@afourpaper' (*note A4 Paper::), or '@pagesizes' (*note @pagesizes::),
without actually changing the document source.  (You can also do this on
a site-wide basis with 'texinfo.cnf'; *note Preparing for TeX::).

  With the '--pdf' option, 'texi2dvi' produces PDF output instead of DVI
(*note PDF Output::), by running 'pdftex' instead of 'tex'.
Alternatively, the command 'texi2pdf' is an abbreviation for running
'texi2dvi --pdf'.  The command 'pdftexi2dvi' is also supported as a
convenience to AUC-TeX users (*note (auctex)Top::, since that program
merely prepends 'pdf' to DVI producing tools to have PDF producing
tools.

  With the '--dvipdf' option, 'texi2dvi' produces PDF output by running
TeX and then a DVI-to-PDF program: if the 'DVIPDF' environment variable
is set, that value is used, else the first extant among 'dvipdfmx',
'dvipdfm', 'dvipdf', 'dvi2pdf', 'dvitopdf'.  This method can support CJK
typesetting better than 'pdftex'.

  With the '--ps' option, 'texi2dvi' produces PostScript instead of DVI,
by running 'tex' and then 'dvips' (*note (dvips)Top::).  (Or the value
of the 'DVIPS' environment variable, if set.)

  'texi2dvi' can also be used to process LaTeX files; simply run
'texi2dvi filename.ext'.

  Normally 'texi2dvi' is able to guess the input file language by its
contents and file name suffix.  If, however, it fails to do so you can
specify the input language using '--language=LANG' command line option,
where LANG is either 'latex' or 'texinfo'.

  'texi2dvi' will use 'etex' (or 'pdfetex') if they are available; these
extended versions of TeX are not required, and the DVI (or PDF) output
is identical, but they simplify the TeX programming in some cases, and
provide additional tracing information when debugging 'texinfo.tex'.

  Several options are provided for handling documents, written in
character sets other than ASCII.  The '--translate-file=FILE' option
instructs 'texi2dvi' to translate input into internal TeX character set
using "translation file" FILE (*note TCX files: (web2c)TCX files.).

  The options '--recode' and '--recode-from=ENC' allow conversion of an
input document before running TeX.  The '--recode' option recodes the
document from encoding specified by '@documentencoding' command (*note
@documentencoding::) to plain 7-bit 'texinfo' encoding.

  The option '--recode-from=ENC' recodes the document from ENC encoding
to the encoding specified by '@documentencoding'.  This is useful, for
example, if the document is written in 'UTF-8' encoding and an
equivalent 8-bit encoding is supported by 'makeinfo'.

  Both '--recode' and '--recode-from=ENC' use 'recode' utility to
perform the conversion.  If 'recode' fails to process the file,
'texi2dvi' prints a warning and continues, using the unmodified input
file.

  The option '-E' (equivalently, '-e' and '--expand') does Texinfo macro
expansion using 'makeinfo' instead of the TeX implementation (*note
Macro Details::).  Each implementation has its own limitations and
advantages.  If this option is used, the string '@c _texi2dvi' must not
appear at the beginning of a line in the source file.

  For the list of all options, run 'texi2dvi --help'.


File: texinfo.info,  Node: Print with lpr,  Next: Within Emacs,  Prev: Format with texi2dvi,  Up: Hardcopy

21.4 Print With 'lpr -d' From Shell
===================================

The precise command to print a DVI file depends on your system
installation.  Two common ones are 'dvips foo.dvi -o' and 'lpr -d
foo.dvi'.

  For example, the following commands will (perhaps) suffice to sort the
indices, format, and print the 'Bison Manual':

     tex bison.texinfo
     texindex bison.??
     tex bison.texinfo
     lpr -d bison.dvi

(Remember that the shell commands may be different at your site; but
these are commonly used versions.)

  Using the 'texi2dvi' shell script (see the previous section):

     texi2dvi bison.texinfo
     lpr -d bison.dvi
     # or perhaps dvips bison.dvi -o

  'lpr' is a standard program on Unix systems, but it is usually absent
on MS-DOS/MS-Windows.  Some network packages come with a program named
'lpr', but these are usually limited to sending files to a print server
over the network, and generally don't support the '-d' option.  If you
are unfortunate enough to work on one of these systems, you have several
alternative ways of printing DVI files:

   * Find and install a Unix-like 'lpr' program, or its clone.  If you
     can do that, you will be able to print DVI files just like
     described above.

   * Send the DVI files to a network printer queue for DVI files.  Some
     network printers have special queues for printing DVI files.  You
     should be able to set up your network software to send files to
     that queue.  In some cases, the version of 'lpr' which comes with
     your network software will have a special option to send a file to
     specific queues, like this:

          lpr -Qdvi -hprint.server.domain bison.dvi

   * Convert the DVI file to a Postscript or PCL file and send it to
     your local printer.  *Note (dvips)Invoking Dvips::, and the man
     pages for 'dvilj', for detailed description of these tools.  Once
     the DVI file is converted to the format your local printer
     understands directly, just send it to the appropriate port, usually
     'PRN'.


File: texinfo.info,  Node: Within Emacs,  Next: Texinfo Mode Printing,  Prev: Print with lpr,  Up: Hardcopy

21.5 From an Emacs Shell
========================

You can give formatting and printing commands from a shell within GNU
Emacs.  To create a shell within Emacs, type 'M-x shell'.  In this
shell, you can format and print the document.  *Note Format and Print
Hardcopy: Hardcopy, for details.

  You can switch to and from the shell buffer while 'tex' is running and
do other editing.  If you are formatting a long document on a slow
machine, this can be very convenient.

  You can also use 'texi2dvi' from an Emacs shell.  For example, here is
how to use 'texi2dvi' to format and print 'Using and Porting GNU CC'
from a shell within Emacs:

     texi2dvi gcc.texinfo
     lpr -d gcc.dvi

  See the next section for more information about formatting and
printing in Texinfo mode.


File: texinfo.info,  Node: Texinfo Mode Printing,  Next: Compile-Command,  Prev: Within Emacs,  Up: Hardcopy

21.6 Formatting and Printing in Texinfo Mode
============================================

Texinfo mode provides several predefined key commands for TeX formatting
and printing.  These include commands for sorting indices, looking at
the printer queue, killing the formatting job, and recentering the
display of the buffer in which the operations occur.

'C-c C-t C-b'
'M-x texinfo-tex-buffer'
     Run 'texi2dvi' on the current buffer.

'C-c C-t C-r'
'M-x texinfo-tex-region'
     Run TeX on the current region.

'C-c C-t C-i'
'M-x texinfo-texindex'
     Sort the indices of a Texinfo file formatted with
     'texinfo-tex-region'.

'C-c C-t C-p'
'M-x texinfo-tex-print'
     Print a DVI file that was made with 'texinfo-tex-region' or
     'texinfo-tex-buffer'.

'C-c C-t C-q'
'M-x tex-show-print-queue'
     Show the print queue.

'C-c C-t C-d'
'M-x texinfo-delete-from-print-queue'
     Delete a job from the print queue; you will be prompted for the job
     number shown by a preceding 'C-c C-t C-q' command
     ('texinfo-show-tex-print-queue').

'C-c C-t C-k'
'M-x tex-kill-job'
     Kill the currently running TeX job started by either
     'texinfo-tex-region' or 'texinfo-tex-buffer', or any other process
     running in the Texinfo shell buffer.

'C-c C-t C-x'
'M-x texinfo-quit-job'
     Quit a TeX formatting job that has stopped because of an error by
     sending an <x> to it.  When you do this, TeX preserves a record of
     what it did in a '.log' file.

'C-c C-t C-l'
'M-x tex-recenter-output-buffer'
     Redisplay the shell buffer in which the TeX printing and formatting
     commands are run to show its most recent output.

  Thus, the usual sequence of commands for formatting a buffer is as
follows (with comments to the right):

     C-c C-t C-b             Run 'texi2dvi' on the buffer.
     C-c C-t C-p             Print the DVI file.
     C-c C-t C-q             Display the printer queue.

  The Texinfo mode TeX formatting commands start a subshell in Emacs
called the '*tex-shell*'.  The 'texinfo-tex-command',
'texinfo-texindex-command', and 'tex-dvi-print-command' commands are all
run in this shell.

  You can watch the commands operate in the '*tex-shell*' buffer, and
you can switch to and from and use the '*tex-shell*' buffer as you would
any other shell buffer.

  The formatting and print commands depend on the values of several
variables.  The default values are:

         Variable                              Default value

     texinfo-texi2dvi-command                  "texi2dvi"
     texinfo-tex-command                       "tex"
     texinfo-texindex-command                  "texindex"
     texinfo-delete-from-print-queue-command   "lprm"
     texinfo-tex-trailer                       "@bye"
     tex-start-of-header                       "%**start"
     tex-end-of-header                         "%**end"
     tex-dvi-print-command                     "lpr -d"
     tex-show-queue-command                    "lpq"

  You can change the values of these variables with the 'M-x
set-variable' command (*note Examining and Setting Variables:
(emacs)Examining.), or with your '.emacs' initialization file (*note
(emacs)Init File::).

  Beginning with version 20, GNU Emacs offers a user-friendly interface,
called "Customize", for changing values of user-definable variables.
*Note Easy Customization Interface: (emacs)Easy Customization, for more
details about this.  The Texinfo variables can be found in the
'Development/Docs/Texinfo' group, once you invoke the 'M-x customize'
command.


File: texinfo.info,  Node: Compile-Command,  Next: Requirements Summary,  Prev: Texinfo Mode Printing,  Up: Hardcopy

21.7 Using the Local Variables List
===================================

Yet another way to apply the TeX formatting command to a Texinfo file is
to put that command in a "local variables list" at the end of the
Texinfo file.  You can then specify the 'tex' or 'texi2dvi' commands as
a 'compile-command' and have Emacs run it by typing 'M-x compile'.  This
creates a special shell called the '*compilation*' buffer in which Emacs
runs the compile command.  For example, at the end of the 'gdb.texinfo'
file, after the '@bye', you could put the following:

     Local Variables:
     compile-command: "texi2dvi gdb.texinfo"
     End:

This technique is most often used by programmers who also compile
programs this way; see *note (emacs)Compilation::.


File: texinfo.info,  Node: Requirements Summary,  Next: Preparing for TeX,  Prev: Compile-Command,  Up: Hardcopy

21.8 TeX Formatting Requirements Summary
========================================

Every Texinfo file that is to be input to TeX must begin with a '\input'
command and must contain an '@setfilename' command:

     \input texinfo
     @setfilename ARG-NOT-USED-BY-TeX

The first command instructs TeX to load the macros it needs to process a
Texinfo file and the second command opens auxiliary files.

  Every Texinfo file must end with a line that terminates TeX's
processing and forces out unfinished pages:

     @bye

  Strictly speaking, these lines are all a Texinfo file needs to be
processed successfully by TeX.

  Usually, however, the beginning includes an '@settitle' command to
define the title of the printed manual, an '@setchapternewpage' command,
a title page, a copyright page, and permissions.  Besides an '@bye', the
end of a file usually includes indices and a table of contents.  (And of
course most manuals contain a body of text as well.)

  For more information, see:

   * *note @settitle::.
   * *note @setchapternewpage::.
   * *note Headings::.
   * *note Titlepage & Copyright Page::.
   * *note Printing Indices & Menus::.
   * *note Contents::.


File: texinfo.info,  Node: Preparing for TeX,  Next: Overfull hboxes,  Prev: Requirements Summary,  Up: Hardcopy

21.9 Preparing for TeX
======================

TeX needs to know where to find the 'texinfo.tex' file that the '\input
texinfo' command on the first line reads.  The 'texinfo.tex' file tells
TeX how to handle @-commands; it is included in all standard GNU
distributions.  The latest version is always available from the Texinfo
source repository:
     <http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD>

  Usually, the installer has put the 'texinfo.tex' file in the default
directory that contains TeX macros when GNU Texinfo, Emacs or other GNU
software is installed.  In this case, TeX will find the file and you do
not need to do anything special.  If this has not been done, you can put
'texinfo.tex' in the current directory when you run TeX, and TeX will
find it there.

  Also, you should install 'epsf.tex', if it is not already installed
from another distribution.  More details are at the end of the
description of the '@image' command (*note Images::).

  To be able to use quotation marks other than those used in English
you'll need to install European Computer Modern fonts and optionally
CM-Super fonts, unless they are already installed (*note Inserting
Quotation Marks::).

  If you intend to use the '@euro' command, you should install the Euro
font, if it is not already installed.  *Note @euro::.

  Optionally, you may create an additional 'texinfo.cnf', and install it
as well.  This file is read by TeX when the '@setfilename' command is
executed (*note @setfilename::).  You can put any commands you like
there, according to local site-wide conventions.  They will be read by
TeX when processing any Texinfo document.  For example, if 'texinfo.cnf'
contains the line '@afourpaper' (*note A4 Paper::), then all Texinfo
documents will be processed with that page size in effect.  If you have
nothing to put in 'texinfo.cnf', you do not need to create it.

  If neither of the above locations for these system files suffice for
you, you can specify the directories explicitly.  For 'texinfo.tex', you
can do this by writing the complete path for the file after the '\input'
command.  Another way, that works for both 'texinfo.tex' and
'texinfo.cnf' (and any other file TeX might read), is to set the
'TEXINPUTS' environment variable in your '.cshrc' or '.profile' file.

  Which you use of '.cshrc' or '.profile' depends on whether you use a
Bourne shell-compatible ('sh', 'bash', 'ksh', ...) or C shell-compatible
('csh', 'tcsh') command interpreter.  The latter read the '.cshrc' file
for initialization information, and the former read '.profile'.

  In a '.cshrc' file, you could use the following 'csh' command
sequence:

     setenv TEXINPUTS .:/home/me/mylib:

  In a '.profile' file, you could use the following 'sh' command
sequence:

     TEXINPUTS=.:/home/me/mylib:
     export TEXINPUTS

  On MS-DOS/MS-Windows, you would say it like this(1):

     set TEXINPUTS=.;d:/home/me/mylib;c:

It is customary for DOS/Windows users to put such commands in the
'autoexec.bat' file, or in the Windows registry.

These settings would cause TeX to look for '\input' file first in the
current directory, indicated by the '.', then in a hypothetical user
'me''s 'mylib' directory, and finally in the system directories.  (A
leading, trailing, or doubled ':' indicates searching the system
directories at that point.)

  Finally, you may wish to dump a '.fmt' file (*note (web2c)Memory
dumps::) so that TeX can load Texinfo faster.  (The disadvantage is that
then updating 'texinfo.tex' requires redumping.)  You can do this by
running this command, assuming 'epsf.tex' is findable by TeX:

     initex texinfo @dump

('dump' is a TeX primitive.)  Then, move 'texinfo.fmt' to wherever your
'.fmt' files are found; typically, this will be in the subdirectory
'web2c' of your TeX installation.

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

   (1) Note the use of the ';' character, instead of ':', as directory
separator on these systems.


File: texinfo.info,  Node: Overfull hboxes,  Next: @smallbook,  Prev: Preparing for TeX,  Up: Hardcopy

21.10 Overfull "hboxes"
=======================

TeX is sometimes unable to typeset a line without extending it into the
right margin.  This can occur when TeX comes upon what it interprets as
a long word that it cannot hyphenate, such as an electronic mail network
address or a very long title.  When this happens, TeX prints an error
message like this:

     Overfull @hbox (20.76302pt too wide)

(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
'@hbox' is a TeX primitive not used in the Texinfo language.)

  TeX also provides the line number in the Texinfo source file and the
text of the offending line, which is marked at all the places that TeX
considered hyphenation.  *Note Debugging with TeX::, for more
information about typesetting errors.

  If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it.  A
small excursion into the right margin often does not matter and may not
even be noticeable.

  If you have many overfull boxes and/or an antipathy to rewriting, you
can coerce TeX into greatly increasing the allowable interword spacing,
thus (if you're lucky) avoiding many of the bad line breaks, like this:

     @tex
     \global\emergencystretch = .9\hsize
     @end tex

(You should adjust the fraction as needed.)  This huge value for
'\emergencystretch' cannot be the default, since then the typeset output
would generally be of noticeably lower quality; the default is
'.15\hsize'.  '\hsize' is the TeX dimension containing the current line
width.

  For what overfull boxes you have, however, TeX will print a large,
ugly, black rectangle beside the line that contains the overfull hbox
unless told otherwise.  This is so you will notice the location of the
problem if you are correcting a draft.

  To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
before the '@titlepage' command:

     @finalout


File: texinfo.info,  Node: @smallbook,  Next: A4 Paper,  Prev: Overfull hboxes,  Up: Hardcopy

21.11 '@smallbook': Printing "Small" Books
==========================================

By default, TeX typesets pages for printing in an 8.5 by 11 inch format.
However, you can direct TeX to typeset a document in a 7 by 9.25 inch
format that is suitable for bound books by inserting the following
command on a line by itself at the beginning of the Texinfo file, before
the title page:

     @smallbook

(Since many books are about 7 by 9.25 inches, this command might better
have been called the '@regularbooksize' command, but it came to be
called the '@smallbook' command by comparison to the 8.5 by 11 inch
format.)

  If you write the '@smallbook' command between the start-of-header and
end-of-header lines, the Texinfo mode TeX region formatting command,
'texinfo-tex-region', will format the region in "small" book size (*note
Start of Header::).

  *Note @small...::, for information about commands that make it easier
to produce examples for a smaller manual.

  *Note Format with texi2dvi::, and *note Preparing for TeX::, for other
ways to format with '@smallbook' that do not require changing the source
file.


File: texinfo.info,  Node: A4 Paper,  Next: @pagesizes,  Prev: @smallbook,  Up: Hardcopy

21.12 Printing on A4 Paper
==========================

You can tell TeX to format a document for printing on European size A4
paper (or A5) with the '@afourpaper' (or '@afivepaper') command.  Write
the command on a line by itself near the beginning of the Texinfo file,
before the title page.  For example, this is how you would write the
header for this manual:

     \input texinfo    @c -*-texinfo-*-
     @c %**start of header
     @setfilename texinfo
     @settitle Texinfo
     @afourpaper
     @c %**end of header

  *Note Format with texi2dvi::, and *note Preparing for TeX::, for other
ways to format for different paper sizes that do not require changing
the source file.

  You may or may not prefer the formatting that results from the command
'@afourlatex'.  There's also '@afourwide' for A4 paper in wide format.


File: texinfo.info,  Node: @pagesizes,  Next: Cropmarks and Magnification,  Prev: A4 Paper,  Up: Hardcopy

21.13 '@pagesizes' [WIDTH][, HEIGHT]: Custom Page Sizes
=======================================================

You can explicitly specify the height and (optionally) width of the main
text area on the page with the '@pagesizes' command.  Write this on a
line by itself near the beginning of the Texinfo file, before the title
page.  The height comes first, then the width if desired, separated by a
comma.  Examples:

     @pagesizes 200mm,150mm  
and
     @pagesizes 11.5in      

  This would be reasonable for printing on B5-size paper.  To emphasize,
this command specifies the size of the _text area_, not the size of the
paper (which is 250mm by 177mm for B5, 14in by 8.5in for legal).

  To make more elaborate changes, such as changing any of the page
margins, you must define a new command in 'texinfo.tex' or
'texinfo.cnf'.

  *Note Format with texi2dvi::, and *note Preparing for TeX::, for other
ways to specify '@pagesizes' that do not require changing the source
file.

  '@pagesizes' is ignored by 'makeinfo'.


File: texinfo.info,  Node: Cropmarks and Magnification,  Next: PDF Output,  Prev: @pagesizes,  Up: Hardcopy

21.14 Cropmarks and Magnification
=================================

You can (attempt to) direct TeX to print cropmarks at the corners of
pages with the '@cropmarks' command.  Write the '@cropmarks' command on
a line by itself near the beginning of the Texinfo file, before the
title page, like this:

     @cropmarks

  This command is mainly for printers that typeset several pages on one
sheet of film; but you can attempt to use it to mark the corners of a
book set to 7 by 9.25 inches with the '@smallbook' command.  (Printers
will not produce cropmarks for regular sized output that is printed on
regular sized paper.)  Since different printing machines work in
different ways, you should explore the use of this command with a spirit
of adventure.  You may have to redefine the command in 'texinfo.tex'.

  The '@cropmarks' command is recognized and ignored in non-TeX output
formats.

  You can attempt to direct TeX to typeset pages larger or smaller than
usual with the '\mag' TeX command.  Everything that is typeset is scaled
proportionally larger or smaller.  ('\mag' stands for "magnification".)
This is _not_ a Texinfo @-command, but is a raw TeX command that is
prefixed with a backslash.  You have to write this command between
'@tex' and '@end tex' (*note Raw Formatter Commands::).

  Follow the '\mag' command with an '=' and then a number that is 1000
times the magnification you desire.  For example, to print pages at 1.2
normal size, write the following near the beginning of the Texinfo file,
before the title page:

     @tex
     \mag=1200
     @end tex

  With some printing technologies, you can print normal-sized copies
that look better than usual by giving a larger-than-normal master to
your print shop.  They do the reduction, thus effectively increasing the
resolution.

  Depending on your system, DVI files prepared with a nonstandard-'\mag'
may not print or may print only with certain magnifications.  Be
prepared to experiment.


File: texinfo.info,  Node: PDF Output,  Next: Obtaining TeX,  Prev: Cropmarks and Magnification,  Up: Hardcopy

21.15 PDF Output
================

The simplest way to generate PDF output from Texinfo source is to run
the convenience script 'texi2pdf' (or 'pdftexi2dvi'); this executes the
'texi2dvi' script with the '--pdf' option (*note Format with
texi2dvi::).  If for some reason you want to process the document by
hand, you can run the 'pdftex' program instead of plain 'tex'.  That is,
run 'pdftex foo.texi' instead of 'tex foo.texi'.

  "PDF" stands for 'Portable Document Format'.  It was invented by Adobe
Systems some years ago for document interchange, based on their
PostScript language.  Related links:

   * GNU GV, a Ghostscript-based PDF reader
     (http://www.gnu.org/software/gv/).  (It can also preview PostScript
     documents.)

   * A freely available standalone PDF reader
     (http://www.foolabs.com/xpdf/) for the X window system.

   * PDF definition
     (http://partners.adobe.com/asn/acrobat/sdk/public/docs/).

  At present, Texinfo does not provide '@ifpdf' or '@pdf' commands as
for the other output formats, since PDF documents contain many internal
links that would be hard or impossible to get right at the Texinfo
source level.

  PDF files require special software to be displayed, unlike the plain
ASCII formats (Info, HTML) that Texinfo supports.  They also tend to be
much larger than the DVI files output by TeX by default.  Nevertheless,
a PDF file does define an actual typeset document in a self-contained
file, so it has its place.


File: texinfo.info,  Node: Obtaining TeX,  Prev: PDF Output,  Up: Hardcopy

21.16 Obtaining TeX
===================

TeX is a document formatter that is used by the FSF for its
documentation.  It is the easiest way to get printed output (e.g., PDF
and PostScript) for Texinfo manuals.  TeX is freely redistributable, and
you can get it over the Internet or on physical media.  See
<http://tug.org/texlive>.


File: texinfo.info,  Node: Generic Translator texi2any,  Next: Creating and Installing Info Files,  Prev: Hardcopy,  Up: Top

22 'texi2any': The Generic Translator for Texinfo
*************************************************

'texi2any' is the generic translator for Texinfo that can produce
different output formats and is highly customizable.  It supports these
formats:

Info (by default, or with '--info'),

HTML (with '--html'),

plain text (with '--plaintext'),

Docbook (with '--docbook'),

Texinfo XML (with '--xml').

  'makeinfo' is an alias for 'texi2any'.  By default, both 'texi2any'
and 'makeinfo' generate Info output; indeed, there are no differences in
behavior based on the name.

  Beside these default formats, command line options to 'texi2any' can
change many aspects of the output.  Beyond that, initialization files
provide even more control over the final output--nearly anything not
specified in the Texinfo input file.  Initialization files are written
in Perl, like the main program, and anything which can be specified on
the command line can also be specified within a initialization file.

  The rest of this chapter goes into the details.

* Menu:

* Reference Implementation::    'texi2any': the reference implementation.
* Invoking texi2any::           Running the translator from a shell.
* texi2any Printed Output::     Calling 'texi2dvi'.
* Pointer Validation::          How to check that pointers point somewhere.
* Customization Variables::     Configuring 'texi2any'.
* Internationalization of Document Strings:: Translating program-inserted text.
* Invoking pod2texi::           Translating Perl pod to Texinfo.
* texi2html::                   An ancestor of 'texi2any'.


File: texinfo.info,  Node: Reference Implementation,  Next: Invoking texi2any,  Up: Generic Translator texi2any

22.1 'texi2any': A Texinfo Reference Implementation
===================================================

Above, we called 'texi2any' "the" translator for Texinfo instead of just
"a" translator, even though (of course) it's technically and legally
possible for other implementations to be written.  The reason is that
alternative implementations are highly likely to have subtle, or
not-so-subtle, differences in behavior, and thus Texinfo documents would
become dependent on the processor.  Therefore, it is important to have a
reference implementation that defines parts of the language not fully
specified by the manual (often intentionally so).  It is equally
important to have consistent command-line options and other behavior for
processors.

  For this reason, the once-independent 'texi2html' Perl Texinfo
processor was made compatible with the C implementation of 'makeinfo',
to avoid continuing with two different implementations (*note
History::).  The current reference implementation, 'texi2any', inherited
the design of customization and other features from 'texi2html' (for
more on 'texi2html' compatibility, *note texi2html::).  However,
'texi2any' is a full reimplementation: it constructs a tree-based
representation of the input document for all back-ends to work from.

  Extensive tests of the language were developed at the same time as
'texi2any'; we plead with anyone thinking of writing a program to parse
Texinfo input to at least make use of these tests.

  The 'texi2html' wrapper script (*note texi2html::) provides a simple
example of calling 'texi2any' from a shell script; it's in
'util/texi2html' in the Texinfo sources.  More consequentially,
'texi-elements-by-size' is an example Perl script using the
'Texinfo::Parser' module interface; it's in
'util/texi-elements-by-size'.  (Its functionality may also be useful to
authors; *note texi-elements-by-size::.)

  With the release of 'texi2any' as the reference implementation,
development of both the C implementation of 'makeinfo' and 'texi2html'
has been halted.  Going forward, we ask authors of Texinfo documents to
use only 'texi2any'.


File: texinfo.info,  Node: Invoking texi2any,  Next: texi2any Printed Output,  Prev: Reference Implementation,  Up: Generic Translator texi2any

22.2 Invoking 'texi2any'/'makeinfo' from a Shell
================================================

To process a Texinfo file, invoke 'texi2any' or 'makeinfo' (the two
names are synonyms for the same program; we'll use the names
interchangeably) followed by the name of the Texinfo file.  Also select
the format you want to output with the appropriate command line option
(default is Info).  Thus, to create the Info file for Bison, type the
following to the shell:

     texi2any --info bison.texinfo

  You can specify more than one input file name; each is processed in
turn.  If an input file name is '-', standard input is read.

  The 'texi2any' program accept many options.  Perhaps the most basic
are those that change the output format.  By default, 'texi2any' outputs
Info.

  Each command line option is either a long name preceded by '--' or a
single letter preceded by '-'.  You can use abbreviations for the long
option names as long as they are unique.

  For example, you could use the following shell command to create an
Info file for 'bison.texinfo' in which lines are filled to only 68
columns:

     texi2any --fill-column=68 bison.texinfo

  You can write two or more options in sequence, like this:

     texi2any --no-split --fill-column=70 ...

(This would keep the Info file together as one possibly very long file
and would also set the fill column to 70.)

  The options are (approximately in alphabetical order):

'--commands-in-node-names'
     This option now does nothing, but remains for compatibility.  (It
     used to ensure that @-commands in node names were expanded
     throughout the document, especially '@value'.  This is now done by
     default.)

'--conf-dir=PATH'
     Prepend PATH to the directory search list for finding customization
     files that may be loaded with '--init-file' (see below).  The PATH
     value can be a single directory, or a list of several directories
     separated by the usual path separator character (':' on Unix-like
     systems, ';' on Windows).

'--css-include=FILE'
     When producing HTML, literally include the contents of FILE, which
     should contain W3C cascading style sheets specifications, in the
     '<style>' block of the HTML output.  If FILE is '-', read standard
     input.  *Note HTML CSS::.

'--css-ref=URL'
     When producing HTML, add a '<link>' tag to the output which
     references a cascading style sheet at URL.  This allows using
     standalone style sheets.

'-D VAR'
     Cause the Texinfo variable VAR to be defined.  This is equivalent
     to '@set VAR' in the Texinfo file (*note @set @clear @value::).

'--disable-encoding'
'--enable-encoding'
     By default, or with '--enable-encoding', output accented and
     special characters in Info and plain text output based on
     '@documentencoding'.  With '--disable-encoding', 7-bit ASCII
     transliterations are output.  *Note @documentencoding::, and *note
     Inserting Accents::.

'--docbook'
     Generate Docbook output (rather than Info).

'--document-language=LANG'
     Use LANG to translate Texinfo keywords which end up in the output
     document.  The default is the locale specified by the
     '@documentlanguage' command if there is one, otherwise English
     (*note @documentlanguage::).

'--dvi'
     Generate a TeX DVI file using 'texi2dvi', rather than Info (*note
     texi2any Printed Output::).

'--dvipdf'
     Generate a PDF file using 'texi2dvi --dvipdf', rather than Info
     (*note texi2any Printed Output::).

'--error-limit=LIMIT'
'-e LIMIT'
     Report LIMIT errors before aborting (on the assumption that
     continuing would be useless); default 100.

'--fill-column=WIDTH'
'-f WIDTH'
     Specify the maximum number of columns in a line; this is the
     right-hand edge of a line.  Paragraphs that are filled will be
     filled to this width.  (Filling is the process of breaking up and
     connecting lines so that lines are the same length as or shorter
     than the number specified as the fill column.  Lines are broken
     between words.)  The default value is 72.

'--footnote-style=STYLE'
'-s STYLE'
     Set the footnote style to STYLE: either 'end' for the end node
     style (the default) or 'separate' for the separate node style.  The
     value set by this option overrides the value set in a Texinfo file
     by an '@footnotestyle' command (*note Footnote Styles::).

     When the footnote style is 'separate', 'makeinfo' makes a new node
     containing the footnotes found in the current node.  When the
     footnote style is 'end', 'makeinfo' places the footnote references
     at the end of the current node.

     In HTML, when the footnote style is 'end', or if the output is not
     split, footnotes are put at the end of the output.  If set to
     'separate', and the output is split, they are placed in a separate
     file.

'--force'
'-F'
     Ordinarily, if the input file has errors, the output files are not
     created.  With this option, they are preserved.

'--help'
'-h'
     Print a message with available options and basic usage, then exit
     successfully.

'--html'
     Generate HTML output (rather than Info).  By default, the HTML
     output is split into one output file per Texinfo source node, and
     the split output is written into a subdirectory based on the name
     of the top-level Info file.  *Note Generating HTML::.

'-I PATH'
     Append PATH to the directory search list for finding files that are
     included using the '@include' command.  By default, 'texi2any'
     searches only the current directory.  If PATH is not given, the
     current directory is appended.  The PATH value can be a single
     directory or a list of several directories separated by the usual
     path separator character (':' on Unix-like systems, ';' on
     Windows).

'--ifdocbook'
'--ifhtml'
'--ifinfo'
'--ifplaintext'
'--iftex'
'--ifxml'
     For the given format, process '@ifFORMAT' and '@FORMAT' commands,
     and do not process '@ifnotFORMAT', regardless of the format being
     output.  For instance, if '--iftex' is given, then '@iftex' and
     '@tex' blocks will be read, and '@ifnottex' blocks will be ignored.

'--info'
     Generate Info output.  By default, if the output file contains more
     than about 300,000 bytes, it is split into shorter subfiles of
     about that size.  The name of the output file and any subfiles is
     determined by '@setfilename' (*note @setfilename::).  *Note Tag and
     Split Files::.

'--init-file=FILE'
     Load FILE as code to modify the behavior and output of the
     generated manual.  It is customary to use the '.pm' or the '.init'
     extensions for these customization files, but that is not enforced;
     the FILE name can be anything.  The '--conf-dir' option (see above)
     can be used to add to the list of directories in which these
     customization files are searched for.

'--internal-links=FILE'
     In HTML mode, output a tab-separated file containing three columns:
     the internal link to an indexed item or item in the table of
     contents, the name of the index (or table of contents) in which it
     occurs, and the term which was indexed or entered.  The items are
     in the natural sorting order for the given element.  This dump can
     be useful for post-processors.

'--macro-expand=FILE'
'-E FILE'
     Output the Texinfo source, with all Texinfo macros expanded, to
     FILE.  Normally, the result of macro expansion is used internally
     by 'makeinfo' and then discarded.

'--no-headers'
     Do not include menus or node separator lines in the output.

     When generating Info, this is the same as using '--plaintext',
     resulting in a simple plain text file.  Furthermore, '@setfilename'
     is ignored, and output is to standard output unless overridden with
     '-o'.  (This behavior is for backward compatibility.)

     When generating HTML, and output is split, also output navigation
     links only at the beginning of each file.  If output is not split,
     do not include navigation links at the top of each node at all.
     *Note Generating HTML::.

'--no-ifdocbook'
'--no-ifhtml'
'--no-ifinfo'
'--no-ifplaintext'
'--no-iftex'
'--no-ifxml'
     For the given format, do not process '@ifFORMAT' and '@FORMAT'
     commands, and do process '@ifnotFORMAT', regardless of the format
     being output.  For instance, if '--no-ifhtml' is given, then
     '@ifhtml' and '@html' blocks will not be read, and '@ifnothtml'
     blocks will be.

'--no-node-files'
'--node-files'
     When generating HTML, create redirection files for anchors and any
     nodes not already output with the file name corresponding to the
     node name (*note HTML Xref Node Name Expansion::).  This makes it
     possible for section- and chapter-level cross-manual references to
     succeed (*note HTML Xref Configuration::).

     If the output is split, this is enabled by default.  If the output
     is not split, '--node-files' enables the creation of the
     redirection files, in addition to the monolithic main output file.
     '--no-node-files' suppresses the creation of redirection files in
     any case.  This option has no effect with any output format other
     than HTML.  *Note Generating HTML::.

'--no-number-footnotes'
     Suppress automatic footnote numbering.  By default, footnotes are
     numbered sequentially within a node, i.e., the current footnote
     number is reset to 1 at the start of each node.

'--no-number-sections'
'--number-sections'
     With '--number_sections' (the default), output chapter, section,
     and appendix numbers as in printed manuals.  This works only with
     hierarchically-structured manuals.  You should specify
     '--no-number-sections' if your manual is not normally structured.

'--no-pointer-validate'
'--no-validate'
     Suppress the pointer-validation phase of 'makeinfo'--a dangerous
     thing to do.  This can also be done with the '@novalidate' command
     (*note Use TeX::).  Normally, consistency checks are made to ensure
     that cross references can be resolved, etc.  *Note Pointer
     Validation::.

'--no-warn'
     Suppress warning messages (but not error messages).

'--output=FILE'
'-o FILE'
     Specify that the output should be directed to FILE.  This overrides
     any file name specified in an '@setfilename' command found in the
     Texinfo source.  If neither '@setfilename' nor this option are
     specified, the input file name is used to determine the output
     name.  *Note @setfilename::.

     If FILE is '-', output goes to standard output and '--no-split' is
     implied.

     If FILE is a directory or ends with a '/' the usual rules are used
     to determine the output file name (namely, use '@setfilename' or
     the input file name) but the files are written to the FILE
     directory.  For example, 'makeinfo -o bar/ foo.texi', with or
     without '--no-split', will write 'bar/foo.info', and possibly other
     files, under 'bar/'.

     When generating HTML and output is split, FILE is used as the name
     for the directory into which all files are written.  For example,
     'makeinfo -o bar --html foo.texi' will write 'bar/index.html',
     among other files.

'--output-indent=VAL'
     This option now does nothing, but remains for compatibility.  (It
     used to alter indentation in XML/Docbook output.)

'-P PATH'
     Prepend PATH to the directory search list for '@include'.  If PATH
     is not given, the current directory is prepended.  See '-I' above.

'--paragraph-indent=INDENT'
'-p INDENT'
     Set the paragraph indentation style to INDENT.  The value set by
     this option overrides the value set in a Texinfo file by an
     '@paragraphindent' command (*note @paragraphindent::).  The value
     of INDENT is interpreted as follows:

     'asis'
          Preserve any existing indentation (or lack thereof) at the
          beginnings of paragraphs.

     '0' or 'none'
          Delete any existing indentation.

     NUM
          Indent each paragraph by NUM spaces.

     The default is to indent by two spaces, except for paragraphs
     following a section heading, which are not indented.

'--pdf'
     Generate a PDF file using 'texi2dvi --pdf', rather than Info (*note
     texi2any Printed Output::).

'--plaintext'
     Output a plain text file (rather than Info): do not include menus
     or node separator lines in the output.  This results in a
     straightforward plain text file that you can (for example) send in
     email without complications, or include in a distribution (for
     example, an 'INSTALL' file).

     With this option, '@setfilename' is ignored and the output goes to
     standard output by default; this can be overridden with '-o'.

'--ps'
     Generate a PostScript file using 'texi2dvi --ps', rather than Info
     (*note texi2any Printed Output::).

'--set-customization-variable VAR=VALUE'
'-c VAR=VALUE'
     Set the customization variable VAR to VALUE.  The '=' is optional,
     but both VAR and VALUE must be quoted to the shell as necessary so
     the result is a single word.  Many aspects of 'texi2any' behavior
     and output may be controlled by customization variables, beyond
     what can be set in the document by @-commands and with other
     command line switches.  *Note Customization Variables::.

'--split=HOW'
'--no-split'
     When generating Info, by default large output files are split into
     smaller subfiles, of approximately 300k bytes.  When generating
     HTML, by default each output file contains one node (*note
     Generating HTML::).  '--no-split' suppresses this splitting of the
     output.

     Alternatively, '--split=HOW' may be used to specify at which level
     the HTML output should be split.  The possible values for HOW are:

     'chapter'
          The output is split at '@chapter' and other sectioning
          @-commands at this level ('@appendix', etc.).

     'section'
          The output is split at '@section' and similar.

     'node'
          The output is split at every node.  This is the default.

'--split-size=NUM'
     Keep Info files to at most NUM characters if possible; default is
     300,000.  (However, a single node will never be split across Info
     files.)

'--transliterate-file-names'
     Enable transliteration of 8-bit characters in node names for the
     purpose of file name creation.  *Note HTML Xref 8-bit Character
     Expansion::.

'-U VAR'
     Cause VAR to be undefined.  This is equivalent to '@clear VAR' in
     the Texinfo file (*note @set @clear @value::).

'--verbose'
     Cause 'makeinfo' to display messages saying what it is doing.
     Normally, 'makeinfo' only outputs messages if there are errors or
     warnings.

'--version'
'-V'
     Print the version number, then exit successfully.

'--Xopt STR'
     Pass STR (a single shell word) to 'texi2dvi'; may be repeated
     (*note texi2any Printed Output::).

'--xml'
     Generate Texinfo XML output (rather than Info).

  'makeinfo' also reads the environment variable 'TEXINFO_OUTPUT_FORMAT'
to determine the output format, if not overridden by a command line
option.  The value should be one of:

     docbook  dvi  dvipdf  html  info  pdf  plaintext  ps  xml

  If not set or otherwise specified, Info output is the default.

  The customization variable of the same name is also read; if set, that
overrides an environment variable setting, but not a command-line
option.  *Note Customization Variables for @-Commands::.


File: texinfo.info,  Node: texi2any Printed Output,  Next: Pointer Validation,  Prev: Invoking texi2any,  Up: Generic Translator texi2any

22.3 'texi2any' Printed Output
==============================

To justify the name Texinfo-to-_any_, 'texi2any' has basic support for
creating printed output in the various formats: TeX DVI, PDF, and
PostScript.  This is done via the simple method of executing the
'texi2dvi' program when those outputs are requested.

  The output format options for this are '--dvi', '--dvipdf', '--pdf',
and '--ps'.  *Note Format with texi2dvi::, for more details on these
options and general 'texi2dvi' operation.  In addition, the '--verbose',
'--silent', and '--quiet' options are passed on if specified; the '-I'
and '-o' options are likewise passed on with their arguments, and
'--debug' without its argument.

  The only option remaining that is related to the 'texi2dvi' invocation
is '--Xopt'.  Here, just the argument is passed on and multiple '--Xopt'
options accumulate.  This provides a way to construct an arbitrary
command line for 'texi2dvi'.  For example, running

     texi2any --Xopt -t --Xopt @a4paper --pdf foo.texi

is equivalent to running

     texi2dvi -t @a4paper --pdf foo.texi

  Although one might wish that other options to 'texi2any' would take
effect, they don't.  For example, running 'texi2any --no-number-sections
--dvi foo.texi' still results in a DVI file with numbered sections.
(Perhaps this could be improved in the future, if requests are
received.)

  The actual name of the command that is invoked is specified by the
'TEXI2DVI' customization variable (*note Other Customization
Variables::).  As you might guess, the default is 'texi2dvi'.

  'texi2any' itself does not generate any output when it invokes
'texi2dvi'.


File: texinfo.info,  Node: Pointer Validation,  Next: Customization Variables,  Prev: texi2any Printed Output,  Up: Generic Translator texi2any

22.4 Pointer Validation
=======================

If you do not suppress pointer validation with the '--no-validate'
option or the '@novalidate' command in the source file (*note Use
TeX::), 'makeinfo' will check the validity of the Texinfo file.

  Most validation checks are different depending on whether node
pointers are explicitly or implicitly determined.  With explicit node
pointers, here is the list of what is checked:

  1. If a 'Next', 'Previous', or 'Up' node reference is a reference to a
     node in the current file and is not an external reference such as
     to '(dir)', then the referenced node must exist.

  2. Every node except the 'Top' node must have an 'Up' pointer.

  3. The node referenced by an 'Up' pointer must itself reference the
     current node through a menu item, unless the node referenced by
     'Up' has the form '(FILE)'.

  With implicit node pointers, the above error cannot occur, as such.
(Which is a major reason why we recommend using this feature of
'makeinfo', and not specifying any node pointers yourself.)

  Instead, 'makeinfo' checks that the tree constructed from the
document's menus matches the tree constructed from the sectioning
commands.  For example, if a chapter-level menu mentions nodes N1 and
N2, in that order, nodes N1 and N2 must be associated with '@section'
commands in the chapter.

  Finally, with both explicit and implicit node pointers, 'makeinfo'
checks that every node except the 'Top' node is referenced in a menu.


File: texinfo.info,  Node: Customization Variables,  Next: Internationalization of Document Strings,  Prev: Pointer Validation,  Up: Generic Translator texi2any

22.5 Customization Variables
============================

     Warning: These customization variable names and meanings may change
     in any Texinfo release.  We always try to avoid incompatible
     changes, but we cannot absolutely promise, since needs change over
     time.

  Many aspects of the behavior and output of 'texi2any' may be modified
by modifying so-called "customization variables".  These fall into four
general categories:

   * Those associated with @-commands; for example, '@documentlanguage'.

   * Those associated with command-line options; for example, the
     customization variable 'SPLIT' is associated with the '--split'
     command-line option, and 'TEXINFO_OUTPUT_FORMAT' allows specifying
     the output format.

   * Other ad hoc variables.

  Customization variables may set on the command line using
'--set-customization-variable 'VAR VALUE'' (quoting the variable/value
pair to the shell) or '--set-customization-variable VAR=VALUE' (using
'=').  A special VALUE is 'undef', which sets the variable to this
special "undefined" Perl value.

  The sections below give the details for each of these.

* Menu:

* Commands: Customization Variables for @-Commands.
* Options:  Customization Variables and Options.
* HTML:     HTML Customization Variables.
* Other:    Other Customization Variables.


File: texinfo.info,  Node: Customization Variables for @-Commands,  Next: Customization Variables and Options,  Up: Customization Variables

22.5.1 Customization Variables for @-Commands
---------------------------------------------

Each of the following @-commands has an associated customization
variable with the same name (minus the leading '@'):

     @allowcodebreaks @clickstyle @codequotebacktick
     @codequoteundirected @contents @deftypefnnewline
     @documentdescription @documentencoding @documentlanguage
     @evenfooting   @evenfootingmarks
     @evenheading   @evenheadingmarks
     @everyfooting  @everyfootingmarks
     @everyheading  @everyheadingmarks
     @exampleindent @firstparagraphindent
     @fonttextsize  @footnotestyle @frenchspacing @headings
     @kbdinputstyle @novalidate
     @oddfooting    @oddfootingmarks
     @oddheading    @oddheadingmarks
     @pagesizes     @paragraphindent
     @setchapternewpage @setcontentsaftertitlepage
     @setfilename
     @setshortcontentsaftertitlepage @shortcontents
     @urefbreakstyle @xrefautomaticsectiontitle

  Setting such a customization variable to a value 'foo' is similar to
executing '@CMD foo'.  It is not exactly the same, though, since any
side effects of parsing the Texinfo source are not redone.  Also, some
variables do not take Texinfo code when generating particular formats,
but an argument that is already formatted.  This is the case, for
example, for HTML for 'documentdescription'.


File: texinfo.info,  Node: Customization Variables and Options,  Next: HTML Customization Variables,  Prev: Customization Variables for @-Commands,  Up: Customization Variables

22.5.2 Customization Variables and Options
------------------------------------------

The following table gives the customization variables associated with
some command line options.  *Note Invoking texi2any::, for the meaning
of the options.

Option                               Variable
--------------------------------------------------------------------------
'--enable-encoding'                  'ENABLE_ENCODING'
'--document-language'                'documentlanguage'
'--error-limit'                      'ERROR_LIMIT'
'--fill-column'                      'FILLCOLUMN'
'--footnote-style'                   'footnotestyle'
'--force'                            'FORCE'
'--internal-links'                   'INTERNAL_LINKS'
'--macro-expand'                     'MACRO_EXPAND'
'--headers'                          'HEADERS', 'SHOW_MENU'
'--no-warn'                          'NO_WARN'
'--no-validate'                      'novalidate'
'--number-footnotes'                 'NUMBER_FOOTNOTES'
'--number-sections'                  'NUMBER_SECTIONS'
'--node-files'                       'NODE_FILES'
'--output'                           'OUT', 'OUTFILE', 'SUBDIR'
'--paragraph-indent'                 'paragraphindent'
'--silent'                           'SILENT'
'--split'                            'SPLIT'
'--split-size'                       'SPLIT_SIZE'
'--transliterate-file-names'         'TRANSLITERATE_FILE_NAMES'
'--verbose'                          'VERBOSE'

  Setting such a customization variable to a value 'foo' is essentially
the same as specifying the '--OPT=foo' if the option takes an argument,
or '--OPT' if not.

  In addition, the customization variable 'TEXINFO_OUTPUT_FORMAT' allows
specifying what 'makeinfo' outputs, either one of the usual output
formats that can be specified with options, or various other forms:

'docbook'
'dvi'
'dvipdf'
'html'
'info'
'pdf'
'plaintext'
'ps'
'xml'
     These correspond to the command-line options (and
     'TEXINFO_OUTPUT_FORMAT' environment variable values) of the same
     name.  *Note Invoking texi2any::.

'debugcount'
     Instead of generating a regular output format, output the count of
     bytes and lines obtained when converting to Info, and other
     information.

'debugtree'
     Instead of generating a regular output format, output a text
     representation of the tree obtained by parsing the input texinfo
     document.

'parse'
     Do only Texinfo source parsing; there is no output.

'plaintexinfo'
     Output the Texinfo source with all the macros, '@include' and
     '@value{}' expanded.  This is similar to setting '--macro-expand',
     but instead of being output in addition to the normal conversion,
     output of Texinfo is the main output.

'rawtext'
     Output raw text, with minimal formatting.  For example, footnotes
     are ignored and there is no paragraph filling.  This is used by the
     parser for file names and copyright text in HTML comments, for
     example.

'structure'
     Do only Texinfo source parsing and determination of the document
     structure; there is no output.

'texinfosxml'
     Output the document in TexinfoSXML representation, a syntax for
     writing XML data using Lisp S-expressions.

'textcontent'
     Output the text content only, stripped of commands; this is useful
     for spell checking or word counting, for example.  The trivial
     'detexinfo' script setting this is in the 'util' directory of the
     Texinfo source as an example.  It's one line:

          exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@"


File: texinfo.info,  Node: HTML Customization Variables,  Next: Other Customization Variables,  Prev: Customization Variables and Options,  Up: Customization Variables

22.5.3 HTML Customization Variables
-----------------------------------

This table gives the customization variables which apply to HTML output
only.  A few other customization variable apply to both HTML and other
output formats; those are given in the next section.

'AVOID_MENU_REDUNDANCY'
     For HTML.  If set, and the menu entry and menu description are the
     same, then do not print the menu description; default false.

'AFTER_BODY_OPEN'
     For HTML.  If set, the corresponding text will appear at the
     beginning of each HTML file; default unset.

'AFTER_ABOUT'
     For HTML, when an About-element is output.  If set, the
     corresponding text will appear at the end of the About element;
     default unset.

'AFTER_OVERVIEW'
'AFTER_TOC_LINES'
     For HTML.  If set, the corresponding text is output after the short
     table of contents for 'AFTER_OVERVIEW' and after the table of
     contents for 'AFTER_TOC_LINES'; otherwise, a default string is
     used.  At the time of writing, a '</div>' element is closed.

     In general, you should set 'BEFORE_OVERVIEW' if 'AFTER_OVERVIEW' is
     set, and you should set 'BEFORE_TOC_LINES' if 'AFTER_TOC_LINES' is
     set.

'BASEFILENAME_LENGTH'
     For HTML.  The maximum length of the base filenames; default 245.
     Changing this would make cross-manual references to such long node
     names invalid (*note HTML Xref Link Basics::).

'BEFORE_OVERVIEW'
'BEFORE_TOC_LINES'
     For HTML.  If set, the corresponding text is output before the
     short table of contents for 'BEFORE_OVERVIEW' and before the table
     of contents for 'BEFORE_TOC_LINES', otherwise a default string is
     used.  At the time of writing, a '<div ...>' element is opened.

     In general you should set 'AFTER_OVERVIEW' if 'BEFORE_OVERVIEW' is
     set, and you should set 'AFTER_TOC_LINES' if 'BEFORE_TOC_LINES' is
     set.

'BIG_RULE'
     For HTML.  Rule used after and before the top element and before
     special elements, but not for footers and headers; default '<hr>'.

'BODYTEXT'
     For HTML, the text appearing in '<body>'.  By default, set
     automatically, taking into account the document language (*note
     @documentlanguage::).

'CASE_INSENSITIVE_FILENAMES'
     For HTML.  Construct output file names as if the filesystem were
     case insensitive (*note HTML Splitting::); default false.

'CHAPTER_HEADER_LEVEL'
     For HTML.  Header formatting level used for chapter level
     sectioning commands; default '2'.

'CHECK_HTMLXREF'
     For HTML.  Check that manuals which are the target of external
     cross references (*note Four and Five Arguments::) are present in
     'htmlxref.cnf' (*note HTML Xref Configuration::); default false.

'COMPLEX_FORMAT_IN_TABLE'
     For HTML.  If set, use tables for indentation of complex formats;
     default false.

'CSS_LINES'
     For HTML.  CSS output, automatically determined by default (*note
     HTML CSS::).

'DATE_IN_HEADER'
     For HTML.  Put the document generation date in the header; off by
     default.

'DEF_TABLE'
     For HTML.  If set, a '<table>' construction for '@deffn' and
     similar @-commands is used (looking more like the TeX output),
     instead of definition lists; default false.

'DEFAULT_RULE'
     For HTML.  Rule used between element, except before and after the
     top element, and before special elements, and for footers and
     headers; default '<hr>'.

'DO_ABOUT'
     For HTML.  If set to 0 never do an About special element; if set to
     1 always do an About special element; default 0.

'EXTERNAL_DIR'
     For HTML.  Base directory for external manuals; default none.  It
     is better to use the general external cross reference mechanism
     (*note HTML Xref Configuration::) than this variable.

'EXTRA_HEAD'
     For HTML.  Additional text appearing within '<head>'; default
     unset.

'FOOTNOTE_END_HEADER_LEVEL'
     For HTML.  Header formatting level used for the footnotes header
     with the 'end' footnotestyle; default '4'.  *Note Footnote
     Styles::.

'FOOTNOTE_SEPARATE_HEADER_LEVEL'
     For HTML.  Header formatting level used for the footnotes header
     with the 'separate' footnotestyle; default '4'.  *Note Footnote
     Styles::.

'FRAMES'
     For HTML.  If set, a file describing the frame layout is generated,
     together with a file with the short table of contents; default
     false.

'FRAMESET_DOCTYPE'
     For HTML.  Same as DOCTYPE, but for the file containing the frame
     description.

'HEADER_IN_TABLE'
     For HTML.  Use tables for header formatting rather than a simple
     '<div>' element; default false.

'ICONS'
     For HTML.  Use icons for the navigation panel; default false.

'IMAGE_LINK_PREFIX'
     For HTML.  If set, the associated value is prepended to the image
     file links; default unset.

'INLINE_CSS_STYLE'
     For HTML.  Put CSS directly in HTML elements rather than at the
     beginning of the output; default false.

'KEEP_TOP_EXTERNAL_REF'
     For HTML.  If set, do not ignore 'Top' as the first argument for an
     external ref to a manual, as is done by default.  *Note Top Node
     Naming::.

'L2H'
     For HTML.  If set, 'latex2html' is used to convert '@math' and
     '@tex' sections; default false.  Best used with '--iftex'.

'L2H_CLEAN'
     (Relevant only if 'L2H' is set.)  If set, the intermediate files
     generated in relation with 'latex2html' are removed; default true.

'L2H_FILE'
     (Relevant only if 'L2H' is set.)  If set, the given file is used as
     'latex2html''s init file; default unset.

'L2H_HTML_VERSION'
     (Relevant only if 'L2H' is set.)  The HTML version used in the
     'latex2html' call; default unset.

'L2H_L2H'
     (Relevant only if 'L2H' is set.)  The program invoked as
     'latex2html'; default is 'latex2html'.

'L2H_SKIP'
     (Relevant only if 'L2H' is set.)  If set to a true value, the
     actual call to 'latex2html' is skipped; previously generated
     content is reused instead.  If set to 0, the cache is not used at
     all.  If set to 'undef', the cache is used for as many TeX
     fragments as possible and for any remaining the command is run.
     The default is 'undef'.

'L2H_TMP'
     (Relevant only if 'L2H' is set.)  Set the directory used for
     temporary files.  None of the file name components in this
     directory name may start with '.'; otherwise, 'latex2html' will
     fail (because of 'dvips').  The default is the empty string, which
     means the current directory.

'MAX_HEADER_LEVEL'
     For HTML.  Maximum header formatting level used (higher header
     formatting level numbers correspond to lower sectioning levels);
     default '4'.

'MENU_SYMBOL'
     For HTML.  Symbol used in front of menu entries when node names are
     used for menu entries formatting; default '&bull;'.

'MONOLITHIC'
     For HTML.  Output only one file including the table of contents.
     Set by default, but only relevant when the output is not split.

'NO_CSS'
     For HTML.  Do not use CSS; default false.  *Note HTML CSS::.

'NODE_FILE_EXTENSION'
     For HTML.  Extension for node files if 'NODE_FILENAMES' is set;
     default 'html'.

'PRE_ABOUT'
     For HTML, when an About element is output.  If set to a text
     string, this text will appear at the beginning of the About
     element.  If set to a reference on a subroutine, the result of the
     subroutine call will appear at the beginning of the About element.
     If not set (the default), default text is used.

'PRE_BODY_CLOSE'
     For HTML.  If set, the given text will appear at the footer of each
     HTML file; default unset.

'PROGRAM_NAME_IN_FOOTER'
     For HTML.  If set, output the program name and miscellaneous
     related information in the page footers; default false.

'SHORTEXTN'
     For HTML.  If set, use '.htm' as extension; default false.

'SHOW_TITLE'
     For HTML.  If set, output the title at the beginning of the
     document; default true.

'SIMPLE_MENU'
     For HTML.  If set, use a simple preformatted style for the menu,
     instead of breaking down the different parts of the menu; default
     false.  *Note Menu Parts::.

'TOC_LINKS'
     For HTML.  If set, links from headings to toc entries are created;
     default false.

'TOP_FILE'
     This file name may be used for the top-level file.  The extension
     is set appropriately, if necessary.  This is used to override the
     default, and is, in general, only taken into account when output is
     split, and for HTML.

'TOP_NODE_FILE'
     For HTML.  File name used for the Top node, if 'NODE_FILENAMES' is
     set; default is 'index'.

'TOP_NODE_FILE_TARGET'
     For HTML.  File name used for the Top node in cross references;
     default is 'index'.

'TOP_NODE_UP_URL'
     For HTML.  The url used for the Up pointer of the Top node; default
     'undef', meaning no link is generated.

'USE_ACCESSKEY'
     For HTML.  Use 'accesskey' in cross references; default true.

'USE_ISO'
     For HTML.  Use entities for doubled single-quote characters (*note
     Inserting Quotation Marks::), and '---' and '--' (*note
     Conventions::); default true.

'USE_LINKS'
     For HTML.  Generate '<link>' elements in the HTML '<head>' output;
     default true.

'USE_REL_REV'
     For HTML.  Use 'rel' in cross references; default true.

'VERTICAL_HEAD_NAVIGATION'
     For HTML.  If set, a vertical navigation panel is used; default
     false.

'WORDS_IN_PAGE'
     For HTML, with output split at nodes.  Specifies the approximate
     minimum page length at which a navigation panel is placed at the
     bottom of a page.  To avoid ever having the navigation buttons at
     the bottom of a page, set this to a sufficiently large number.  The
     default is 300.

'XREF_USE_FLOAT_LABEL'
     For HTML.  If set, for the float name in cross references, use the
     float label instead of the type followed by the float number (*note
     @float::).  The default is off.

'XREF_USE_NODE_NAME_ARG'
     For HTML.  Only relevant for cross reference commands with no cross
     reference name (second argument).  If set to 1, use the node name
     (first) argument in cross reference @-commands for the text
     displayed as the hyperlink.  If set to 0, use the node name if
     'USE_NODES' is set, otherwise the section name.  If set to 'undef',
     use the first argument in preformatted environments, otherwise use
     the node name or section name depending on 'USE_NODES'.  The
     default is 'undef'.


File: texinfo.info,  Node: Other Customization Variables,  Prev: HTML Customization Variables,  Up: Customization Variables

22.5.4 Other Customization Variables
------------------------------------

This table gives the remaining customization variables, which apply to
multiple formats, or affect global behavior, or otherwise don't fit into
the categories of the previous sections.

'CLOSE_QUOTE_SYMBOL'
     When a closing quote is needed, use this character; default
     '&rsquo;' in HTML, '&#8217;' in Docbook.  The default for Info is
     the same as 'OPEN_QUOTE_SYMBOL' (see below).

'CPP_LINE_DIRECTIVES'
     Recognize '#line' directives in a "preprocessing" pass (*note
     External Macro Processors::); on by default.

'DEBUG'
     If set, debugging output is generated; default is off (zero).

'DOCTYPE'
     For Docbook, HTML, XML.  Specifies the 'SystemLiteral', the
     entity's system identifier.  This is a URI which may be used to
     retrieve the entity, and identifies the canonical DTD for the
     document.  The default value is different for each of HTML, Docbook
     and Texinfo XML.

'DUMP_TEXI'
     For debugging.  If set, no conversion is done, only parsing and
     macro expansion.  If the option '--macro-expand' is set, the
     Texinfo source is also expanded to the corresponding file.  Default
     false.

'DUMP_TREE'
     For debugging.  If set, the tree constructed upon parsing a Texinfo
     document is output to standard error; default false.

'ENABLE_ENCODING_USE_ENTITY'
     For HTML, XML.  If '--enable-encoding' is set, and there is an
     entity corresponding with the letter or the symbol being output,
     prefer the entity.  Set by default for HTML, but not XML.

'EXTERNAL_CROSSREF_SPLIT'
     For cross references to other manuals, this determines if the other
     manual is considered to be split or monolithic.  By default, it is
     set based on the value of 'SPLIT'.  *Note HTML Xref::, and *note
     HTML Xref Configuration::.

'EXTENSION'
     The extension added to the output file name.  The default is
     different for each output format.

'FIX_TEXINFO'
     For "plain Texinfo" (see the 'PLAINTEXINFO' item).  If set to
     false, the resulting Texinfo does not have all errors corrected,
     such as missing '@end'; default true.  This variable is only
     relevant when expanding Texinfo; other converters always try to
     output something sane even if the input is erroneous.

'IGNORE_BEFORE_SETFILENAME'
     If set, begin outputting at '@setfilename', if '@setfilename' is
     present; default true.

'IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME'
     If set, spaces are ignored after an @-command that takes braces.
     Default on, matching the TeX behavior.

'INDEX_ENTRY_COLON'
     Symbol used between the index entry and the associated node or
     section; default ':'.

'INLINE_CONTENTS'
     For HTML.  If set, output the contents where the '@contents' and
     similar @-commands are located; default true.  This is Ignored if
     '@set*contentsaftertitlepage' is set (*note Contents::).

'INLINE_INSERTCOPYING'
     If set, '@insertcopying' is replaced by the '@copying' content
     (*note @copying::) as if '@insertcopying' were a user-defined
     macro; default false.

'INPUT_ENCODING_NAME'
     Normalized encoding name suitable for output.  Should be a usable
     charset name in HTML, typically one of the preferred IANA encoding
     names.  You should not need to use this variable, since it is set
     by '@documentencoding' (*note @documentencoding::).

'INPUT_PERL_ENCODING'
     Perl encoding used to process the Texinfo source.  You should not
     need to use that variable, since it is set by '@documentencoding'
     (*note @documentencoding::).

'MACRO_BODY_IGNORES_LEADING_SPACE'
     Ignore white space at the beginning of user defined macro body
     line, mimicking a TeX limitation (*note Macro Details::).  Default
     off.

'MAX_MACRO_CALL_NESTING'
     The maximal number of recursive calls of @-commands defined through
     '@rmacro'; default 100000.  The purpose of this variable is to
     avoid infinite recursions.

'MENU_ENTRY_COLON'
     Symbol used between the menu entry and the description; default
     ':'.

'NO_USE_SETFILENAME'
     If set, do not use '@setfilename' to set the document name;
     instead, base the output document name only on the input file name.
     The default is false.

'NODE_FILENAMES'
     If set, node names are used to construct file names.  By default,
     it is set if the output is split by node, or if 'NODE_FILES' is set
     and the output is split in any way.

'NODE_NAME_IN_INDEX'
     If set, use node names in index entries, otherwise prefer section
     names; default true.

'NODE_NAME_IN_MENU'
     If set, use node names in menu entries, otherwise prefer section
     names; default true.

'OPEN_QUOTE_SYMBOL'
     When an opening quote is needed, e.g., for '@samp' output, use the
     specified character; default '&lsquo;' for HTML, '&#8216;' for
     Docbook.  For Info, the default depends on the enabled document
     encoding (*note @documentencoding::); if no document encoding is
     set, or the encoding is US-ASCII, etc., ''' is used.  This
     character usually appears as an undirected single quote on modern
     systems.  If the document encoding is Unicode, the Info output uses
     a Unicode left quote.

'OUTPUT_ENCODING_NAME'
     Normalized encoding name used for output files.  Should be a usable
     charset name in HTML, typically one of the preferred IANA encoding
     names.  By default, if an input encoding is set (typically through
     '@documentencoding' or 'INPUT_ENCODING_NAME'), this information is
     used to set the output encoding name.  If no input encoding is
     specified, the default output encoding name may be set by the
     output format.  In particular, the XML-based formats use 'utf-8'
     for 'OUTPUT_ENCODING_NAME' if the encoding is not otherwise
     specified.  *Note @documentencoding::.

'OVERVIEW_LINK_TO_TOC'
     If set, the cross references in the Overview link to the
     corresponding Table of Contents entries; default true.

'PACKAGE'
'PACKAGE_VERSION'
'PACKAGE_AND_VERSION'
'PACKAGE_URL'
'PACKAGE_NAME'
     The implementation's short package name, package version, package
     name and version concatenated, package url, and full package name,
     respectively.  By default, these variables are all set through
     Autoconf, Automake, and 'configure'.

'PREFIX'
     The output file prefix, which is prepended to some output file
     names.  By default it is set by '@setfilename' or from the input
     file (*note @setfilename::).  How this value is used depends on the
     value of other customization variables or command line options,
     such as whether the output is split and 'NODE_FILENAMES'.  The
     default is unset.

'PROGRAM'
     Name of the program used.  By default, it is set to the name of the
     program launched, with a trailing '.pl' removed.

'RENAMED_NODES_FILE'
     If set, use the value for the renamed nodes description file.  If
     not set, the file is 'DOC_BASENAME-noderename.cnf'.  *Note HTML
     Xref Link Preservation::.

'RENAMED_NODES_REDIRECTIONS'
     If set, create redirection files for renamed nodes.  Set by default
     when generating HTML.

'SHOW_MENU'
     If set, Texinfo menus are output.  By default, it is set unless
     generating Docbook or if '--no-headers' is specified.

'SORT_ELEMENT_COUNT'
     If set, the name of a file to which a list of elements (nodes or
     sections, depending on the output format) is dumped, sorted by the
     number of lines they contain after removal of @-commands; default
     unset.  This is used by the program 'texi-elements-by-size' in the
     'util/' directory of the Texinfo source distribution (*note
     texi-elements-by-size::).

'SORT_ELEMENT_COUNT_WORDS'
     When dumping the elements-by-size file (see preceding item), use
     word counts instead of line counts; default false.

'TEST'
     If set to true, some variables which are normally dynamically
     generated anew for each run (date, program name, version) are set
     to fixed and given values.  This is useful to compare the output to
     a reference file, as is done for the tests.  The default is false.

'TEXI2DVI'
     Name of the command used to produce PostScript, PDF, and DVI;
     default 'texi2dvi'.  *Note texi2any Printed Output::.

'TEXI2HTML'
     Generate HTML and try to be as compatible as possible with
     'texi2html'; default false.

'TEXINFO_COLUMN_FOR_DESCRIPTION'
     Used with the 'indent_menu_descriptions' tree transformation,
     described below; default 32 (matching
     'texinfo-column-for-description' in Emacs)).

'TEXINFO_DTD_VERSION'
     For XML.  Version of the DTD used in the XML output preamble.  The
     default is set based on a variable in 'configure.ac'.

'TEXTCONTENT_COMMENT'
     For stripped text content output (i.e., when
     'TEXINFO_OUTPUT_FORMAT' is set to 'textcontent').  If set, also
     output comments.  Default false.

'TOP_NODE_UP'
     Up node for the Top node; default '(dir)'.

'TREE_TRANSFORMATIONS'
     The associated value is a comma separated list of transformations
     that can be applied to the Texinfo tree prior to outputting the
     result.  If more than one is specified, the ordering is irrelevant;
     each is always applied at the necessary point during processing.

     The only one executed by default is
     'move_index_entries_after_items' for HTML and Docbook output.
     Here's an example of updating the master menu in a document:

          makeinfo \
            -c TREE_TRANSFORMATIONS=regenerate_master_menu \
            -c PLAINTEXINFO=1 \
            mydoc.texi \
            -o /tmp/out

     (Caveat: Since 'PLAINTEXINFO' output does expand Texinfo macros and
     conditionals, it's necessary to remove any such differences before
     installing the updates in the original document.  This will be
     remedied in a future release.)

     The following transformations are currently supported (many are
     used in the 'pod2texi' utility distributed with Texinfo):

     'complete_tree_nodes_menus'
          Add menu entries or whole menus for nodes associated with
          sections of any level, based on the sectioning tree.

     'fill_gaps_in_sectioning'
          Adds empty '@unnumbered' in a tree to fill gaps in sectioning.
          For example, an '@unnumberedsec' will be inserted if an
          '@chapter' is followed by an '@subsection'.

     'indent_menu_descriptions'
          Reformat menus so that descriptions start at column
          'TEXINFO_COLUMN_DESCRIPTION'.

     'insert_nodes_for_sectioning_commands'
          Insert nodes for sectioning commands lacking a corresponding
          node.

     'move_index_entries_after_items'
          In '@enumerate' and '@itemize', move index entries appearing
          just before an '@item' to just after the '@item'.  Comment
          lines between index entries are moved too.  As mentioned, this
          is always done for HTML and Docbook output.

     'regenerate_master_menu'
          Update the Top node master menu, either replacing the (first)
          '@detailmenu' in the Top node menu, or creating it at the end
          of the Top node menu.

     'simple_menu'
          Mostly the same as 'SIMPLE_MENU': use a simple preformatted
          style for the menu.  It differs from setting 'SIMPLE_MENU' in
          that 'SIMPLE_MENU' only has an effect in HTML output.

'USE_NODES'
     Preferentially use nodes to decide where elements are separated.
     If set to false, preferentially use sectioning to decide where
     elements are separated.  The default is true.

'USE_NODE_TARGET'
     If set, use the node associated with a section for the section
     target in cross references; default true.

'USE_NUMERIC_ENTITY'
     For HTML and XML.  If set, use numeric entities instead of ASCII
     characters when there is no named entity.  By default, set to true
     for HTML.

'USE_UP_NODE_FOR_ELEMENT_UP'
     Fill in up sectioning direction with node direction when there is
     no sectioning up direction.  In practice this can only happen when
     there is no @top section.  Not set by default.

'USE_SETFILENAME_EXTENSION'
     Default is on for Info, off for other output.  If set, use exactly
     what '@setfilename' gives for the output file name, including the
     extension.  You should not need to explicitly set this variable.

'USE_TITLEPAGE_FOR_TITLE'
     Use the full '@titlepage' as the title, not a simple title string;
     default false.

'USE_UNIDECODE'
     If set to false, do not use the 'Text::Unidecode' Perl module to
     transliterate more characters; default true.


File: texinfo.info,  Node: Internationalization of Document Strings,  Next: Invoking pod2texi,  Prev: Customization Variables,  Up: Generic Translator texi2any

22.6 Internationalization of Document Strings
=============================================

'texi2any' writes fixed strings into the output document at various
places: cross references, page footers, the help page, alternate text
for images, and so on.  The string chosen depends on the value of the
'documentlanguage' at the time of the string being output (*note
@documentlanguage::, for the Texinfo command interface).

  The Gettext framework is used for those strings (*note
(gettext)Top::).  The 'libintl-perl' package is used as the 'gettext'
implementation; more specifically, the pure Perl implementation is used,
so Texinfo can support consistent behavior across all platforms and
installations, which would not otherwise be possible.  'libintl-perl' is
included in the Texinfo distribution and always installed, to ensure
that it is available if needed.  It is also possible to use the system
'gettext' (the choice can be made at build-time).

  The Gettext domain 'texinfo_document' is used for the strings.
Translated strings are written as Texinfo, and may include @-commands.
In translated strings, the varying parts of the string are not usually
denoted by '%s' and the like, but by '{arg_name}'.  (This convention is
common for 'gettext' in Perl and is fully supported in GNU Gettext;
*note Perl Format Strings: (gettext)perl-format.)  For example, in the
following, '{section}' will be replaced by the section name:

     see {section}

  These Perl-style brace format strings are used for two reasons: first,
changing the order of 'printf' arguments is only available since
Perl 5.8.0; second, and more importantly, the order of arguments is
unpredictable, since @-command expansion may lead to different orders
depending on the output format.

  The expansion of a translation string is done like this:

  1. First, the string is translated.  The locale is
     @DOCUMENTLANGUAGE'.'@DOCUMENTENCODING.

     If the @DOCUMENTLANGUAGE has the form 'll_CC', that is tried first,
     and then just 'll'.  If that does not exist, and the encoding is
     not 'us-ascii', then 'us-ascii' is tried.

     The idea is that if there is a 'us-ascii' encoding, it means that
     all the characters in the charset may be expressed as @-commands.
     For example, there is a 'fr.us-ascii' locale that can accommodate
     any encoding, since all the Latin 1 characters have associated
     @-commands.  On the other hand, Japanese has only a translation
     'ja.utf-8', since there are no @-commands for Japanese characters.

  2. Next, the string is expanded as Texinfo, and converted.  The
     arguments are substituted; for example, '{arg_name}' is replaced by
     the corresponding actual argument.

  In the following example, '{date}', '{program_homepage}' and
'{program}' are the arguments of the string.  Since they are used in
'@uref', their order is not predictable.  '{date}', '{program_homepage}'
and '{program}' are substituted after the expansion:

     Generated on @emph{{date}} using
     @uref{{program_homepage}, @emph{{program}}}.

  This approach is admittedly a bit complicated.  Its usefulness is that
it supports having translations available in different encodings for
encodings which can be covered by @-commands, and also specifying how
the formatting for some commands is done, independently of the output
format--yet still be language-dependent.  For example, the '@pxref'
translation string can be like this:

     see {node_file_href} section `{section}\' in @cite{{book}}

which allows for specifying a string independently of the output format,
while nevertheless with rich formatting it may be translated
appropriately in many languages.


File: texinfo.info,  Node: Invoking pod2texi,  Next: texi2html,  Prev: Internationalization of Document Strings,  Up: Generic Translator texi2any

22.7 Invoking pod2texi:
=======================

The 'pod2texi' program translates Perl pod documentation file(s) to
Texinfo.  There are two basic modes of operation: generating a
standalone manual from each input pod, or (if '--base-level=1' or higher
is given) generating Texinfo subfiles suitable for use with '@include'.

  Although ordinarily this documentation in the Texinfo manual would be
the best place to look, in this case we have documented all the options
and examples in the 'pod2texi' program itself, since it may be useful
outside of the rest of Texinfo.  Thus, please see the output of
'pod2texi --help', the version on the web at
<http://www.gnu.org/software/texinfo/manual/pod2texi.html>, etc.

  For an example of using 'pod2texi' to make Texinfo out of the Perl
documentation itself, see 'contrib/perldoc-all'
(http://cvs.savannah.gnu.org/viewvc/texinfo/contrib/perldoc-all/?root=texinfo)
in the Texinfo source distribution (the output is available at
<http://www.gnu.org/software/perl/manual>).


File: texinfo.info,  Node: texi2html,  Prev: Invoking pod2texi,  Up: Generic Translator texi2any

22.8 'texi2html': Ancestor of 'texi2any'
========================================

Conceptually, the 'texi2html' program is the parent of today's
'texi2any' program.  'texi2html' was developed independently, originally
by Lionel Cons in 1998; at the time, 'makeinfo' could not generate HTML.
Many other people contributed to 'texi2html' over the years.

  The present 'texi2any' uses little of the actual code of 'texi2html',
and has quite a different basic approach to the implementation (namely,
parsing the Texinfo document into a tree), but still, there is a family
resemblance.

  By design, 'texi2any' supports nearly all the features of 'texi2html'
in some way.  However, we did not attempt to maintain strict
compatibility, so no 'texi2html' executable is installed by the Texinfo
package.  An approximation can be run with an invocation like this
(available as 'util/texi2html' in the Texinfo source):

     texi2any --set-customization-variable TEXI2HTML=1 ...

but, to emphasize, this is _not_ a drop-in replacement for the previous
'texi2html'.  Here are the biggest differences:

   * Most blatantly, the command line options of 'texi2html' are now
     customization variables, for the most part.  A table of approximate
     equivalents is given below.

   * The program-level customization API is very different in
     'texi2any'.

   * Indices cannot be split.

   * Translated strings cannot be customized; we hope to introduce this
     feature in 'texi2any' in the future.

  Aside from the last, we do not intend to reimplement these
differences.  Therefore, the route forward for authors is alter manuals
and build processes as necessary to use the new features and methods of
'texi2any'.  The 'texi2html' maintainers (one of whom is the principal
author of 'texi2any') do not intend to make further releases.

  Here is the table showing 'texi2html' options and corresponding
'texi2any' customization variables.

'--toc-links'              'TOC_LINKS'
'--short-ext'              'SHORTEXTN'
'--prefix'                 'PREFIX'
'--short-ref'              'SHORT_REF'
'--idx-sum'                'IDX_SUMMARY'
'--def-table'              'DEF_TABLE'
'--ignore-preamble-text'   'IGNORE_PREAMBLE_TEXT'
'--html-xref-prefix'       'EXTERNAL_DIR'
'--l2h'                    'L2H'
'--l2h-l2h'                'L2H_L2H'
'--l2h-skip'               'L2H_SKIP'
'--l2h-tmp'                'L2H_TMP'
'--l2h-file'               'L2H_FILE'
'--l2h-clean'              'L2H_CLEAN'
'--use-nodes'              'USE_NODES'
'--monolithic'             'MONOLITHIC'
'--top-file'               'TOP_FILE'
'--toc-file'               'TOC_FILE'
'--frames'                 'FRAMES'
'--menu'                   'SHOW_MENU'
'--debug'                  'DEBUG'
'--doctype'                'DOCTYPE'
'--frameset-doctype'       'FRAMESET_DOCTYPE'
'--test'                   'TEST'

  Finally, any 'texi2html' users seeking more detailed information can
check the draft file 'doc/texi2oldapi.texi' in the Texinfo source
repository.  It consists mainly of very rough notes, but may still be
useful to some.


File: texinfo.info,  Node: Creating and Installing Info Files,  Next: Generating HTML,  Prev: Generic Translator texi2any,  Up: Top

23 Creating and Installing Info Files
*************************************

This chapter describes how to create and install Info files.  *Note Info
Files::, for general information about the file format itself.

* Menu:

* Creating an Info File::
* Installing an Info File::


File: texinfo.info,  Node: Creating an Info File,  Next: Installing an Info File,  Up: Creating and Installing Info Files

23.1 Creating an Info File
==========================

'makeinfo' is a program that converts a Texinfo file into an Info file,
HTML file, or plain text.  'texinfo-format-region' and
'texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to
Info.

  For information on installing the Info file in the Info system, *note
Installing an Info File::.

* Menu:

* makeinfo Advantages::         'makeinfo' provides better error checking.
* makeinfo in Emacs::           How to run 'makeinfo' from Emacs.
* texinfo-format commands::     Two Info formatting commands written
                                 in Emacs Lisp are an alternative
                                 to 'makeinfo'.
* Batch Formatting::            How to format for Info in Emacs Batch mode.
* Tag and Split Files::         How tagged and split files help Info
                                 to run better.


File: texinfo.info,  Node: makeinfo Advantages,  Next: makeinfo in Emacs,  Up: Creating an Info File

23.1.1 'makeinfo' Advantages
----------------------------

The 'makeinfo' utility creates an Info file from a Texinfo source
providing better error messages than either of the Emacs formatting
commands.  We recommend it.  The 'makeinfo' program is independent of
Emacs.  You can run 'makeinfo' in any of three ways: from an operating
system shell, from a shell inside Emacs, or by typing the 'C-c C-m C-r'
or the 'C-c C-m C-b' command in Texinfo mode in Emacs.

  The 'texinfo-format-region' and the 'texinfo-format-buffer' commands
may be useful if you cannot run 'makeinfo'.


File: texinfo.info,  Node: makeinfo in Emacs,  Next: texinfo-format commands,  Prev: makeinfo Advantages,  Up: Creating an Info File

23.1.2 Running 'makeinfo' Within Emacs
--------------------------------------

You can run 'makeinfo' in GNU Emacs Texinfo mode by using either the
'makeinfo-region' or the 'makeinfo-buffer' commands.  In Texinfo mode,
the commands are bound to 'C-c C-m C-r' and 'C-c C-m C-b' by default.

'C-c C-m C-r'
'M-x makeinfo-region'
     Format the current region for Info.

'C-c C-m C-b'
'M-x makeinfo-buffer'
     Format the current buffer for Info.

  When you invoke 'makeinfo-region' the output goes to a temporary
buffer.  When you invoke 'makeinfo-buffer' output goes to the file set
with '@setfilename' (*note @setfilename::).

  The Emacs 'makeinfo-region' and 'makeinfo-buffer' commands run the
'makeinfo' program in a temporary shell buffer.  If 'makeinfo' finds any
errors, Emacs displays the error messages in the temporary buffer.

  You can parse the error messages by typing 'C-x `' ('next-error').
This causes Emacs to go to and position the cursor on the line in the
Texinfo source that 'makeinfo' thinks caused the error.  *Note Running
'make' or Compilers Generally: (emacs)Compilation, for more information
about using the 'next-error' command.

  In addition, you can kill the shell in which the 'makeinfo' command is
running or make the shell buffer display its most recent output.

'C-c C-m C-k'
'M-x makeinfo-kill-job'
     Kill the current running 'makeinfo' job (from 'makeinfo-region' or
     'makeinfo-buffer').

'C-c C-m C-l'
'M-x makeinfo-recenter-output-buffer'
     Redisplay the 'makeinfo' shell buffer to display its most recent
     output.

(Note that the parallel commands for killing and recentering a TeX job
are 'C-c C-t C-k' and 'C-c C-t C-l'.  *Note Texinfo Mode Printing::.)

  You can specify options for 'makeinfo' by setting the
'makeinfo-options' variable with either the 'M-x customize' or the 'M-x
set-variable' command, or by setting the variable in your '.emacs'
initialization file.

  For example, you could write the following in your '.emacs' file:

     (setq makeinfo-options
          "--paragraph-indent=0 --no-split
           --fill-column=70 --verbose")

For more information, see
*note Easy Customization Interface: (emacs)Easy Customization,
*note Examining and Setting Variables: (emacs)Examining,
*note (emacs)Init File::, and
*note makeinfo Options::.


File: texinfo.info,  Node: texinfo-format commands,  Next: Batch Formatting,  Prev: makeinfo in Emacs,  Up: Creating an Info File

23.1.3 The 'texinfo-format...' Commands
---------------------------------------

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
file with the 'texinfo-format-region' command.  This formats the current
region and displays the formatted text in a temporary buffer called
'*Info Region*'.

  Similarly, you can format a buffer with the 'texinfo-format-buffer'
command.  This command creates a new buffer and generates the Info file
in it.  Typing 'C-x C-s' will save the Info file under the name
specified by the '@setfilename' line which must be near the beginning of
the Texinfo file.

'C-c C-e C-r'
'texinfo-format-region'
     Format the current region for Info.

'C-c C-e C-b'
'texinfo-format-buffer'
     Format the current buffer for Info.

  The 'texinfo-format-region' and 'texinfo-format-buffer' commands
provide you with some error checking, and other functions can provide
you with further help in finding formatting errors.  These procedures
are described in an appendix; see *note Catching Mistakes::.  However,
the 'makeinfo' program provides better error checking (*note makeinfo in
Emacs::).


File: texinfo.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Creating an Info File

23.1.4 Batch Formatting
-----------------------

You can format Texinfo files for Info using 'batch-texinfo-format' and
Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
including a shell inside of Emacs.  (*Note (emacs)Command Arguments::.)

  Here is a shell command to format all the files that end in '.texinfo'
in the current directory:

     emacs -batch -funcall batch-texinfo-format *.texinfo

Emacs processes all the files listed on the command line, even if an
error occurs while attempting to format some of them.

  Run 'batch-texinfo-format' only with Emacs in Batch mode as shown; it
is not interactive.  It kills the Batch mode Emacs on completion.

  'batch-texinfo-format' is convenient if you lack 'makeinfo' and want
to format several Texinfo files at once.  When you use Batch mode, you
create a new Emacs process.  This frees your current Emacs, so you can
continue working in it.  (When you run 'texinfo-format-region' or
'texinfo-format-buffer', you cannot use that Emacs for anything else
until the command finishes.)


File: texinfo.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Creating an Info File

23.1.5 Tag Files and Split Files
--------------------------------

If a Texinfo file has more than 30,000 bytes, 'texinfo-format-buffer'
automatically creates a tag table for its Info file; 'makeinfo' always
creates a tag table.  With a "tag table", Info can jump to new nodes
more quickly than it can otherwise.

  In addition, if the Texinfo file contains more than about 300,000
bytes, 'texinfo-format-buffer' and 'makeinfo' split the large Info file
into shorter "indirect" subfiles of about 300,000 bytes each.  Big files
are split into smaller files so that Emacs does not need to make a large
buffer to hold the whole of a large Info file; instead, Emacs allocates
just enough memory for the small, split-off file that is needed at the
time.  This way, Emacs avoids wasting memory when you run Info.  (Before
splitting was implemented, Info files were always kept short and
"include files" were designed as a way to create a single, large printed
manual out of the smaller Info files.  *Note Include Files::, for more
information.  Include files are still used for very large documents,
such as 'The Emacs Lisp Reference Manual', in which each chapter is a
separate file.)

  When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to the
files that were split off.  The split-off files are called "indirect"
files.

  The split-off files have names that are created by appending '-1',
'-2', '-3' and so on to the file name specified by the '@setfilename'
command.  The shortened version of the original file continues to have
the name specified by '@setfilename'.

  At one stage in writing this document, for example, the Info file was
saved as the file 'test-texinfo' and that file looked like this:

     Info file: test-texinfo,    -*-Text-*-
     produced by texinfo-format-buffer
     from file: new-texinfo-manual.texinfo

     ^_
     Indirect:
     test-texinfo-1: 102
     test-texinfo-2: 50422
     test-texinfo-3: 101300
     ^_^L
     Tag table:
     (Indirect)
     Node: overview^?104
     Node: info file^?1271
     Node: printed manual^?4853
     Node: conventions^?6855
     ...

(But 'test-texinfo' had far more nodes than are shown here.)  Each of
the split-off, indirect files, 'test-texinfo-1', 'test-texinfo-2', and
'test-texinfo-3', is listed in this file after the line that says
'Indirect:'.  The tag table is listed after the line that says 'Tag
table:'.

  In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or any permissions
text in the first file.  In the tag table, the number following the node
name records the location of the beginning of the node, in bytes from
the beginning of the (unsplit) output.

  If you are using 'texinfo-format-buffer' to create Info files, you may
want to run the 'Info-validate' command.  (The 'makeinfo' command does
such a good job on its own, you do not need 'Info-validate'.)  However,
you cannot run the 'M-x Info-validate' node-checking command on indirect
files.  For information on how to prevent files from being split and how
to validate the structure of the nodes, see *note Using Info-validate::.


File: texinfo.info,  Node: Installing an Info File,  Prev: Creating an Info File,  Up: Creating and Installing Info Files

23.2 Installing an Info File
============================

Info files are usually kept in the 'info' directory.  You can read Info
files using the standalone Info program or the Info reader built into
Emacs.  (*Note (info)Top::, for an introduction to Info.)

* Menu:

* Directory File::              The top level menu for all Info files.
* New Info File::               Listing a new Info file.
* Other Info Directories::      How to specify Info files that are
                                 located in other directories.
* Installing Dir Entries::      How to specify what menu entry to add
                                 to the Info directory.
* Invoking install-info::       'install-info' options.


File: texinfo.info,  Node: Directory File,  Next: New Info File,  Up: Installing an Info File

23.2.1 The Directory File 'dir'
-------------------------------

For Info to work, the 'info' directory must contain a file that serves
as a top level directory for the Info system.  By convention, this file
is called 'dir'.  (You can find the location of this file within Emacs
by typing 'C-h i' to enter Info and then typing 'C-x C-f' to see the
pathname to the 'info' directory.)

  The 'dir' file is itself an Info file.  It contains the top level menu
for all the Info files in the system.  The menu looks like this:

     * Menu:
     * Info:    (info).     Documentation browsing system.
     * Emacs:   (emacs).    The extensible, self-documenting
                           text editor.
     * Texinfo: (texinfo).  With one source file, make
                           either a printed manual using
                           @TeX{} or an Info file.
     ...

  Each of these menu entries points to the 'Top' node of the Info file
that is named in parentheses.  (The menu entry does not need to specify
the 'Top' node, since Info goes to the 'Top' node if no node name is
mentioned.  *Note Nodes in Other Info Files: Other Info Files.)

  Thus, the 'Info' entry points to the 'Top' node of the 'info' file and
the 'Emacs' entry points to the 'Top' node of the 'emacs' file.

  In each of the Info files, the 'Up' pointer of the 'Top' node refers
back to the 'dir' file.  For example, the line for the 'Top' node of the
Emacs manual looks like this in Info:

     File: emacs  Node: Top, Up: (DIR), Next: Distrib

In this case, the 'dir' file name is written in uppercase letters--it
can be written in either upper- or lowercase.  This is not true in
general, it is a special case for 'dir'.


File: texinfo.info,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory File,  Up: Installing an Info File

23.2.2 Listing a New Info File
------------------------------

To add a new Info file to your system, you must write a menu entry to
add to the menu in the 'dir' file in the 'info' directory.  For example,
if you were adding documentation for GDB, you would write the following
new entry:

     * GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a
colon.  The second part is the name of the Info file, in parentheses,
followed by a period.  The third part is the description.

  The name of an Info file often has a '.info' extension.  Thus, the
Info file for GDB might be called either 'gdb' or 'gdb.info'.  The Info
reader programs automatically try the file name both with and without
'.info'(1); so it is better to avoid clutter and not to write '.info'
explicitly in the menu entry.  For example, the GDB menu entry should
use just 'gdb' for the file name, not 'gdb.info'.

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

   (1) On MS-DOS/MS-Windows systems, Info will try the '.inf' extension
as well.


File: texinfo.info,  Node: Other Info Directories,  Next: Installing Dir Entries,  Prev: New Info File,  Up: Installing an Info File

23.2.3 Info Files in Other Directories
--------------------------------------

If an Info file is not in the 'info' directory, there are three ways to
specify its location:

  1. Write the pathname in the 'dir' file as the second part of the
     menu.

  2. Specify the Info directory name in the 'INFOPATH' environment
     variable in your '.profile' or '.cshrc' initialization file.  (Only
     you and others who set this environment variable will be able to
     find Info files whose location is specified this way.)

  3. If you are using Emacs, list the name of the file in a second 'dir'
     file, in its directory; and then add the name of that directory to
     the 'Info-directory-list' variable in your personal or site
     initialization file.

     This variable tells Emacs where to look for 'dir' files (the files
     must be named 'dir').  Emacs merges the files named 'dir' from each
     of the listed directories.  (In Emacs version 18, you can set the
     'Info-directory' variable to the name of only one directory.)

  For example, to reach a test file in the '/home/bob/info' directory,
you could add an entry like this to the menu in the standard 'dir' file:

     * Test: (/home/bob/info/info-test).  Bob's own test file.

In this case, the absolute file name of the 'info-test' file is written
as the second part of the menu entry.

  If you don't want to edit the system 'dir' file, you can tell Info
where to look by setting the 'INFOPATH' environment variable in your
shell startup file.  This works with both the Emacs and standalone Info
readers.

  Specifically, if you use a Bourne-compatible shell such as 'sh' or
'bash' for your shell command interpreter, you set the 'INFOPATH'
environment variable in the '.profile' initialization file; but if you
use 'csh' or 'tcsh', you set the variable in the '.cshrc' initialization
file.  On MS-DOS/MS-Windows systems, you must set 'INFOPATH' in your
'autoexec.bat' file or in the registry.  Each type of shell uses a
different syntax.

   * In a '.cshrc' file, you could set the 'INFOPATH' variable as
     follows:

          setenv INFOPATH .:~/info:/usr/local/emacs/info

   * In a '.profile' file, you would achieve the same effect by writing:

          INFOPATH=.:$HOME/info:/usr/local/emacs/info
          export INFOPATH

   * In a 'autoexec.bat' file, you write this command (note the use of
     ';' as the directory separator, and a different syntax for using
     values of other environment variables):

          set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info

The '.' indicates the current directory as usual.  Emacs uses the
'INFOPATH' environment variable to initialize the value of Emacs's own
'Info-directory-list' variable.  The standalone Info reader merges any
files named 'dir' in any directory listed in the 'INFOPATH' variable
into a single menu presented to you in the node called '(dir)Top'.

  However you set 'INFOPATH', if its last character is a colon (on
MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced by
the default (compiled-in) path.  This gives you a way to augment the
default path with new directories without having to list all the
standard places.  For example (using 'sh' syntax):

     INFOPATH=/home/bob/info:
     export INFOPATH

will search '/home/bob/info' first, then the standard directories.
Leading or doubled colons are not treated specially.

  When you create your own 'dir' file for use with 'Info-directory-list'
or 'INFOPATH', it's easiest to start by copying an existing 'dir' file
and replace all the text after the '* Menu:' with your desired entries.
That way, the punctuation and special CTRL-_ characters that Info needs
will be present.

  As one final alternative, which works only with Emacs Info, you can
change the 'Info-directory-list' variable.  For example:

     (add-hook 'Info-mode-hook '(lambda ()
     	     (add-to-list 'Info-directory-list
     			  (expand-file-name "~/info"))))


File: texinfo.info,  Node: Installing Dir Entries,  Next: Invoking install-info,  Prev: Other Info Directories,  Up: Installing an Info File

23.2.4 Installing Info Directory Files
--------------------------------------

When you install an Info file onto your system, you can use the program
'install-info' to update the Info directory file 'dir'.  Normally the
makefile for the package runs 'install-info', just after copying the
Info file into its proper installed location.

  In order for the Info file to work with 'install-info', you include
the commands '@dircategory' and '@direntry'...'@end direntry' in the
Texinfo source file.  Use '@direntry' to specify the menu entries to add
to the Info directory file, and use '@dircategory' to specify which part
of the Info directory to put it in.  Here is how these commands are used
in this manual:

     @dircategory Texinfo documentation system
     @direntry
     * Texinfo: (texinfo).           The GNU documentation format.
     * install-info: (texinfo)Invoking install-info. ...
     ...
     @end direntry

  Here's what this produces in the Info file:

     INFO-DIR-SECTION Texinfo documentation system
     START-INFO-DIR-ENTRY
     * Texinfo: (texinfo).           The GNU documentation format.
     * install-info: (texinfo)Invoking install-info. ...
     ...
     END-INFO-DIR-ENTRY

The 'install-info' program sees these lines in the Info file, and that
is how it knows what to do.

  Always use the '@direntry' and '@dircategory' commands near the
beginning of the Texinfo input, before the first '@node' command.  If
you use them later on in the input, 'install-info' will not notice them.

  'install-info' will automatically reformat the description of the menu
entries it is adding.  As a matter of convention, the description of the
main entry (above, 'The GNU documentation format') should start at
column 32, starting at zero (as in 'what-cursor-position' in Emacs).
This will make it align with most others.  Description for individual
utilities best start in column 48, where possible.  For more information
about formatting see the '--calign', '--align', and '--max-width'
options in *note Invoking install-info::.

  If you use '@dircategory' more than once in the Texinfo source, each
usage specifies the 'current' category; any subsequent '@direntry'
commands will add to that category.

  When choosing a category name for the '@dircategory' command, we
recommend consulting the Free Software Directory
(http://www.gnu.org/directory).  If your program is not listed there, or
listed incorrectly or incompletely, please report the situation to the
directory maintainers (<bug-directory@gnu.org>) so that the category
names can be kept in sync.

  Here are a few examples (see the 'util/dir-example' file in the
Texinfo distribution for large sample 'dir' file):

     Emacs
     Localization
     Printing
     Software development
     Software libraries
     Text creation and manipulation

  Each 'Invoking' node for every program installed should have a
corresponding '@direntry'.  This lets users easily find the
documentation for the different programs they can run, as with the
traditional 'man' system.

