This is texinfo, produced by makeinfo version 4.2 from texinfo.txi.

This manual is for GNU Texinfo (version 4.2, 28 March 2002), a
documentation system that can produce both online information and a
printed manual from a single source.

  Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
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.1 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 freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by
     the Free Software Foundation raise funds for GNU development."
  
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.
* texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
* texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo.         Translate Texinfo source.
END-INFO-DIR-ENTRY


File: texinfo,  Node: Three Arguments,  Next: Four and Five Arguments,  Prev: Two Arguments,  Up: xref

`@xref' with Three Arguments
----------------------------

  A third argument replaces the node name in the TeX output.  The third
argument should be the name of the section in the printed output, or
else state the topic discussed by that section.  Often, you will want to
use initial upper case letters so it will be easier to read when the
reference is printed.  Use a third argument when the node name is
unsuitable because of syntax or meaning.

  Remember to avoid placing a comma within the title or topic section of
a cross reference, or within any other section.  The formatters divide
cross references into arguments according to the commas; a comma within
a title or other section will divide it into two arguments.  In a
reference, you need to write a title such as "Clouds, Mist, and Fog"
without the commas.

  Also, remember to write a comma or period after the closing brace of
an `@xref' to terminate the cross reference.  In the following
examples, a clause follows a terminating comma.

The template is like this:

     @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.

For example,

     @xref{Electrical Effects, Lightning, Thunder and Lightning},
     for details.

produces

     *Note Lightning: Electrical Effects, for details.

and

     See Section 5.2 [Thunder and Lightning], page 57, for details.

  If a third argument is given and the second one is empty, then the
third argument serves both.  (Note how two commas, side by side, mark
the empty second argument.)

     @xref{Electrical Effects, , Thunder and Lightning},
     for details.

produces

     *Note Thunder and Lightning: Electrical Effects, for details.

and

     See Section 5.2 [Thunder and Lightning], page 57, for details.

  As a practical matter, it is often best to write cross references with
just the first argument if the node name and the section title are the
same, and with the first and third arguments if the node name and title
are different.

  Here are several examples from `The GNU Awk User's Guide':

     @xref{Sample Program}.
     @xref{Glossary}.
     @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
     @xref{Close Output, , Closing Output Files and Pipes},
        for more information.
     @xref{Regexp, , Regular Expressions as Patterns}.


File: texinfo,  Node: Four and Five Arguments,  Prev: Three Arguments,  Up: xref

`@xref' with Four and Five Arguments
------------------------------------

  In a cross reference, a fourth argument specifies the name of another
Info file, different from the file in which the reference appears, and
a fifth argument specifies its title as a printed manual.

  Remember that a comma or period must follow the closing brace of an
`@xref' command to terminate the cross reference.  In the following
examples, a clause follows a terminating comma.

The template is:

     @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
     INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.

For example,

     @xref{Electrical Effects, Lightning, Thunder and Lightning,
     weather, An Introduction to Meteorology}, for details.

produces

     *Note Lightning: (weather)Electrical Effects, for details.

The name of the Info file is enclosed in parentheses and precedes the
name of the node.

In a printed manual, the reference looks like this:

     See section "Thunder and Lightning" in An Introduction to
     Meteorology, for details.

The title of the printed manual is typeset in italics; and the
reference lacks a page number since TeX cannot know to which page a
reference refers when that reference is to another manual.

  Often, you will leave out the second argument when you use the long
version of `@xref'.  In this case, the third argument, the topic
description, will be used as the cross reference name in Info.

The template looks like this:

     @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
     PRINTED-MANUAL-TITLE}, for details.

which produces

     *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.

and

     See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.

For example,

     @xref{Electrical Effects, , Thunder and Lightning,
     weather, An Introduction to Meteorology}, for details.

produces

     *Note Thunder and Lightning: (weather)Electrical Effects,
     for details.

and

     See section "Thunder and Lightning" in An Introduction to
     Meteorology, for details.

  On rare occasions, you may want to refer to another Info file that is
within a single printed manual--when multiple Texinfo files are
incorporated into the same TeX run but make separate Info files.  In
this case, you need to specify only the fourth argument, and not the
fifth.


File: texinfo,  Node: Top Node Naming,  Next: ref,  Prev: xref,  Up: Cross References

Naming a `Top' Node
===================

  In a cross reference, you must always name a node.  This means that in
order to refer to a whole manual, you must identify the `Top' node by
writing it as the first argument to the `@xref' command.  (This is
different from the way you write a menu entry; see *Note Referring to
Other Info Files: Other Info Files.)  At the same time, to provide a
meaningful section topic or title in the printed cross reference
(instead of the word `Top'), you must write an appropriate entry for
the third argument to the `@xref' command.

Thus, to make a cross reference to `The GNU Make Manual', write:

     @xref{Top, , Overview, make, The GNU Make Manual}.

