@comment -*-texinfo-*-
@setfilename texinfo

@node [top, commands, , (DIR)]

@chapter Texinfo Files

Documentation for GNU utilities and libraries should be written
in a format called @defn {texinfo}.  This format can be translated
mechanically into either printed manuals or on-line readable
structured documentation files.@refill

@menu
* commands::   What goes into a texinfo file.
* info::   Making texinfo files into ``info'' structured files.
* tex::    Making texinfo files into printed manuals.
@end menu
@node [commands, info, top, top]

@section Texinfo File Commands

Texinfo files contain a strictly limited set of constructs
for a @TeX macro package quite different from plain @TeX.
The strict limits make it possible for texinfo files to be
understood also by the @code[texinfo] program, which converts
them into info files.

All ASCII printing characters except @code[@@], @code[{] and
@code[}] can appear in body text in a texinfo file and stand for
themselves.  @code[@@] is the escape character which introduces
commands.  @code[{] and @code[}] should be used only to surround
arguments to certain commands.  @code[{] and @code[}] appearing
anywhere else will be treated by @TeX as a grouping but treated by
texinfo as themselves; this inconsistency is undesirable, so don't
let it occur.  To put special characters into the document, put a
control-q character in front; thus, type @code[{] to put a
@code[{] in the document.@refill

It is customary in @TeX to use doubled single-quote characters
to begin and end quotations.  This convention should be followed
in texinfo files.

@TeX ignores the line-breaks in the input text, except for
blank lines, which separate paragraphs.  Texinfo generally
preserves the line breaks that are present in the input file.
Therefore, you break the lines in the texinfo file the way
you want them to appear in the output info file, and let @TeX
take care of itself.

This is a list of the @@-commands defined in texinfo:

** @@@@ **

@@@@ stands for a single @@ in the printed or info output.

** @@setfilename **

@code{@@setfilename @var{file}} informs texinfo that the
Info file being produced is named @var{file}.  This information
is entered in every node header.  It also tells texinfo the
name for the output file.

** @@node **

@code[@@node] defines the beginning of a new node in the info output file
(@note [info, (info)top])  It is followed by four arguments, separated
by commas, and all surrounded by square brackets.  For example,@refill

@example
@@node [info, tex, commands, top]
@end example

defines a node named @code{info}, whose successor node name
is @code{tex}, whose predecessor node name is @code{commands},
and whose parent node name is @code{top}.  What this means
is that texinfo changes @code[@@node [@var{args}]] into the special
text string necessary to separate info nodes and to identify
the node that is starting and say what its relatives are.@refill

The successor, predecessor and parent names should be the names
of nodes defined elsewhere.  For this example, nodes named @code{tex},
@code{commands} and @code{top} should be defined elsewhere in
the file with other @code{@@node} commands.  It does not matter whether
they are before or after the node that refers to them.@refill

In @TeX, @code[@@node] is nearly ignored.  It generates no text.  Its only
function is to identify the name to use for cross-references
to the following chapter or section which makes up the body of the node.
(Cross references are made with @code[@@note]).

@code[@@node] should always be followed by a blank line, which is
then followed by a @code[@@chapter], @code[@@section],
@code[@@subsection] or @code[@@subsubsection].@refill

** @@chapter **

@code[@@chapter] identifies a chapter in the document.  It is followed
by a single argument within braces, as in@refill

@example
@@chapter {Texinfo Files}
@end example

In @TeX, it serves to create a chapter of the document,
specifying the chapter title.

In texinfo, @code[@@chapter] causes its argument to appear on a line
by itself, with a line of dashes inserted underneath.  Thus, in
texinfo, the above example produces the output@refill

@example
Texinfo Files
-------------
@end example

** @@section **

@code[@@section] is like @code[@@chapter] except that in @TeX it makes
a section rather than a chapter.  Sections go within chapters.  In
texinfo, @code[@@chapter] and @code[@@section] have the same
effect.@refill

** @@subsection **

Subsections are to sections as sections are to chapters.

** @@subsubsection **

Subsubsections are to subsections as subsections are to sections.

** @@code **

@code[@@code] is used to indicate text that is a literal example of
input to a program.  The text follows, enclosed in braces.  Any time
you give a sample of an expression in C, or of a command for the
shell, or any such thing, use @code[@@code].  In @TeX, it puts the
argument in bold face.  In texinfo, it creates `...' quotation.
Example:@refill

@example
To compare two files, showing text inserted or removed,
use @@code{diff}.
@end example

produces

@example
To compare two files, showing text inserted or removed,
use @code{diff}.
@end example

** @@var **

@code[@@var] is used to indicate metasyntactic variables.  It is much
like @code[@@code] in use.  Its effect in texinfo is to upcase the
argument; in @TeX, to italicize it.  Example:@refill

@example
To delete file @@var{file}, type @@code{rm @@var{file}}.
@end example

produces

@example
To delete file @var{file}, type @code{rm @var{file}}.
@end example

** @@defn **

@code[@@defn] is like @code[@@code] and @code[@@var]; but for a
different purpose: it indicates the first introductory or defining
use of a technical term.  It generates italics in @TeX, and double
quotation marks in texinfo.  Example:@refill

@example
Getting rid of a file is called @@defn{deleting} it.
@end example

produces

@example
Getting rid of a file is called @defn{deleting} it.
@end example

** @@example **

@code[@@example] is used to indicate an example that is not part
of the running text.  This text is printed by @TeX in a fixed
width font with no filling.  Texinfo simply indents the lines
of the example by four extra spaces.  @code[@@example] should appear
on a line by itself; this line will disappear from the output.
Mark the end of the example with a line containing @code{@@end example},
which will likewise disappear.  Example:@refill

@example
@@example
mv foo bar
@@end example
@end example

produces

@example
    mv foo bar
@end example

Don't use tabs in lines of an example!

** @@menu **

Info file nodes can contain @defn{menus} which point to other nodes.
You must type the menus in by hand, and surround them with
lines containing @code{@@menu} and @code{@@end menu}.
The @code{@@menu} line changes into @code{* Menu:}, which indicates
the beginning of a menu to the Info program.  The contents are
unchanged by texinfo.  @TeX throws away the entire @code{@@menu}
construct.@refill

@example
@@menu
* foo::         The node named foo tells you how to go fooing.
* sw: switches.	Type @@code[m sw] to see node @@code[switches].
                which describes the switches available here.
@@end menu
@end example

produces

@example
* menu:
* foo::         The node named foo tells you how to go fooing.
* sw: switches. Type `m sw' to see node `switches'
                which describes the switches available here.
@end example

** @@refill **

If a paragraph contains sizeable @@-constructs, it may look
badly filled once texinfo is through with it.

Put @code{@@refill} at the end of the paragraph to tell
texinfo to refill the paragraph after finishing all other
processing on it.  @code[@@refill] has no effect on @TeX, which
always fills everything that ought to be filled.@refill

** @@xref **

@code[@@xref] generates a cross-reference.  In texinfo, it turns into
an Info @defn{footnote} which the Info @code{f} command can use
to go directly to another node.  In @TeX, it turns into a sentence
of the form
@example
See section @var{SECTION} [@var{TOPIC}], page @var{PAGE}
@end example
but does not generate a period to end it.

@code[@@xref] must refer to an Info node created by @code[@@node], by
the node's name.  If I were in less of a rush, I would have made a
node in this file for each texinfo command, and put in plenty of
@@note's to cross-reference them together.  The big node named
@code[commands] would actually contain a menu naming the nodes for
individual commands.

@code{@@xref} is followed by a pair of square brackets, containing up
to five arguments separated by commas.  Whitespace around the arguments
is ignored.  The closing square bracket must be followed by a period
or a comma, since one of those to is required to terminate an Info
footnote.  This period or comma will appear in the output, both Info
file and printed manual.

The simplest form of @code{@@xref} takes one argument, the name of another
node in the same Info file:

@example
@@xref[foo], for more info.

 *Note foo::, for more info.
 See section @var{nnn} [foo], page @var[ppp], for more info.
@end example

With two arguments, the second one is the used as the
name of the Info footnote, while the first argument is still
the node that the footnote points to:

@example
@@xref[foo node, foo], for more info.

 *Note foo: foo node, for more info.
 See section @var{nnn} [foo node], page @var[ppp], for more info.
@end example

A third argument replaces the node name when it actually appears
in the TeX output.  It should state the topic discussed by the
section being referenced.  Use a third argument when the node
name is unsuitable because of syntax, grammar or diction.

@example
@@xref[foo node, foo, using foo], for more info.

 *Note foo: foo node, for more info.
 See section @var{nnn} [using foo], page @var[ppp],
 for more info.
@end example

A fourth argument specifies the name of the Info file in which
the referenced node is located, assuming it is not the one which
the reference appears in.  @code{@@xref} with only four arguments
is used when the reference is not within one Info file, but is
within a single printed manual--when multiple texinfo files are
incorporated into the same TeX run but make separate Info files.

@example
@@xref[foo node, foo, using foo, myinfofile], for more info.

 *Note foo: (myinfofile)foo node, for more info.
 See section @var{nnn} [using foo], page @var[ppp],
 for more info.
@end example

A fifth argument is used when referencing another Info file
which is also part of another printed manual.  It gives the
title of that manual.

@example
@@xref[foo node, foo, using foo, myinfofile, Mymanual],
for more info.

 *Note foo: (myinfofile)foo node, for more info.
 See section @var{nnn} [using foo], page @var[ppp]
 of Mymanual, for more info.
@end example

** @@itemize **

@code{@@itemize} is used to produce sequences of indented paragraphs,
with a mark inside the left margin at the beginning of each.
The rest of the line that starts with @code{@@itemize} should
contain the character or texinfo commands to generate such a mark.
It should ultimately result in a single character, or the indentation
will come out wrong.

The text of the indented paragraphs themselves come after the
@code{@@itemize}, up to another line that says @code{@@end @@itemize}.

Before each paragraph for which a mark in the margin is desired,
place a line that says just @code{@@item}.

Here is an example of the use of @code{@@itemize}, followed
by the output it produces in texinfo.  Note that @code{@@bullet}
produces a @code{*} in texinfo and a round dot in @TeX.

@example
@@itemize @@bullet
@@item
Some text for foo.
@@item
Some text
for bar.
@@end itemize
@end example

@example
@itemize @bullet
@item
Some text for foo.
@item
Some text
for bar.
@end itemize
@end example

** @@enumerate **

@code{@@enumerate} is like @code{@@itemize} except that the
marks in the left margin contain successive integers starting
with 1.  Do not put argument on the same line as @code{@@enumerate};
none is needed.

@example
@@enumerate
@@item
Some text for foo.
@@item
Some text
for bar.
@@end enumerate
@end example

@example
@enumerate
@item
Some text for foo.
@item
Some text
for bar.
@end enumerate
@end example

** conditionals **

You may not be able to use the same text for @TeX and texinfo.
Use the conditional commands to specify which text is for @TeX
and which is for texinfo.

@code[@@ifinfo] begins text that should be ignored by @TeX.
It should appear on a line by itself.  End the texinfo-only
text with a line containing @code{@@end ifinfo}.@refill

Likewise, @code[@@iftex] and @code{@@end iftex} lines delimit code
that should be ignored by texinfo.@refill
