This is texinfo.info, produced by texi2any version 6.1 from
texinfo.texi.

This manual is for GNU Texinfo (version 6.1, 6 February 2016), 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, 2014, 2015, 2016 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: Inserting an Atsign,  Next: Inserting Braces,  Up: Special Characters

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

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

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

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

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

12.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 using '@set' to change the
values of the corresponding variables 'txicodequoteundirected' and
'txicodequotebacktick'; 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

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

12.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' represents an '@'
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

12.3.2 Not Ending a Sentence
----------------------------

When a period, exclamation point or question mark is at the end of a
sentence, slightly more space is inserted after it in a typeset manual.

   Usually, Texinfo can determine automatically when a period ends a
sentence.  However, special commands are needed in some circumstances.
Use the '@:' command after a period, question mark, exclamation mark or
colon that should not be followed by extra space.  This is necessary in
the following situations:

  1. After a period that ends a lowercase abbreviation which is not at
     the end of a sentences.

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

The first line below shows the output, and for comparison, the second
line shows the spacing when the '@:' commands were not used.

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

   It may help you to remember what '@:' does by imagining that it
stands for an invisible lower-case character that stops a word ending in
a period.

   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 to be the end of a sentence, and no extra space is
inserted.

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

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

12.3.3 Ending a Sentence
------------------------