which produces

     *Note Overview: (make)Top.

and

     See section "Overview" in The GNU Make Manual.

In this example, `Top' is the name of the first node, and `Overview' is
the name of the first section of the manual.


File: texinfo,  Node: ref,  Next: pxref,  Prev: Top Node Naming,  Up: Cross References

`@ref'
======

  `@ref' is nearly the same as `@xref' except that it does not generate
a `See' in the printed output, just the reference itself.  This makes
it useful as the last part of a sentence.

For example,

     For more information, see @ref{Hurricanes}.

produces

     For more information, see *Note Hurricanes::.

and

     For more information, see Section 8.2 [Hurricanes], page 123.

  The `@ref' command sometimes leads writers to express themselves in a
manner that is suitable for a printed manual but looks awkward in the
Info format.  Bear in mind that your audience will be using both the
printed and the Info format.

For example,

     Sea surges are described in @ref{Hurricanes}.

produces

     Sea surges are described in Section 6.7 [Hurricanes], page 72.

in a printed document, and the following in Info:

     Sea surges are described in *Note Hurricanes::.

     *Caution:* You _must_ write a period, comma, or right parenthesis
     immediately after an `@ref' command with two or more arguments.
     Otherwise, Info will not find the end of the cross reference entry
     and its attempt to follow the cross reference will fail.  As a
     general rule, you should write a period or comma after every
     `@ref' command.  This looks best in both the printed and the Info
     output.


File: texinfo,  Node: pxref,  Next: inforef,  Prev: ref,  Up: Cross References

`@pxref'
========

  The parenthetical reference command, `@pxref', is nearly the same as
`@xref', but you use it _only_ inside parentheses and you do _not_ type
a comma or period after the command's closing brace.  The command
differs from `@xref' in two ways:

  1. TeX typesets the reference for the printed manual with a lower case
     `see' rather than an upper case `See'.

  2. The Info formatting commands automatically end the reference with a
     closing colon or period.

  Because one type of formatting automatically inserts closing
punctuation and the other does not, you should use `@pxref' _only_
inside parentheses as part of another sentence.  Also, you yourself
should not insert punctuation after the reference, as you do with
`@xref'.

  `@pxref' is designed so that the output looks right and works right
between parentheses both in printed output and in an Info file.  In a
printed manual, a closing comma or period should not follow a cross
reference within parentheses; such punctuation is wrong.  But in an
Info file, suitable closing punctuation must follow the cross reference
so Info can recognize its end.  `@pxref' spares you the need to use
complicated methods to put a terminator into one form of the output and
not the other.

With one argument, a parenthetical cross reference looks like this:

     ... storms cause flooding (@pxref{Hurricanes}) ...

which produces

     ... storms cause flooding (*Note Hurricanes::) ...

and

     ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
     ...

  With two arguments, a parenthetical cross reference has this template:

     ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...

which produces

     ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...

and

     ... (see Section NNN [NODE-NAME], page PPP) ...

  `@pxref' can be used with up to five arguments just like `@xref'
(*note `@xref': xref.).

     *Please note:* Use `@pxref' only as a parenthetical reference.  Do
     not try to use `@pxref' as a clause in a sentence.  It will look
     bad in either the Info file, the printed output, or both.

     Also, parenthetical cross references look best at the ends of
     sentences.  Although you may write them in the middle of a
     sentence, that location breaks up the flow of text.


File: texinfo,  Node: inforef,  Next: uref,  Prev: pxref,  Up: Cross References

`@inforef'
==========

  `@inforef' is used for cross references to Info files for which there
are no printed manuals.  Even in a printed manual, `@inforef' generates
a reference directing the user to look in an Info file.

  The command takes either two or three arguments, in the following
order:

  1. The node name.

  2. The cross reference name (optional).

  3. The Info file name.

Separate the arguments with commas, as with `@xref'.  Also, you must
terminate the reference with a comma or period after the `}', as you do
with `@xref'.

The template is:

     @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},

Thus,

     @inforef{Expert, Advanced Info commands, info},
     for more information.

produces

     *Note Advanced Info commands: (info)Expert,
     for more information.

and

     See Info file `info', node `Expert', for more information.

Similarly,

     @inforef{Expert, , info}, for more information.

produces

     *Note (info)Expert::, for more information.

and

     See Info file `info', node `Expert', for more information.

  The converse of `@inforef' is `@cite', which is used to refer to