As mentioned above, Texinfo normally inserts additional space after the
end of a sentence.  It uses the same heuristic for this as TeX: a
sentence ends with a period, exclamation point, or question mark, either
preceded or 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.  Do not put braces after any of these
commands.  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 "closing punctuation" mentioned above is defined as a right
parenthesis (')', right bracket (']'), or right quote, either single or
double (''' and ''''; the many possible additional Unicode right quotes
are not included).  These characters can be thought of as invisible with
respect to whether a given period ends a sentence.  (This is the same
rule as TeX.)  For instance, the periods in 'foo.) Bar' and 'foo.'' Bar'
do end sentences.

   The meanings of '@:' and '@.', etc. in Texinfo are designed to work
well with the Emacs sentence motion commands (*note (emacs)Sentences::).
It may help to imagine that the '@' in '@.', etc., is an invisible
lower-case letter 'a' which makes an upper-case letter before it
immaterial for the purposes of deciding whether the period ends the
sentence.

   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.  Notably, this is the case
for code-like highlighting commands, '@var' arguments ending with a
capital letter, '@LaTeX', and '@TeX'.  For example, that sentence ended
with '... @code{@@TeX}.'; '@.' was not needed.  Similarly, 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

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

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

12.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<       caron/hacek/check 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 Subscripts and Superscripts,  Prev: Inserting Accents,  Up: Insertions

12.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://ctan.org/pkg/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://ctan.org/pkg/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>).  Texinfo does
not provide commands or configurations 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 Subscripts and Superscripts,  Next: Inserting Math,  Prev: Inserting Quotation Marks,  Up: Insertions

12.6 '@sub' and '@sup': Inserting Subscripts and Superscripts
=============================================================

You can insert subscripts and superscripts, in either text or math, with
the '@sub' and '@sup' commands.  (For other mathematical expressions,
see the next section.)  For example, here is a purely textual subscript
and superscript:

     here@sub{below}@sup{above}

produces:

     here_{below}^{above}

   Inside '@math', '@sub' and '@sup' produce mathematical subscripts and
superscripts.  This uses a different font in the TeX output (math italic
instead of text italic); it makes no difference in the other output
formats.  Here's an example:

     @math{e@sup{x}}

produces:

     e^{x}

   In Info and plain text, regardless of being used inside '@math',
'@sub{TEXT}' is output as '_{TEXT}' and '@sup{TEXT}' as '^{TEXT}',
including the literal braces (to mark the beginning and end of the
"script" text to the reader).

   When the output format (and display program) permit (TeX math, HTML),
the superscript is set above the subscript when both commands are given
consecutively.

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

12.7 '@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) = (b + a)}

This produces the following in Info and HTML:

     (a + b) = (b + a)

   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 use produce good mathematical formatting in any way (no use of
MathML, etc.).  The HTML output is enclosed by '<em>...</em>', but
nothing more.

   However, as far as the TeX output is concerned, plain TeX
mathematical commands are allowed in '@math', starting with '\'.  In
essence, '@math' switches into plain TeX math mode.  (Exception: the
plain TeX command '\sup', which typesets the mathematical operator name
'sup', must be accessed as '\mathopsup', due to the conflict with
Texinfo's '@sup' command.)

   This allows you 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.

   The '@sub' and '@sup' commands described in the previous section
produce subscripts and superscripts in HTML output as well as TeX; the
plain TeX characters '_' and '^' for subscripts and superscripts are
recognized by TeX inside '@math', but do nothing special in HTML or
other output formats.

   It's best to use '\' instead of '@' for any such mathematical
commands; otherwise, 'makeinfo' will complain.  On the other hand,
'makeinfo' does allow input with matching (but unescaped) braces, such
as 'k_{75}'; 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

12.8 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

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

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

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

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

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

12.8.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://ctan.org/pkg/eurosym>, among other places.  The distribution
includes installation instructions.

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

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

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

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

12.8.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,  Next: Inserting Unicode,  Prev: Glyphs for Text,  Up: Insertions

12.9 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

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

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

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

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

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

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

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

12.9.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: Inserting Unicode,  Prev: Glyphs for Programming,  Up: Insertions

12.10 Inserting Unicode: '@U'
=============================

The command '@U{HEX}' inserts a representation of the Unicode character
U+HEX.  For example, '@U{0132}' inserts the Dutch 'IJ' ligature (poorly
shown here as simply the two letters 'I' and 'J').

   The HEX value should be at least four hex digits; leading zeros are
_not_ added.  In general, HEX must specify a valid normal Unicode
character; e.g., U+10FFFF (the very last code point) is invalid by
definition, and thus cannot be inserted this way.

   '@U' is useful for inserting occasional glyphs for which Texinfo has
no dedicated command, while allowing the Texinfo source to remain purely
7-bit ASCII for maximum portability.

   This command has many limitations--the same limitations as inserting
Unicode characters in UTF-8 or another binary form.  First and most
importantly, TeX knows nothing about most of Unicode.  Supporting
specific additional glyphs upon request is possible, but it's not viable
for 'texinfo.tex' to support whole additional scripts (Japanese, Urdu,
...).  The '@U' command does nothing to change this.  If the specified
character is not supported in TeX, an error is given.  (*Note
@documentencoding::.)

   In HTML, XML, and Docbook, the output from '@U' is always an entity
reference of the form '&#xHEX;', as in '&#x0132;' for the example above.
This should work even when an HTML document uses some other encoding
(say, Latin 1) and the given character is not supported in that
encoding.

   In Info and plain text, if the document encoding is specified
explicitly to be UTF-8, the output will be the UTF-8 representation of
the character U+HEX (presuming it's a valid character).  In all other
cases, the output is the ASCII sequence 'U+HEX', as in the six ASCII
characters 'U+0132' for the example above.

   That's all.  No magic!

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

13 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

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

13.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 be useful within long urls or other identifiers
where TeX can't find a good place to break.  TeX will automatically
break urls at the natural places (*note URL Line Breaking::), so only
use '@/' if you need it.  '@/' has no effect in the other output format.

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

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

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

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

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

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

13.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.  A '@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

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

13.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 a '@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

14 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

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

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

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

     @defspec foobar (var [from to [inc]]) 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

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

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

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

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

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

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

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

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

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

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

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

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

15 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

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

     @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 usually be the
case for up-to-date distributions of the extended TeX programs 'etex'
(DVI output) and 'pdftex' (PDF output).  '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

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

The '@documentencoding' command declares the input document encoding,
and can also affect the encoding of the output.  Write it on a line by
itself, with a valid encoding specification following, near the
beginning of the file.

     @documentencoding ENC

   Texinfo supports 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-1'
'ISO-8859-15'
'ISO-8859-2'
     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,
according to the conventions of those formats.

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

   For maximum portability of Texinfo documents across the many
different user environments in the world, we recommend sticking to 7-bit
ASCII in the input unless your particular manual needs a substantial
amount of non-ASCII, e.g., it's written in German.  You can use the '@U'
command to insert an occasional needed character (*note Inserting
Unicode::).

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

16 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

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

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

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

16.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 a '@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 must
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, using
the '@kbdinputstyle' command inside a raw region is undefined.

   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

16.4 Inline Conditionals: '@inline', '@inlineifelse', '@inlineraw'
==================================================================

Texinfo provides a set of conditional commands with arguments given
within braces:

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

'@inlinefmtifelse{FORMAT, THEN-TEXT, ELSE-TEXT}'
     Process the Texinfo THEN-TEXT if FORMAT output is being generated;
     otherwise, process ELSE-TEXT.

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

   The supported FORMAT names are:

     docbook  html  info  plaintext  tex  xml

   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 arguments, as usual, but is _not_ ignored at the end of TEXT.

   To insert a literal at sign, left brace, or right brace in one of the
arguments, you must use the alphabetic commands '@atchar{}' (*note
Inserting an Atsign::), and '@lbracechar{}' or '@rbracechar{}' (*note
Inserting Braces::), or the parsing will become confused.

   With '@inlinefmtifelse', it is also necessary to use '@comma{}' to
avoid mistaking a ',' in the text for the delimiter.  With '@inlinefmt'
and '@inlineraw', '@comma{}' is not required (though it's fine to use
it), since these commands always have exactly two arguments.

   For TeX, the processed TEXT cannot contain newline-delimited
commands.  Text to be ignored (i.e., for non-TeX) can, though.

   Two other '@inline...' conditionals complement the '@ifset' and
'@ifclear' commands; see the next section.

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

16.5 Flags: '@set', '@clear', conditionals, 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.

'@inlineifset{FLAG, TEXT}'
     Brace-delimited version of '@ifset'.

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

'@inlineifclear{FLAG, TEXT}'
     Brace-delimited version of '@ifclear'.

* Menu:

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

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

16.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 a '@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 a '@value' command within a paragraph; but you must
write a '@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: @inlineifset @inlineifclear,  Prev: @set @value,  Up: @set @clear @value

16.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 a '@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: @inlineifset @inlineifclear,  Next: @value Example,  Prev: @ifset @ifclear,  Up: @set @clear @value

16.5.3 '@inlineifset' and '@inlineifclear'
------------------------------------------

'@inlineifset' and '@inlineifclear' provide brace-delimited alternatives
to the '@ifset' and '@ifclear' forms, similar to the other '@inline...'
Commands (*note Inline Conditionals::).  The same caveats about argument
parsing given there apply here too.

'@inlineifset{VAR, TEXT}'
     Process the Texinfo TEXT if the flag VAR is defined.

'@inlineifclear{VAR, TEXT}'
     Process the Texinfo TEXT if the flag VAR is not defined.

   Except for the syntax, their general behavior and purposes is the
same as with '@ifset' and '@ifclear', described in the previous section.


File: texinfo.info,  Node: @value Example,  Prev: @inlineifset @inlineifclear,  Up: @set @clear @value

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

          This is Edition @value{EDITION},
          last updated @value{UPDATED},
          of @cite{The GNU Make Manual},
          for @code{make}, version @value{VERSION}.
          @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

16.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, @samp{@@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 straightforward
for anyone 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
(standards)Releases::).

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

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

17 Defining New Texinfo Commands
********************************

Texinfo provides several ways to define new commands (in all cases, it's
not recommended to try redefining existing 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 any 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

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

   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

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

   The backslash itself can be quoted in macro arguments with another
backslash.  For example:

     @MACNAME {\\bleh}

will pass the argument '\bleh' to MACNAME.

   'makeinfo' also recognizes '\{' and '\}' sequences for curly braces,
but these are not recognized by the implementation in TeX.  There
should, however, rarely be a need for these, as they are only needed
when a macro argument contains unbalanced braces.

   If a macro is defined to take exactly one argument, it can be invoked
without any braces, taking all of the line after the macro name as the
argument.  For example:

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

produces:

     Twice: aah & aah.

In these arguments, there is no escaping of special characters, so each
'\' stands for itself.

   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

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

   * Arguments to macros taking more than one argument 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.

   * Texinfo commands in the expansion of a macro in the text of an
     index entry may end up being typeset as literal text (including an
     "@" sign), instead of being interpreted with their intended
     meaning.

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

   * Likewise, if you want to pass an argument with the Texinfo command
     '@,' (to produce a cedilla, see *note Inserting Accents::), you
     have to use '@value' or another work-around.  Otherwise, the comma
     may be taken as separating the arguments.  For example,

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

     produces:

          Franc,ois+.

   * Ending a macro body with '@c' may cause text following the macro
     invocation to be ignored as a comment in 'makeinfo'.  This is not
     the case when processing with TeX (in case you really want to
     comment out following text, use '@comment' instead).  This was
     often done to "comment out" an unwanted newline at the end of a
     macro body, but this is not necessary any more, as the final
     newline before '@end macro' is not included in the macro body
     anyway.

   * 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 a '@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

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

17.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' or '@tex' in your document.

   Write a '@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 a '@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

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

17.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, a '@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

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

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

18 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.
* @verbatiminclude::            Including a file verbatim.
* 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

18.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 a '@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

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

18.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 a
'@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: @verbatiminclude,  Prev: Include Files Requirements,  Up: Include Files

18.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-*-
     @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: @verbatiminclude,  Next: Include Files Evolution,  Prev: Sample Include File,  Up: Include Files

18.5 '@verbatiminclude' FILE: Include a File Verbatim
=====================================================

You can include the exact contents of a file in the document with the
'@verbatiminclude' command:

     @verbatiminclude FILENAME

   The contents of FILENAME is printed in a verbatim environment (*note
@verbatim::).  Generally, the file is printed exactly as it is, with all
special characters and white space retained.  No indentation is added;
if you want indentation, enclose the '@verbatiminclude' within
'@example' (*note @example::).

   The name of the file is taken literally, with a single exception:
'@value{VAR}' references are expanded.  This makes it possible to
include files in other directories within a distribution, for instance:

     @verbatiminclude @value{top_srcdir}/NEWS

(You still have to get 'top_srcdir' defined in the first place.)

   For a method on printing the file contents in a smaller font size,
see the end of the section on '@verbatim'.


File: texinfo.info,  Node: Include Files Evolution,  Prev: @verbatiminclude,  Up: Include Files

18.6 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

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

   In more detail, 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 texi2dvi::        The simplest way to format.
* Format with tex/texindex::    Formatting with explicit shell commands.
* 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 texi2dvi,  Up: Hardcopy

19.1 Use TeX
============

The typesetting program called TeX is used to format a Texinfo document
for printable output.  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 in
itself.


File: texinfo.info,  Node: Format with texi2dvi,  Next: Format with tex/texindex,  Prev: Use TeX,  Up: Hardcopy

19.2 Format with 'texi2dvi'
===========================

The 'texi2dvi' program takes care of all the steps for producing a TeX
DVI file from a Texinfo document.  Similarly, 'texi2pdf' produces a PDF
file.

   To run 'texi2dvi' or 'texi2pdf' on an input file 'foo.texi', do this
(where 'prompt$ ' is your shell prompt):

     prompt$ texi2dvi foo.texi
     prompt$ texi2pdf foo.texi

   As shown in this example, the input filenames to 'texi2dvi' and
'texi2pdf' must include any extension, such as '.texi'.  (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.)

   For a list of all the options, run 'texi2dvi --help'.  Some of the
options are discussed below.

   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 provided as a
convenience for AUC-TeX (*note (auctex)Top::, as it prefers to merely
prepend '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 program extant among
'dvipdfmx', 'dvipdfm', 'dvipdf', 'dvi2pdf', 'dvitopdf'.  This method
generally supports 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.  Normally
'texi2dvi' is able to guess the input file language by its contents and
file name extension; however, if it guesses wrong you can explicitly
specify the input language using '--language=LANG' command line option,
where LANG is either 'latex' or 'texinfo'.

   One useful option to 'texi2dvi' is '--command=CMD'.  This inserts CMD
on a line by itself, after a '@setfilename' line 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::).

   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, no line in the source file may
begin with the string '@c _texi2dvi' or the string '@c (_texi2dvi)'.

   'texi2dvi' takes the '--build=MODE' option to specify where the TeX
compilation takes place, and, as a consequence, how auxiliary files are
treated.  The build mode can also be set using the environment variable
'TEXI2DVI_BUILD_MODE'.  The valid values for MODE are:

'local'
     Compile in the current directory, leaving all the auxiliary files
     around.  This is the traditional TeX use.

'tidy'
     Compile in a local '*.t2d' directory, where the auxiliary files are
     left.  Output files are copied back to the original file.

     Using the 'tidy' mode brings several advantages:
        - the current directory is not cluttered with plethora of
          temporary files.
        - clutter can be even further reduced using '--build-dir=dir':
          all the '*.t2d' directories are stored there.
        - clutter can be reduced to zero using, e.g.,
          '--build-dir=/tmp/\$USER.t2d' or '--build-dir=\$HOME/.t2d'.
        - the output file is updated after every successful TeX run, for
          sake of concurrent visualization of the output.  In a 'local'
          build the viewer stops during the whole TeX run.
        - if the compilation fails, the previous state of the output
          file is preserved.
        - PDF and DVI compilation are kept in separate subdirectories
          preventing any possibility of auxiliary file incompatibility.

     On the other hand, because 'tidy' compilation takes place in
     another directory, occasionally TeX won't be able to find some
     files (e.g., when using '\graphicspath'): in that case, use '-I' to
     specify the additional directories to consider.

'clean'
     Same as 'tidy', but remove the auxiliary directory afterwards.
     Every compilation therefore requires the full cycle.

   'texi2dvi' will use 'etex' (or 'pdfetex') if it is available, because
it runs faster in some cases, and provides additional tracing
information when debugging 'texinfo.tex'.  Nevertheless, this extended
version of TeX is not required, and the DVI output is identical.  (These
days, 'pdftex' and 'pdfetex' are exactly the same, but we still run
'pdfetex' to cater to ancient TeX installations.)

   'texi2dvi' attempts to detect auxiliary files output by TeX, either
by using the '-recorder' option, or by scanning for '\openout' in the
log file that a run of TeX produces.  You may control how 'texi2dvi'
does this with the 'TEXI2DVI_USE_RECORDER' environment variable.  Valid
values are:

'yes'
     use the '-recorder' option, no checks.

'no'
     scan for '\openout' in the log file, no checks.

'yesmaybe'
     check whether '-recorder' option is supported, and if yes use it,
     otherwise check for tracing '\openout' in the log file is
     supported, and if yes use it, else it is an error.

'nomaybe'
     same as 'yesmaybe', except that the '\openout' trace in log file is
     checked first.

   The default is 'nomaybe'.  This environment variable is provided for
troubleshooting purposes, and may change or disappear in the future.


File: texinfo.info,  Node: Format with tex/texindex,  Next: Print with lpr,  Prev: Format with texi2dvi,  Up: Hardcopy

19.3 Format with 'tex'/'texindex'
=================================

You can do the basic formatting of a 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,
perhaps after a further conversion (see the previous section).

   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.  ('texi2dvi',
described in the previous section, runs 'tex' and 'texindex' as
necessary.)

   'tex' outputs unsorted index files under names following a standard
convention: the name of your main input file with any '.texi' or similar
extension replaced by the two letter index name.  For example, the raw
index output files for the input file 'foo.texi' would be, by default,
'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,
it's typical to 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; for example,
'foo.cps' is made from 'foo.cp'.  The '@printindex' command looks for a
file with that name (*note Printing Indices & Menus::).  TeX does not
read the raw index output file, and 'texindex' does not alter it.

   After you have sorted the indices, you need to rerun 'tex' on the
Texinfo file.  This regenerates the output 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.  (Alternatively, it's a
one-step process: run 'texi2dvi'; see the previous section.)

  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.

* Menu:

* Formatting Partial Documents::
* Details of texindex::


File: texinfo.info,  Node: Formatting Partial Documents,  Next: Details of texindex,  Up: Format with tex/texindex

19.3.1 Formatting Partial Documents
-----------------------------------

Sometimes you may wish to print a document while you know it is
incomplete, or to print just one chapter of a document.  In such a case,
the usual auxiliary files that TeX creates and warnings TeX gives about
undefined cross-references are just nuisances.  You can avoid them with
the '@novalidate' command, which you must give _before_ any sectioning
or cross-reference commands.

   Thus, the beginning of your file would look approximately like this:

     \input texinfo
     @novalidate
     ...

'@novalidate' also turns off validation in 'makeinfo', just like its
'--no-validate' option (*note Pointer Validation::).

   Furthermore, you need not run 'texindex' each time after you run
'tex'.  The 'tex' formatting command simply uses whatever sorted index
files happen to exist from a previous use of 'texindex'.  If those are
out of date, that is usually ok while you are creating or debugging a
document.


File: texinfo.info,  Node: Details of texindex,  Prev: Formatting Partial Documents,  Up: Format with tex/texindex

19.3.2 Details of 'texindex'
----------------------------

In Texinfo version 6, released in 2015, the 'texindex' program was
completely reimplemented.  The principal functional difference is that
index entries beginning with a left brace or right brace ('{' resp. '}')
can work properly.  For example, these simple index entries are
processed correctly, including the "index initial" shown in the index:

     @cindex @{
     @cindex @}
     ...
     @printindex cp

   However, to enable this behavior, it's necessary (for the time being)
to give a special option to TeX early in a source document:

     @tex
     \global\usebracesinindexestrue
     @end tex

   This is because the previous 'texindex' implementation aborted with
an incorrect error message ('No page number in \entry...') on such index
entries when handled in the normal way.  Therefore TeX wrote out an
incorrect "sort string" using the '|' character; this did not affect the
text of the entry, but the index initial was the incorrect '|', and
sorting was not perfect.

   Because of that fatal error, and because relatively few documents
have index entries beginning with braces, we want to provide some
transition time for installations to have the new 'texindex'.  At some
point in the future, we'll make '\usebracesinindexes' true by default
(the above TeX code will continue to work fine).

   Although not a matter of functionality, readers may be interested to
know that the new 'texindex' is a literate program
(<http://en.wikipedia.org/wiki/Literate_programming>) using Texinfo for
documentation and (portable) 'awk' for code.  A single source file,
'texindex/ti.twjr' in this case, produces the runnable program, a
printable document, and an online document.

   The system is called TexiWeb Jr. and was created by Arnold Robbins,
who also wrote the new 'texindex'.  Not coincidentally, he is also the
long-time maintainer of 'gawk' (GNU Awk, *note (gawk)Top::).  The file
'texindex/Makefile.am' shows example usage of the system.


File: texinfo.info,  Node: Print with lpr,  Next: Within Emacs,  Prev: Format with tex/texindex,  Up: Hardcopy

19.4 Print with 'lpr' from Shell
================================

The way to print a DVI file depends on your system installation.  Two
common ones are 'dvips foo.dvi -o' to make a PostScript file first and
then print that, and 'lpr -d foo.dvi' to print a DVI file directly.

   For example, the following commands will (probably) suffice to sort
the indices, format, and print this manual using the 'texi2dvi' shell
script (*note Format with texi2dvi::).

     texi2dvi texinfo.texi
     dvips texinfo.dvi -o
     lpr texinfo.ps

   Depending on the 'lpr' setup on your machine, you might able to
combine the last two steps into 'lpr -d texinfo.dvi'.

   You can also generate a PDF file by running 'texi2pdf' instead of
'texi2dvi'; a PDF is often directly printable.  Or you can generate a
PCL file by using 'dvilj' instead of 'dvips', if you have a printer that
prefers that format.

   'lpr' is a standard program on Unix systems, but it is usually absent
on MS-DOS/MS-Windows.  If so, just create a PostScript or PDF or PCL
file, whatever is most convenient, and print that in the usual way for
your machine (e.g., by sending to the appropriate port, usually 'PRN').


File: texinfo.info,  Node: Within Emacs,  Next: Texinfo Mode Printing,  Prev: Print with lpr,  Up: Hardcopy

19.5 Printing From an Emacs Shell
=================================

You can give formatting and printing commands from a shell within GNU
Emacs, just like any other shell command.  To create a shell within
Emacs, type 'M-x shell' (*note (emacs)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.

   For example, you can use 'texi2dvi' from an Emacs shell.  Here is one
way to use 'texi2pdf' to format and print 'Using and Porting GNU CC'
from a shell within Emacs:

     texi2pdf gcc.texi
     lpr gcc.pdf

   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

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

19.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.texi'
file, after the '@bye', you could put the following:

     Local Variables:
     compile-command: "texi2dvi gdb.texi"
     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

19.8 TeX Formatting Requirements Summary
========================================

Every Texinfo file that is to be input to TeX must begin with a '\input'
command:

     \input texinfo

This instructs TeX to load the macros it needs to process a Texinfo
file.

   Every Texinfo file must end with a line that terminates TeX's
processing and forces out unfinished pages:

     @bye

   Strictly speaking, these two lines are all a Texinfo file needs to be
processed successfully by TeX.

   Usually, however, the beginning includes a '@settitle' command to
define the title of the printed manual, a title page, a copyright page,
permissions, and a table of contents.  Besides '@bye', the end of a file
usually includes indices.  (Not to mention that 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

19.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 released for general use is available
from the usual GNU servers and mirrors:

     <http://ftp.gnu.org/gnu/texinfo/texinfo.tex>
     <http://ftpmirror.gnu.org/texinfo/texinfo.tex>

   The latest development version is available from the Texinfo source
repository:
     <http://svn.savannah.gnu.org/viewvc/trunk/doc/texinfo.tex?root=texinfo&view=log>

   'texinfo.tex' is essentially a standalone file, and compatibility is
of utmost concern; so, if you need or want to try a newer version than
came with your system, it nearly always suffices to download it and put
it anywhere that TeX will find it (first).  You can replace any existing
'texinfo.tex' with a newer version (of course saving the original in
case of disaster).

   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 use quotation marks other than those used in English, you'll need
to have the European Computer Modern fonts (e.g., 'ecrm1000') and (for
PDF output) CM-Super fonts (*note Inserting Quotation Marks::).

   To use the '@euro' command, you'll need the 'feym*' fonts (e.g.,
'feymr10').  *Note @euro::.

   All of the above files (and a whole lot more) should be installed by
default in a reasonable TeX installation.

   Optionally, you may create a file 'texinfo.cnf' for site
configuration.  This file is read by TeX at the beginning of a Texinfo
file.  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, 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 '.profile' or '.cshrc' file.

   Whether you use '.profile' or '.cshrc' depends on whether you use a
Bourne shell-compatible ('sh', 'bash', 'ksh', ...) or C shell-compatible
('csh', 'tcsh') command interpreter, respeictvely.

   In a '.profile' file, you could use the following 'sh' command
sequence:

     TEXINPUTS=.:/home/me/mylib:
     export TEXINPUTS

   While in a '.cshrc' file, you could use the following 'csh' command
sequence:

     setenv TEXINPUTS .:/home/me/mylib:

   On MS-DOS/MS-Windows, you'd do this (note the use of the ';'
character as directory separator, instead of ':'):

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


File: texinfo.info,  Node: Overfull hboxes,  Next: @smallbook,  Prev: Preparing for TeX,  Up: Hardcopy

19.10 Overfull "hboxes"
=======================

TeX is sometimes unable to typeset a line within the normal margins.
This most often occurs 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 identifier.  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; its default value is
'.15\hsize'.  '\hsize' is the TeX dimension containing the current line
width.

   For any overfull boxes you do have, 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

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

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

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


File: texinfo.info,  Node: Cropmarks and Magnification,  Next: PDF Output,  Prev: @pagesizes,  Up: Hardcopy

19.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
     \global\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

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

   * 'xpdf', a freely available standalone PDF reader
     (http://www.foolabs.com/xpdf/) for the X window system.

   * PDF at Wikipedia
     (https://en.wikipedia.org/wiki/Portable_Document_Format).

   At present, Texinfo does not provide '@ifpdf' or '@pdf' commands as
for the other output formats, since PDF documents contain many internal
low-level offsets and cross-references that would be hard or impossible
to specify at the Texinfo source level.

   PDF files require dedicated 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, notably including all the fonts that are used, so
it has its place.


File: texinfo.info,  Node: Obtaining TeX,  Prev: PDF Output,  Up: Hardcopy

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

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

20.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 very 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
all 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 implementation, 'texi2any', serves as the
reference implementation.  It 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 very
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 also in the 'util' source
directory.  (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

20.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'
'-D 'VAR VALUE''
     Cause the Texinfo variable VAR to be defined.  This is equivalent
     to '@set VAR' in the Texinfo file (*note @set @clear @value::).

     The argument to the option is always one word to the shell; if it
     contains internal whitespace, the first word is taken as the
     variable name and the remainder as the value.  For example, '-D
     'myvar someval'' is equivalent to '@set myvar someval'.

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

     Plain text output can be split similarly to HTML.  This may be
     useful for extracting sections from a Texinfo document and making
     them available as separate files.

'--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 and Options::.


File: texinfo.info,  Node: texi2any Printed Output,  Next: Pointer Validation,  Prev: Invoking texi2any,  Up: Generic Translator texi2any

20.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 output formats are requested, after
checking the validity of the input to give users the benefit of
'texi2any''s error checking.  If you don't want such error checking,
perhaps because your manual plays advanced TeX tricks together with
'texinfo.tex', just invoke 'texi2dvi' directly.

   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

except for the validity check.

   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 normal output when it invokes
'texi2dvi', only diagnostic messages.


File: texinfo.info,  Node: Pointer Validation,  Next: Customization Variables,  Prev: texi2any Printed Output,  Up: Generic Translator texi2any

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

20.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 a few
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.

   * Those associated with customizing the HTML output.

   * 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

20.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 @validatemenus @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

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

20.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, sets the
     HTML 'lang' attribute to 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_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_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 Referring
     to a Manual as a Whole::.

'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.  A url used for '(dir)' references; the default is
     'undef', meaning that the normal rules apply, typically leading to
     a link to 'dir.html' from an implicit or explicit reference to
     '(dir)' (*note HTML Xref::).  For more about the Top node pointers,
     *note First Node::.  For overriding the Up pointer in other
     formats, see 'TOP_NODE_UP' in *note Other Customization
     Variables::.

'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

20.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 true, matching the TeX behavior.

'INDEX_ENTRY_COLON'
     Symbol used between the index entry and the associated node or
     section; default ':'.

'INDEX_SPECIAL_CHARS_WARNING'
     If set, warn about ':' in index entry, as it leads to invalid
     entries in index menus in output Info files.  For Info and
     plaintext only.

'INFO_SPECIAL_CHARS_QUOTE'
     If set, whenever there are problematic characters for Info output
     in places such as node names or menu items, surround the part of
     the construct where they appear with quoting characters, as
     described in *note Info Format Specification::.  *Note Node Line
     Requirements::.

'INFO_SPECIAL_CHARS_WARNING'
     If set, warn about problematic constructs for Info output (such as
     the string '::') in node names, menu items, and cross-references;
     default true.  Do not warn about index entries, since parsing
     problems there don't prevent navigation; readers can still
     relatively easily find their way to the node in question.

'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)'.  For overriding the url
     in HTML output, see 'TOP_NODE_UP_URL' in *note HTML Customization
     Variables::.

'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; *note
     Invoking pod2texi::):

     '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...' sections in a tree to fill gaps in
          sectioning.  For example, an '@unnumberedsec' will be inserted
          if a '@chapter' is followed by a '@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

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

20.7 Invoking 'pod2texi': Convert POD to Texinfo
================================================

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://svn.savannah.gnu.org/viewvc/trunk/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

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

21 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

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

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

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

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

   A peculiarity of the 'texinfo-format-buffer' and
'texinfo-format-region' commands is that they do not indent (nor fill)
paragraphs that contain '@w' or '@*' commands.


File: texinfo.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Creating an Info File

21.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)Initial Options::.)

   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

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

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

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

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

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

21.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 (<http://directory.fsf.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.


File: texinfo.info,  Node: Invoking install-info,  Prev: Installing Dir Entries,  Up: Installing an Info File

21.2.5 Invoking 'install-info'
------------------------------

'install-info' inserts menu entries from an Info file into the top-level
'dir' file in the Info system (see the previous sections for an
explanation of how the 'dir' file works).  'install-info' also removes
menu entries from the 'dir' file.  It's most often run as part of
software installation, or when constructing a 'dir' file for all manuals
on a system.  Synopsis:

     install-info [OPTION...] [INFO-FILE [DIR-FILE]]

   If INFO-FILE or DIR-FILE are not specified, the options (described
below) that define them must be.  There are no compile-time defaults,
and standard input is never used.  'install-info' can read only one Info
file and write only one 'dir' file per invocation.

   If DIR-FILE (however specified) does not exist, 'install-info'
creates it if possible (with no entries).

   If any input file is compressed with 'gzip' (*note (gzip)Top::),
'install-info' automatically uncompresses it for reading.  And if
DIR-FILE is compressed, 'install-info' also automatically leaves it
compressed after writing any changes.  If DIR-FILE itself does not
exist, 'install-info' tries to open 'DIR-FILE.gz', 'DIR-FILE.xz',
'DIR-FILE.bz2', 'DIR-FILE.lz', and 'DIR-FILE.lzma', in that order.

   Options:

'--add-once'
     Specifies that the entry or entries will only be put into a single
     section.

'--align=COLUMN'
     Specifies the column that the second and subsequent lines of menu
     entry's description will be formatted to begin at.  The default for
     this option is '35'.  It is used in conjunction with the
     '--max-width' option.  COLUMN starts counting at 1.

'--append-new-sections'
     Instead of alphabetizing new sections, place them at the end of the
     DIR file.

'--calign=COLUMN'
     Specifies the column that the first line of menu entry's
     description will be formatted to begin at.  The default for this
     option is '33'.  It is used in conjunction with the '--max-width'
     option.  When the name of the menu entry exceeds this column,
     entry's description will start on the following line.  COLUMN
     starts counting at 1.

'--debug'
     Report what is being done.

'--delete'
     Delete the entries in INFO-FILE from DIR-FILE.  The file name in
     the entry in DIR-FILE must be INFO-FILE (except for an optional
     '.info' in either one).  Don't insert any new entries.  Any empty
     sections that result from the removal are also removed.

'--description=TEXT'
     Specify the explanatory portion of the menu entry.  If you don't
     specify a description (either via '--entry', '--item' or this
     option), the description is taken from the Info file itself.

'--dir-file=NAME'
     Specify file name of the Info directory file.  This is equivalent
     to using the DIR-FILE argument.

'--dry-run'
     Same as '--test'.

'--entry=TEXT'
     Insert TEXT as an Info directory entry; TEXT should have the form
     of an Info menu item line plus zero or more extra lines starting
     with whitespace.  If you specify more than one entry, they are all
     added.  If you don't specify any entries, they are determined from
     information in the Info file itself.

'--help'
     Display a usage message with basic usage and all available options,
     then exit successfully.

'--info-file=FILE'
     Specify Info file to install in the directory.  This is equivalent
     to using the INFO-FILE argument.

'--info-dir=DIR'
     Specify the directory where the directory file 'dir' resides.
     Equivalent to '--dir-file=DIR/dir'.

'--infodir=DIR'
     Same as '--info-dir'.

'--item=TEXT'
     Same as '--entry=TEXT'.  An Info directory entry is actually a menu
     item.

'--keep-old'
     Do not replace pre-existing menu entries.  When '--remove' is
     specified, this option means that empty sections are not removed.

'--max-width=COLUMN'
     Specifies the column that the menu entry's description will be
     word-wrapped at.  COLUMN starts counting at 1.

'--maxwidth=COLUMN'
     Same as '--max-width'.

'--menuentry=TEXT'
     Same as '--name'.

'--name=TEXT'
     Specify the name portion of the menu entry.  If the TEXT does not
     start with an asterisk '*', it is presumed to be the text after the
     '*' and before the parentheses that specify the Info file.
     Otherwise TEXT is taken verbatim, and is taken as defining the text
     up to and including the first period (a space is appended if
     necessary).  If you don't specify the name (either via '--entry',
     '--item' or this option), it is taken from the Info file itself.
     If the Info does not contain the name, the basename of the Info
     file is used.

'--no-indent'
     Suppress formatting of new entries into the 'dir' file.

'--quiet'
'--silent'
     Suppress warnings, etc., for silent operation.

'--remove'
     Same as '--delete'.

'--remove-exactly'
     Also like '--delete', but only entries if the Info file name
     matches exactly; '.info' and/or '.gz' suffixes are _not_ ignored.

'--section=SEC'
     Put this file's entries in section SEC of the directory.  If you
     specify more than one section, all the entries are added in each of
     the sections.  If you don't specify any sections, they are
     determined from information in the Info file itself.  If the Info
     file doesn't specify a section, the menu entries are put into the
     Miscellaneous section.

'--section REGEX SEC'
     Same as '--regex=REGEX --section=SEC --add-once'.

     'install-info' tries to detect when this alternate syntax is used,
     but does not always guess correctly.  Here is the heuristic that
     'install-info' uses:
       1. If the second argument to '--section' starts with a hyphen,
          the original syntax is presumed.

       2. If the second argument to '--section' is a file that can be
          opened, the original syntax is presumed.

       3. Otherwise the alternate syntax is used.

     When the heuristic fails because your section title starts with a
     hyphen, or it happens to be a filename that can be opened, the
     syntax should be changed to '--regex=REGEX --section=SEC
     --add-once'.

'--regex=REGEX'
     Put this file's entries into any section that matches REGEX.  If
     more than one section matches, all of the entries are added in each
     of the sections.  Specify REGEX using basic regular expression
     syntax, more or less as used with 'grep', for example.

'--test'
     Suppress updating of the directory file.

'--version'
     Display version information and exit successfully.


File: texinfo.info,  Node: Generating HTML,  Next: @-Command Details,  Prev: Creating and Installing Info Files,  Up: Top

22 Generating HTML
******************

'makeinfo' generates Info output by default, but given the '--html'
option, it will generate HTML, for web browsers and other programs.
This chapter gives some details on such HTML output.

   'makeinfo' has many user-definable customization variables with which
you can influence the HTML output.  *Note Customization Variables::.

   'makeinfo' can also produce output in XML and Docbook formats, but we
do not as yet describe these in detail.  *Note Output Formats::, for a
brief overview of all the output formats.

* Menu:

* HTML Translation::       Details of the HTML output.
* HTML Splitting::         How HTML output is split.
* HTML CSS::               Influencing HTML output with Cascading Style Sheets.
* HTML Xref::              Cross-references in HTML output.


File: texinfo.info,  Node: HTML Translation,  Next: HTML Splitting,  Up: Generating HTML

22.1 HTML Translation
=====================

First, the HTML generated by 'makeinfo' is standard HTML 4.  It also
tries to be compatible with earlier standards (e.g., HTML 2.0,
RFC-1866).  Thus, please report output from an error-free run of
'makeinfo' which has practical browser portability problems as a bug
(*note Reporting Bugs::).

   Some known exceptions to HTML 3.2 (using '--init-file=html32.pm'
produces strict HTML 3.2 output; *note Invoking texi2any::):

  1. HTML 3.2 tables are generated for the '@multitable' command (*note
     Multi-column Tables::), but they should degrade reasonably in
     browsers without table support.

  2. The HTML 4 'lang' attribute on the '<html>' attribute is used.

  3. Entities that are not in the HTML 3.2 standard are also used.

  4. CSS is used (*note HTML CSS::).

  5. A few HTML 4 elements are used: 'thead', 'abbr', 'acronym'.

   To achieve maximum portability and accessibility among browsers (both
graphical and text-based), systems, and users, the HTML output is
intentionally quite plain and generic.  It has always been our goal for
users to be able to customize the output to their wishes via CSS (*note
HTML CSS::) or other means (*note Customization Variables::.  If you
cannot accomplish a reasonable customization, feel free to report that.

   However, we do not wish to depart from our basic goal of widest
readability for the core output.  For example, using fancy CSS may make
it possible for the HTML output to more closely resemble the TeX output
in some details, but this result is not even close to being worth the
ensuing difficulties.

   It is also intentionally not our goal, and not even possible, to pass
through every conceivable validation test without any diagnostics.
Different validation tests have different goals, often about pedantic
enforcement of some standard or another.  Our overriding goal is to help
users, not blindly comply with standards.

   To repeat what was said at the top: please report output from an
error-free run of 'makeinfo' which has _practical_ browser portability
problems as a bug (*note Reporting Bugs::).

   A few other general points about the HTML output follow.

   *Navigation bar:* By default, a navigation bar is inserted at the
start of each node, analogous to Info output.  If the '--no-headers'
option is used, the navigation bar is only inserted at the beginning of
split files.  Header '<link>' elements in split output can support
Info-like navigation with browsers like Lynx and Emacs W3 which
implement this HTML 1.0 feature.

   *Footnotes:* for HTML, when the footnote style is 'end', or if the
output is not split, footnotes are put at the end of the output.  If the
footnoet style is set to 'separate', and the output is split, they are
placed in a separate file.  *Note Footnote Styles::.

   *Raw HTML*: 'makeinfo' will include segments of Texinfo source
between '@ifhtml' and '@end ifhtml' in the HTML output (but not any of
the other conditionals, by default).  Source between '@html' and '@end
html' is passed without change to the output (i.e., suppressing the
normal escaping of input '<', '>' and '&' characters which have special
significance in HTML).  *Note Conditional Commands::.


File: texinfo.info,  Node: HTML Splitting,  Next: HTML CSS,  Prev: HTML Translation,  Up: Generating HTML

22.2 HTML Splitting
===================

When splitting output at nodes (which is the default), 'makeinfo' writes
HTML output into (basically) one output file per Texinfo source '@node'.

   Each output file name is the node name with spaces replaced by '-''s
and special characters changed to '_' followed by their code point in
hex (*note HTML Xref::).  This is to make it portable and easy to use as
a filename.  In the unusual case of two different nodes having the same
name after this treatment, they are written consecutively to the same
file, with HTML anchors so each can be referred to independently.

   If 'makeinfo' is run on a system which does not distinguish case in
file names, nodes which are the same except for case (e.g., 'index' and
'Index') will also be folded into the same output file with anchors.
You can also pretend to be on a case insensitive filesystem by setting
the customization variable 'CASE_INSENSITIVE_FILENAMES'.

   It is also possible to split at chapters or sections with '--split'
(*note Invoking texi2any::).  In that case, the file names are
constructed after the name of the node associated with the relevant
sectioning command.  Also, unless '--no-node-files' is specified, a
redirection file is output for every node in order to more reliably
support cross-references to that manual (*note HTML Xref::).

   When splitting, the HTML output files are written into a
subdirectory, with the name chosen as follows:

  1. 'makeinfo' first tries the subdirectory with the base name from
     '@setfilename' (that is, any extension is removed).  For example,
     HTML output for '@setfilename gcc.info' would be written into a
     subdirectory named 'gcc/'.

  2. If that directory cannot be created for any reason, then 'makeinfo'
     tries appending '.html' to the directory name.  For example, output
     for '@setfilename texinfo' would be written to 'texinfo.html/'.

  3. If the 'NAME.html' directory can't be created either, 'makeinfo'
     gives up.

In any case, the top-level output file within the directory is always
named 'index.html'.

   Monolithic output ('--no-split') is named according to '@setfilename'
(with any '.info' extension is replaced with '.html'), '--output' (the
argument is used literally), or based on the input file name as a last
resort (*note @setfilename::).


File: texinfo.info,  Node: HTML CSS,  Next: HTML Xref,  Prev: HTML Splitting,  Up: Generating HTML

22.3 HTML CSS
=============

Cascading Style Sheets (CSS for short) is an Internet standard for
influencing the display of HTML documents: see
<http://www.w3.org/Style/CSS/>.

   By default, 'makeinfo' includes a few simple CSS commands to better
implement the appearance of some Texinfo environments.  Here are two of
them, as an example:

     pre.display { font-family:inherit }
     pre.smalldisplay { font-family:inherit; font-size:smaller }

   A full explanation of CSS is (far) beyond this manual; please see the
reference above.  In brief, however, the above tells the web browser to
use a 'smaller' font size for '@smalldisplay' text, and to use the same
font as the main document for both '@smalldisplay' and '@display'.  By
default, the HTML '<pre>' command uses a monospaced font.

   You can influence the CSS in the HTML output with two 'makeinfo'
options: '--css-include=FILE' and '--css-ref=URL'.

   The option '--css-ref=URL' adds to each output HTML file a '<link>'
tag referencing a CSS at the given URL.  This allows using external
style sheets.  You may find the file
'texi2html/examples/texinfo-bright-colors.css' useful for visualizing
the CSS elements in Texinfo output.

   The option '--css-include=FILE' includes the contents FILE in the
HTML output, as you might expect.  However, the details are somewhat
tricky, as described in the following, to provide maximum flexibility.

   The CSS file may begin with so-called '@import' directives, which
link to external CSS specifications for browsers to use when
interpreting the document.  Again, a full description is beyond our
scope here, but we'll describe how they work syntactically, so we can
explain how 'makeinfo' handles them.

   There can be more than one '@import', but they have to come first in
the file, with only whitespace and comments interspersed, no normal
definitions.  (Technical exception: a '@charset' directive may precede
the '@import''s.  This does not alter 'makeinfo''s behavior, it just
copies the '@charset' if present.)  Comments in CSS files are delimited
by '/* ... */', as in C.  An '@import' directive must be in one of these
two forms:

     @import url(http://example.org/foo.css);
     @import "http://example.net/bar.css";

   As far as 'makeinfo' is concerned, the crucial characters are the '@'
at the beginning and the semicolon terminating the directive.  When
reading the CSS file, it simply copies any such '@'-directive into the
output, as follows:

   * If FILE contains only normal CSS declarations, it is included after
     'makeinfo''s default CSS, thus overriding it.

   * If FILE begins with '@import' specifications (see below), then the
     'import''s are included first (they have to come first, according
     to the standard), and then 'makeinfo''s default CSS is included.
     If you need to override 'makeinfo''s defaults from an '@import',
     you can do so with the '! important' CSS construct, as in:
          pre.smallexample { font-size: inherit ! important }

   * If FILE contains both '@import' and inline CSS specifications, the
     '@import''s are included first, then 'makeinfo''s defaults, and
     lastly the inline CSS from FILE.

   * Any @-directive other than '@import' and '@charset' is treated as a
     CSS declaration, meaning 'makeinfo' includes its default CSS and
     then the rest of the file.

   If the CSS file is malformed or erroneous, 'makeinfo''s output is
unspecified.  'makeinfo' does not try to interpret the meaning of the
CSS file in any way; it just looks for the special '@' and ';'
characters and blindly copies the text into the output.  Comments in the
CSS file may or may not be included in the output.

   In addition to the possibilities offered by CSS, 'makeinfo' has many
user-definable customization variables with which you can influence the
HTML output.  *Note Customization Variables::.


File: texinfo.info,  Node: HTML Xref,  Prev: HTML CSS,  Up: Generating HTML

22.4 HTML Cross-references
==========================

Cross-references between Texinfo manuals in HTML format become, in the
end, a standard HTML '<a>' link, but the details are unfortunately
complex.  This section describes the algorithm used in detail, so that
Texinfo can cooperate with other programs, such as 'texi2html', by
writing mutually compatible HTML files.

   This algorithm may or may not be used for links _within_ HTML output
for a Texinfo file.  Since no issues of compatibility arise in such
cases, we do not need to specify this.

   We try to support references to such "external" manuals in both
monolithic and split forms.  A "monolithic" (mono) manual is entirely
contained in one file, and a "split" manual has a file for each node.
(*Note HTML Splitting::.)

   The algorithm was primarily devised by Patrice Dumas in 2003-04.

* Menu:

* Link Basics:       HTML Xref Link Basics.
* Node Expansion:    HTML Xref Node Name Expansion.
* Command Expansion: HTML Xref Command Expansion.
* 8-bit Expansion:   HTML Xref 8-bit Character Expansion.
* Mismatch:          HTML Xref Mismatch.
* Configuration:     HTML Xref Configuration. htmlxref.cnf.
* Preserving links:  HTML Xref Link Preservation. MANUAL-noderename.cnf.


File: texinfo.info,  Node: HTML Xref Link Basics,  Next: HTML Xref Node Name Expansion,  Up: HTML Xref

22.4.1 HTML Cross-reference Link Basics
---------------------------------------

For our purposes, an HTML link consists of four components: a host name,
a directory part, a file part, and a target part.  We always assume the
'http' protocol.  For example:

     http://HOST/DIR/FILE.html#TARGET

   The information to construct a link comes from the node name and
manual name in the cross-reference command in the Texinfo source (*note
Cross References::), and from "external information" (*note HTML Xref
Configuration::).

   We now consider each part in turn.

   The HOST is hardwired to be the local host.  This could either be the
literal string 'localhost', or, according to the rules for HTML links,
the 'http://localhost/' could be omitted entirely.

   The DIR and FILE parts are more complicated, and depend on the
relative split/mono nature of both the manual being processed and the
manual that the cross-reference refers to.  The underlying idea is that
there is one directory for Texinfo manuals in HTML, and a given MANUAL
is either available as a monolithic file 'MANUAL.html', or a split
subdirectory 'MANUAL/*.html'.  Here are the cases:

   * If the present manual is split, and the referent manual is also
     split, the directory is '../REFERENT/' and the file is the expanded
     node name (described later).

   * If the present manual is split, and the referent manual is mono,
     the directory is '../' and the file is 'REFERENT.html'.

   * If the present manual is mono, and the referent manual is split,
     the directory is 'REFERENT/' and the file is the expanded node
     name.

   * If the present manual is mono, and the referent manual is also
     mono, the directory is './' (or just the empty string), and the
     file is 'REFERENT.html'.

   Another rule, that only holds for filenames, is that base filenames
are truncated to 245 characters, to allow for an extension to be
appended and still comply with the 255-character limit which is common
to many filesystems.  Although technically this can be changed with the
'BASEFILENAME_LENGTH' customization variable (*note Other Customization
Variables::), doing so would make cross-manual references to such nodes
invalid.

   Any directory part in the filename argument of the source cross
reference command is ignored.  Thus, '@xref{,,,../foo}' and
'@xref{,,,foo}' both use 'foo' as the manual name.  This is because any
such attempted hardwiring of the directory is very unlikely to be useful
for both Info and HTML output.

   Finally, the TARGET part is always the expanded node name.

   Whether the present manual is split or mono is determined by user
option; 'makeinfo' defaults to split, with the '--no-split' option
overriding this.

   Whether the referent manual is split or mono, however, is another bit
of the external information (*note HTML Xref Configuration::).  By
default, 'makeinfo' uses the same form of the referent manual as the
present manual.

   Thus, there can be a mismatch between the format of the referent
manual that the generating software assumes, and the format it's
actually present in.  *Note HTML Xref Mismatch::.


File: texinfo.info,  Node: HTML Xref Node Name Expansion,  Next: HTML Xref Command Expansion,  Prev: HTML Xref Link Basics,  Up: HTML Xref

22.4.2 HTML Cross-reference Node Name Expansion
-----------------------------------------------

As mentioned in the previous section, the key part of the HTML cross
reference algorithm is the conversion of node names in the Texinfo
source into strings suitable for XHTML identifiers and filenames.  The
restrictions are similar for each: plain ASCII letters, numbers, and the
'-' and '_' characters are all that can be used.  (Although HTML anchors
can contain most characters, XHTML is more restrictive.)

   Cross-references in Texinfo can refer either to nodes or anchors
(*note @anchor::).  However, anchors are treated identically to nodes in
this context, so we'll continue to say "node" names for simplicity.

   A special exception: the Top node (*note The Top Node::) is always
mapped to the file 'index.html', to match web server software.  However,
the HTML _target_ is 'Top'.  Thus (in the split case):

     @xref{Top,,, emacs, The GNU Emacs Manual}.
     => <a href="emacs/index.html#Top">

  1. The standard ASCII letters (a-z and A-Z) are not modified.  All
     other characters may be changed as specified below.

  2. The standard ASCII numbers (0-9) are not modified except when a
     number is the first character of the node name.  In that case, see
     below.

  3. Multiple consecutive space, tab and newline characters are
     transformed into just one space.  (It's not possible to have
     newlines in node names with the current implementation, but we
     specify it anyway, just in case.)

  4. Leading and trailing spaces are removed.

  5. After the above has been applied, each remaining space character is
     converted into a '-' character.

  6. Other ASCII 7-bit characters are transformed into '_00XX', where XX
     is the ASCII character code in (lowercase) hexadecimal.  This
     includes '_', which is mapped to '_005f'.

  7. If the node name does not begin with a letter, the literal string
     'g_t' is prefixed to the result.  (Due to the rules above, that
     string can never occur otherwise; it is an arbitrary choice,
     standing for "GNU Texinfo".)  This is necessary because XHTML
     requires that identifiers begin with a letter.

   For example:

     @node A  node --- with _'%
     => A-node-_002d_002d_002d-with-_005f_0027_0025

   Example translations of common characters:

   * '_' => '_005f'
   * '-' => '_002d'
   * 'A node' => 'A-node'

   On case-folding computer systems, nodes differing only by case will
be mapped to the same file.  In particular, as mentioned above, Top
always maps to the file 'index.html'.  Thus, on a case-folding system,
Top and a node named 'Index' will both be written to 'index.html'.
Fortunately, the targets serve to distinguish these cases, since HTML
target names are always case-sensitive, independent of operating system.