printed works for which no Info form exists.  *Note `@cite': cite.


File: texinfo,  Node: uref,  Prev: inforef,  Up: Cross References

`@uref{URL[, TEXT][, REPLACEMENT]}'
===================================

  `@uref' produces a reference to a uniform resource locator (url).  It
takes one mandatory argument, the url, and two optional arguments which
control the text that is displayed.  In HTML output, `@uref' produces a
link you can follow.

  The second argument, if specified, is the text to display (the default
is the url itself); in Info and DVI output, but not in HTML output, the
url is also output.

  The third argument, on the other hand, if specified is also the text
to display, but the url is _not_ output in any format.  This is useful
when the text is already sufficiently referential, as in a man page.  If
the third argument is given, the second argument is ignored.

  The simple one argument form, where the url is both the target and the
text of the link:

     The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.

produces:
     The official GNU ftp site is `ftp://ftp.gnu.org/gnu'.

  An example of the two-argument form:
     The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
     holds programs and texts.

produces:
     The official GNU ftp site (ftp://ftp.gnu.org/gnu)
     holds programs and texts.

that is, the Info output is this:
     The official GNU ftp site (ftp://ftp.gnu.org/gnu)
     holds programs and texts.

and the HTML output is this:
     The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
     holds programs and texts.

  An example of the three-argument form:
     The @uref{/man.cgi/1/ls,,ls(1)} program ...

produces:
     The ls(1) program ...

but with HTML:
     The <a href="/man.cgi/1/ls">ls(1)</a> program ...

  To merely indicate a url without creating a link people can follow,
use `@url' (*note `@url': url.).

  Some people prefer to display url's in the unambiguous format:

     <URL:http://HOST/PATH>

You can use this form in the input file if you wish.  We feel it's not
necessary to clutter up the output with the extra `<URL:' and `>',
since any software that tries to detect url's in text already has to
detect them without the `<URL:' to be useful.


File: texinfo,  Node: Marking Text,  Next: Quotations and Examples,  Prev: Cross References,  Up: Top

Marking Words and Phrases
*************************

  In Texinfo, you can mark words and phrases in a variety of ways.  The
Texinfo formatters use this information to determine how to highlight
the text.  You can specify, for example, whether a word or phrase is a
defining occurrence, a metasyntactic variable, or a symbol used in a
program.  Also, you can emphasize text, in several different ways.

* Menu:

* Indicating::                  How to indicate definitions, files, etc.
* Emphasis::                    How to emphasize text.


File: texinfo,  Node: Indicating,  Next: Emphasis,  Prev: Marking Text,  Up: Marking Text

Indicating Definitions, Commands, etc.
======================================

  Texinfo has commands for indicating just what kind of object a piece
of text refers to.  For example, metasyntactic variables are marked by
`@var', and code by `@code'.  Since the pieces of text are labelled by
commands that tell what kind of object they are, it is easy to change
the way the Texinfo formatters prepare such text.  (Texinfo is an
_intentional_ formatting language rather than a _typesetting_
formatting language.)

  For example, in a printed manual, code is usually illustrated in a
typewriter font; `@code' tells TeX to typeset this text in this font.
But it would be easy to change the way TeX highlights code to use
another font, and this change would not affect how keystroke examples
are highlighted.  If straight typesetting commands were used in the body
of the file and you wanted to make a change, you would need to check
every single occurrence to make sure that you were changing code and
not something else that should not be changed.

* Menu:

* Useful Highlighting::         Highlighting provides useful information.
* code::                        Indicating program code.
* kbd::                         Showing keyboard input.
* key::                         Specifying keys.
* samp::                        A literal sequence of characters.
* verb::                        A verbatim sequence of characters.
* var::                         Indicating metasyntactic variables.
* env::                         Indicating environment variables.
* file::                        Indicating file names.
* command::                     Indicating command names.
* option::                      Indicating option names.
* dfn::                         Specifying definitions.
* cite::                        Referring to books not in the  Info system.
* acronym::                     Indicating acronyms.
* url::                         Indicating a World Wide Web reference.
* email::                       Indicating an electronic mail address.


File: texinfo,  Node: Useful Highlighting,  Next: code,  Prev: Indicating,  Up: Indicating

Highlighting Commands are Useful
--------------------------------

  The highlighting commands can be used to extract useful information
from the file, such as lists of functions or file names.  It is
possible, for example, to write a program in Emacs Lisp (or a keyboard
macro) to insert an index entry after every paragraph that contains
words or phrases marked by a specified command.  You could do this to
construct an index of functions if you had not already made the entries.

  The commands serve a variety of purposes:

`@code{SAMPLE-CODE}'
     Indicate text that is a literal example of a piece of a program.

`@kbd{KEYBOARD-CHARACTERS}'
     Indicate keyboard input.

`@key{KEY-NAME}'
     Indicate the conventional name for a key on a keyboard.

`@samp{TEXT}'
     Indicate text that is a literal example of a sequence of
     characters.

`@var{METASYNTACTIC-VARIABLE}'
     Indicate a metasyntactic variable.

`@env{ENVIRONMENT-VARIABLE}'
     Indicate an environment variable.

`@file{FILE-NAME}'
     Indicate the name of a file.

`@command{COMMAND-NAME}'
     Indicate the name of a command.

`@option{OPTION}'
     Indicate a command-line option.

`@dfn{TERM}'
     Indicate the introductory or defining use of a term.

`@cite{REFERENCE}'
     Indicate the name of a book.

`@acronym{ACRONYM}'
     Indicate an acronym.

`@url{UNIFORM-RESOURCE-LOCATOR}'
     Indicate a uniform resource locator for the World Wide Web.

`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
     Indicate an electronic mail address.


File: texinfo,  Node: code,  Next: kbd,  Prev: Useful Highlighting,  Up: Indicating

`@code'{SAMPLE-CODE}
--------------------

  Use the `@code' command to indicate text that is a piece of a program
and which consists of entire syntactic tokens.  Enclose the text in
braces.

  Thus, you should use `@code' for an expression in a program, for the
name of a variable or function used in a program, or for a keyword in a
programming language.

  Use `@code' for command names in languages that resemble programming
languages, such as Texinfo.  For example, `@code' and `@samp' are
produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo
source, respectively.

  It is incorrect to alter the case of a word inside an `@code' command
when it appears at the beginning of a sentence.  Most computer
languages are case sensitive.  In C, for example, `Printf' is different
from the identifier `printf', and most likely is a misspelling of it.
Even in languages which are not case sensitive, it is confusing to a
human reader to see identifiers spelled in different ways.  Pick one
spelling and always use that.  If you do not want to start a sentence
with a command name written all in lower case, you should rearrange the
sentence.

  In the printed manual, `@code' causes TeX to typeset the argument in
a typewriter face.  In the Info file, it causes the Info formatting
commands to use single quotation marks around the text.

  For example,

     The function returns @code{nil}.

produces this in the printed manual:

     The function returns `nil'.

  Here are some cases for which it is preferable not to use `@code':

   * For shell command names such as `ls' (use `@command').

   * For shell options such as `-c' when such options stand alone (use
     `@option').

   * Also, an entire shell command often looks better if written using
     `@samp' rather than `@code'.  In this case, the rule is to choose
     the more pleasing format.

   * For environment variable such as `TEXINPUTS' (use `@env').

   * For a string of characters shorter than a syntactic token.  For
     example, if you are writing about `goto-ch', which is just a part
     of the name for the `goto-char' Emacs Lisp function, you should use
     `@samp'.

   * In general, when writing about the characters used in a token; for
     example, do not use `@code' when you are explaining what letters
     or printable symbols can be used in the names of functions.  (Use
     `@samp'.)  Also, you should not use `@code' to mark text that is
     considered input to programs unless the input is written in a
     language that is like a programming language.  For example, you
     should not use `@code' for the keystroke commands of GNU Emacs (use
     `@kbd' instead) although you may use `@code' for the names of the
     Emacs Lisp functions that the keystroke commands invoke.


  Since `@command', `@option', and `@env' were introduced relatively
recently, it is acceptable to use `@code' or `@samp' for command names,
options, and environment variables.  The new commands allow you to
express the markup more precisely, but there is no real harm in using
the older commands, and of course the long-standing manuals do so.


File: texinfo,  Node: kbd,  Next: key,  Prev: code,  Up: Indicating

`@kbd'{KEYBOARD-CHARACTERS}
---------------------------

  Use the `@kbd' command for characters of input to be typed by users.
For example, to refer to the characters `M-a', write

     @kbd{M-a}

and to refer to the characters `M-x shell', write

     @kbd{M-x shell}

  The `@kbd' command has the same effect as `@code' in Info, but by
default produces a different font (slanted typewriter instead of normal
typewriter) in the printed manual, so users can distinguish the
characters they are supposed to type from those the computer outputs.

  Since the usage of `@kbd' varies from manual to manual, you can
control the font switching with the `@kbdinputstyle' command.  This
command has no effect on Info output.  Write this command at the
beginning of a line with a single word as an argument, one of the
following:
`code'
     Always use the same font for `@kbd' as `@code'.

`example'
     Use the distinguishing font for `@kbd' only in `@example' and
     similar environments.

`distinct'
     (the default) Always use the distinguishing font for `@kbd'.

  You can embed another @-command inside the braces of an `@kbd'
command.  Here, for example, is the way to describe a command that
would be described more verbosely as "press an `r' and then press the
<RET> key":

     @kbd{r @key{RET}}

This produces: `r <RET>'

  You also use the `@kbd' command if you are spelling out the letters
you type; for example:

     To give the @code{logout} command,
     type the characters @kbd{l o g o u t @key{RET}}.

This produces:

     To give the `logout' command, type the characters `l o g o u t
     <RET>'.

  (Also, this example shows that you can add spaces for clarity.  If you
really want to mention a space character as one of the characters of
input, write `@key{SPC}' for it.)


File: texinfo,  Node: key,  Next: samp,  Prev: kbd,  Up: Indicating

`@key'{KEY-NAME}
----------------

  Use the `@key' command for the conventional name for a key on a
keyboard, as in:

     @key{RET}

  You can use the `@key' command within the argument of an `@kbd'
command when the sequence of characters to be typed includes one or
more keys that are described by name.

  For example, to produce `C-x <ESC>' you would type:

     @kbd{C-x @key{ESC}}

  Here is a list of the recommended names for keys:

    SPC
          Space

    RET
          Return

    LFD
          Linefeed (however, since most keyboards nowadays do not have
          a Linefeed key, it might be better to call this character
          `C-j'.

    TAB
          Tab

    BS
          Backspace

    ESC
          Escape

    DEL
          Delete

    SHIFT
          Shift

    CTRL
          Control

    META
          Meta

  There are subtleties to handling words like `meta' or `ctrl' that are
names of modifier keys.  When mentioning a character in which the
modifier key is used, such as `Meta-a', use the `@kbd' command alone;
do not use the `@key' command; but when you are referring to the
modifier key in isolation, use the `@key' command.  For example, write
`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.


File: texinfo,  Node: samp,  Next: verb,  Prev: key,  Up: Indicating

`@samp'{TEXT}
-------------

  Use the `@samp' command to indicate text that is a literal example or
`sample' of a sequence of characters in a file, string, pattern, etc.
Enclose the text in braces.  The argument appears within single
quotation marks in both the Info file and the printed manual; in
addition, it is printed in a fixed-width font.

     To match @samp{foo} at the end of the line,
     use the regexp @samp{foo$}.

produces

     To match `foo' at the end of the line, use the regexp `foo$'.

  Any time you are referring to single characters, you should use
`@samp' unless `@kbd' or `@key' is more appropriate.  Also, you may use
`@samp' for entire statements in C and for entire shell commands--in
this case, `@samp' often looks better than `@code'.  Basically, `@samp'
is a catchall for whatever is not covered by `@code', `@kbd', or `@key'.

  Only include punctuation marks within braces if they are part of the
string you are specifying.  Write punctuation marks outside the braces
if those punctuation marks are part of the English text that surrounds
the string.  In the following sentence, for example, the commas and
period are outside of the braces:

     In English, the vowels are @samp{a}, @samp{e},
     @samp{i}, @samp{o}, @samp{u}, and sometimes
     @samp{y}.

This produces:

     In English, the vowels are `a', `e', `i', `o', `u',  and sometimes
     `y'.


File: texinfo,  Node: verb,  Next: var,  Prev: samp,  Up: Indicating

`@verb'{<char>TEXT<char>}
-------------------------

  Use the `@verb' command to print a verbatim sequence of characters.

  Like LaTeX's `\verb' command, the verbatim text can be quoted using
any unique delimiter character.  Enclose the verbatim text, including
the delimiters, in braces.  Text is printed in a fixed-width font:

     How many @verb{|@|}-escapes does one need to print this
     @verb{.@a @b @c.} string or @verb{+@'e?`!`{}\+} this?

produces

     How many @-escapes does one need to print this
     @a @b @c string or these @'e?`{}!`\ this?

  This is in contrast to `@samp' (see the previous section), whose
argument is normal Texinfo text, where the characters `@{}' are
special; with `@verb', nothing is special except the delimiter
character you choose.


File: texinfo,  Node: var,  Next: env,  Prev: verb,  Up: Indicating

`@var'{METASYNTACTIC-VARIABLE}
------------------------------

  Use the `@var' command to indicate metasyntactic variables.  A
"metasyntactic variable" is something that stands for another piece of
text.  For example, you should use a metasyntactic variable in the
documentation of a function to describe the arguments that are passed
to that function.

  Do not use `@var' for the names of particular variables in
programming languages.  These are specific names from a program, so
`@code' is correct for them (*note code::).  For example, the Emacs
Lisp variable `texinfo-tex-command' is not a metasyntactic variable; it
is properly formatted using `@code'.

  Do not use `@var' for environment variables either; `@env' is correct
for them (see the next section).

  The effect of `@var' in the Info file is to change the case of the
argument to all upper case.  In the printed manual and HTML output, the
argument is printed in slanted type.

  For example,

     To delete file @var{filename},
     type @samp{rm @var{filename}}.

produces

     To delete file FILENAME, type `rm FILENAME'.

(Note that `@var' may appear inside `@code', `@samp', `@file', etc.)

  Write a metasyntactic variable all in lower case without spaces, and
use hyphens to make it more readable.  Thus, the Texinfo source for the
illustration of how to begin a Texinfo manual looks like this:

     \input texinfo
     @@setfilename @var{info-file-name}
     @@settitle @var{name-of-manual}

This produces:

     \input texinfo
     @setfilename INFO-FILE-NAME
     @settitle NAME-OF-MANUAL

  In some documentation styles, metasyntactic variables are shown with
angle brackets, for example:

     ..., type rm <filename>

However, that is not the style that Texinfo uses.  (You can, of course,
modify the sources to `texinfo.tex' and the Info formatting commands to
output the `<...>' format if you wish.)


File: texinfo,  Node: env,  Next: file,  Prev: var,  Up: Indicating

`@env'{ENVIRONMENT-VARIABLE}
----------------------------

  Use the `@env' command to indicate environment variables, as used by
many operating systems, including GNU.  Do not use it for metasyntactic
variables; use `@var' instead (see the previous section).

  `@env' is equivalent to `@code' in its effects.  For example:

     The @env{PATH} environment variable ...
   produces

     The `PATH' environment variable ...


File: texinfo,  Node: file,  Next: command,  Prev: env,  Up: Indicating

`@file'{FILE-NAME}
------------------

  Use the `@file' command to indicate text that is the name of a file,
buffer, or directory, or is the name of a node in Info.  You can also
use the command for file name suffixes.  Do not use `@file' for symbols
in a programming language; use `@code'.

  Currently, `@file' is equivalent to `@samp' in its effects.  For
example,

     The @file{.el} files are in
     the @file{/usr/local/emacs/lisp} directory.

produces

     The `.el' files are in the `/usr/local/emacs/lisp' directory.


File: texinfo,  Node: command,  Next: option,  Prev: file,  Up: Indicating

`@command'{COMMAND-NAME}
------------------------

  Use the `@command' command to indicate command names, such as `ls' or
`cc'.

  `@command' is equivalent to `@code' in its effects.  For example:

     The command @command{ls} lists directory contents.
   produces

     The command `ls' lists directory contents.

  You should write the name of a program in the ordinary text font,
rather than using `@command', if you regard it as a new English word,
such as `Emacs' or `Bison'.

  When writing an entire shell command invocation, as in `ls -l', you
should use either `@samp' or `@code' at your discretion.


File: texinfo,  Node: option,  Next: dfn,  Prev: command,  Up: Indicating

`@option'{OPTION-NAME}
----------------------

  Use the `@option' command to indicate a command-line option; for
example, `-l' or `--version' or `--output=FILENAME'.

  `@option' is equivalent to `@samp' in its effects.  For example:

     The option @option{-l} produces a long listing.
   produces

     The option `-l' produces a long listing.

  In tables, putting options inside `@code' produces a more pleasing
effect.


File: texinfo,  Node: dfn,  Next: cite,  Prev: option,  Up: Indicating

`@dfn'{TERM}
------------

  Use the `@dfn' command to identify the introductory or defining use
of a technical term.  Use the command only in passages whose purpose is
to introduce a term which will be used again or which the reader ought
to know.  Mere passing mention of a term for the first time does not
deserve `@dfn'.  The command generates italics in the printed manual,
and double quotation marks in the Info file.  For example:

     Getting rid of a file is called @dfn{deleting} it.

produces

     Getting rid of a file is called "deleting" it.

  As a general rule, a sentence containing the defining occurrence of a
term should be a definition of the term.  The sentence does not need to
say explicitly that it is a definition, but it should contain the
information of a definition--it should make the meaning clear.


File: texinfo,  Node: cite,  Next: acronym,  Prev: dfn,  Up: Indicating

`@cite'{REFERENCE}
------------------

  Use the `@cite' command for the name of a book that lacks a companion
Info file.  The command produces italics in the printed manual, and
quotation marks in the Info file.

  If a book is written in Texinfo, it is better to use a cross reference
command since a reader can easily follow such a reference in Info.
*Note `@xref': xref.


File: texinfo,  Node: acronym,  Next: url,  Prev: cite,  Up: Indicating

`@acronym'{ACRONYM}
-------------------

  Use the `@acronym' command for abbreviations written in all capital
letters, such as `NASA'.  The abbreviation is given as the single
argument in braces, as in `@acronym{NASA}'.  As a matter of style, or
for particular abbreviations, you may prefer to use periods, as in
`@acronym{F.B.I.}'.

  In TeX and HTML, the argument is printed in a slightly smaller font
size.  In Info or plain text output, this command changes nothing.


File: texinfo,  Node: url,  Next: email,  Prev: acronym,  Up: Indicating

`@url'{UNIFORM-RESOURCE-LOCATOR}
--------------------------------

  Use the `@url' command to indicate a uniform resource locator on the
World Wide Web.  This is analogous to `@file', `@var', etc., and is
purely for markup purposes.  It does not produce a link you can follow
in HTML output (use the `@uref' command for that, *note `@uref':
uref.).  It is useful for url's which do not actually exist.  For
example:

     For example, the url might be @url{http://example.org/path}.

which produces:

     For example, the url might be <http://example.org/path>.


File: texinfo,  Node: email,  Prev: url,  Up: Indicating

`@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
-----------------------------------------

  Use the `@email' command to indicate an electronic mail address.  It
takes one mandatory argument, the address, and one optional argument,
the text to display (the default is the address itself).

  In Info and TeX, the address is shown in angle brackets, preceded by
the text to display if any.  In HTML output, `@email' produces a
`mailto' link that usually brings up a mail composition window.  For
example:

     Send bug reports to @email{bug-texinfo@@gnu.org},
     suggestions to the @email{bug-texinfo@@gnu.org, same place}.
   produces
     Send bug reports to <bug-texinfo@gnu.org>,
     suggestions to the same place <bug-texinfo@gnu.org>.


File: texinfo,  Node: Emphasis,  Prev: Indicating,  Up: Marking Text

Emphasizing Text
================

  Usually, Texinfo changes the font to mark words in the text according
to what category the words belong to; an example is the `@code' command.
Most often, this is the best way to mark words.  However, sometimes you
will want to emphasize text without indicating a category.  Texinfo has
two commands to do this.  Also, Texinfo has several commands that
specify the font in which TeX will typeset text.  These commands have
no effect on Info and only one of them, the `@r' command, has any
regular use.

* Menu:

* emph & strong::               How to emphasize text in Texinfo.
* Smallcaps::                   How to use the small caps font.
* Fonts::                       Various font commands for printed output.


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

`@emph'{TEXT} and `@strong'{TEXT}
---------------------------------

  The `@emph' and `@strong' commands are for emphasis; `@strong' is
stronger.  In printed output, `@emph' produces _italics_ and `@strong'
produces *bold*.

  For example,

     @quotation
     @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
     files in the directory.
     @end quotation

produces:

          *Caution*: `rm * .[^.]*' removes _all_
          files in the directory.

  The `@strong' command is seldom used except to mark what is, in
effect, a typographical element, such as the word `Caution' in the
preceding example.

  In the Info output, `@emph' surrounds the text with underscores
(`_'), and `@strong' puts asterisks around the text.

     *Caution:* Do not use `@strong' with the word `Note'; Info will
     mistake the combination for a cross reference.  Use a phrase such
     as *Please note* or *Caution* instead.


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

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

  Use the `@sc' command to set text in the printed and the HTML output
in A SMALL CAPS FONT and set text in the Info file in upper case
letters.  Write the text you want to be in small caps (where possible)
between braces in lower case, like this:

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

This produces:

     The ACM and IEEE are technical societies.

  TeX typesets the small caps font in a manner that prevents the
letters from `jumping out at you on the page'.  This makes small caps
text easier to read than text in all upper case--but it's usually
better to use regular mixed case anyway.  The Info formatting commands
set all small caps text in upper case.  In HTML, the text is upper-cased
and a smaller font is used to render it.

  If the text between the braces of an `@sc' command is uppercase, TeX
typesets in FULL-SIZE CAPITALS.  Use full-size capitals sparingly, if
ever, and since it's redundant to mark all-uppercase text with `@sc',
`makeinfo' warns about such usage.

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

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


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

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

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

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

  For example,

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

produces

     (+ 2 2)    ; Add two plus two.

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


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

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

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

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

* Menu:

* Block Enclosing Commands::    Different constructs for different purposes.
* quotation::                   Writing a quotation.
* example::                     Writing an example in a fixed-width font.
* verbatim::                    Writing a verbatim example.
* verbatiminclude::             Including a file verbatim.
* lisp::                        Illustrating Lisp code.
* small::                       Forms for `@smallbook'.
* display::                     Writing an example in the current font.
* format::                      Writing an example without narrowed margins.
* exdent::                      Undo indentation on a line.
* flushleft & flushright::      Pushing text flush left or flush right.
* noindent::                    Preventing paragraph indentation.
* cartouche::                   Drawing rounded rectangles around examples.


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

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

  Here are commands for quotations and examples, explained further in
the following sections:

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

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

`@verbatim'
     Mark a piece of text that is to be printed verbatim; no character
     substitutions are made and all commands are ignored, until the next
     `@end verbatim'.  The text is printed in a fixed-width font, and
     not indented or filled.  Extra spaces and blank lines are
     significant, and tabs are expanded.

`@smallexample'
     Same as `@example', except that in TeX this command typesets text
     in a smaller font.

`@lisp'
     Like `@example', but specifically for illustrating Lisp code. The
     text is printed in a fixed-width font, and indented but not filled.

`@smalllisp'
     Is to `@lisp' as `@smallexample' is to `@example'.

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

`@smalldisplay'
     Is to `@display' as `@smallexample' is to `@example'.

`@format'
     Like `@display' (the text is not filled and no font is selected),
     but the text is not indented.

`@smallformat'
     Is to `@format' as `@smallexample' is to `@example'.

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

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

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

  You can use the `@cartouche' command within one of the above
constructs to highlight the example or quotation by drawing a box with
rounded corners around it.  *Note Drawing Cartouches Around Examples:
cartouche.


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

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

  The text of a quotation is processed normally except that:

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

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

   * in the printed output, interparagraph spacing is reduced.

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

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

     @quotation
     This is
     a foo.
     @end quotation

produces

     This is a foo.


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

`@example': Example Text
========================

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

     This is an example of text written between an
     `@example' command
     and an `@end example' command.
     The text is indented but not filled.
     
     In the printed manual, the text is typeset in a
     fixed-width font, and extra spaces and blank lines are
     significant.  In the Info file, an analogous result is
     obtained by indenting each line with five spaces.

  Write an `@example' command at the beginning of a line by itself.
Mark the end of the example with an `@end example' command, also
written at the beginning of a line by itself.

  For example,

     @example
     mv foo bar
     @end example

produces

     mv foo bar

  The lines containing `@example' and `@end example' will disappear
from the output.  To make the output look good, you should put a blank
line before the `@example' and another blank line after the `@end
example'.  Note that blank lines inside the beginning `@example' and
the ending `@end example' will appear in the output.

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

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

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


File: texinfo,  Node: verbatim,  Next: verbatiminclude,  Prev: example,  Up: Quotations and Examples

`@verbatim': Literal Text
=========================

  Use the `@verbatim' environment for printing of text that may contain
special characters or commands that should not be interpreted, such as
computer input or output (`@example' interprets its text as regular
Texinfo commands).  This is especially useful for including
automatically generated output in a Texinfo manual.  Here is an example;
the output you see is just the same as the input, with a line
`@verbatim' before and a line `@end verbatim' after.


This is an example of text written in a @verbatim
block.  No character substitutions are made.  All commands
are ignored, until `<at>end verbatim'.

In the printed manual, the text is typeset in a
fixed-width font, and not indented or filled.  All
spaces and blank lines are significant, including tabs.

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

  For example:

@verbatim
{
<tab>@command with strange characters: @'e
expand<tab>me
}
@end verbatim

produces


{
	@command with strange characters: @'e 
expand	me
}

  Since the lines containing `@verbatim' and `@end verbatim' produce no
output, tyically you should put a blank line before the `@verbatim' and
another blank line after the `@end verbatim'.  Blank lines between the
beginning `@verbatim' and the ending `@end verbatim' will appear in the
output.


File: texinfo,  Node: verbatiminclude,  Next: lisp,  Prev: verbatim,  Up: Quotations and Examples

`@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': verbatim.).  Generally, the file is printed exactly as it
is, with all special characters and white space retained.


File: texinfo,  Node: lisp,  Next: small,  Prev: verbatiminclude,  Up: Quotations and Examples

`@lisp': Marking a Lisp Example
===============================

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

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

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

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


File: texinfo,  Node: lisp-Footnotes,  Up: lisp

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


File: texinfo,  Node: small,  Next: display,  Prev: lisp,  Up: Quotations and Examples

`@small...' Block Commands
==========================

  In addition to the regular `@example' and `@lisp' commands, Texinfo
has "small" example-style commands.  These are `@smalldisplay',
`@smallexample', `@smallformat', and `@smalllisp'.

  In TeX, the `@small...' commands typeset text in a smaller font than
the non-small example commands.  Consequently, many examples containing
long lines fit on a page without needing to be shortened.

  In Info, the `@small...' commands are equivalent to their non-small
companion commands.

  Mark the end of an `@small...' block with a corresponding `@end
small...'.  For example, pair `@smallexample' with `@end smallexample'.

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

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

  As a general rule, a printed document looks better if you use only one
of (for example) `@example' or in `@smallexample' consistently within a
chapter.  Only occasionally should you mix the two formats.

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

