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

@chapter Texinfo Files

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

@menu
* commands::   What goes into a texinfo file.
* info::   Making a texinfo file into an Info file.
The following will be written later
  tex::    Making a texinfo file into a printed manual.
@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:

@subsection @@@@

@@@@ stands for a single @@ in either printed or Info output.

@subsection @@.

@code[@@.] stands for a period that ends an abbreviation.  In
texinfo, it has the same effect as just @code[.], since you
are responsible for your own formatting in texinfo.  In a
printed manual, it generates a period that does not increase
the following interword space as periods usually do.

@subsection @@:

@code[@@:] is used just after a period that really does end
a sentence, if @TeX will assume by its heuristics that that is not so.
This happens when there is a single-capital-letter word at
the end of a sentence: @TeX thinks it is an abbreviation.
@code[@@:] generates no output in texinfo.

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

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

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

@subsection @@unnumbered, @@appendix

These are equivalent to @code[@@chapter] in texinfo.
In a printed manual, they generate chapters that are numbered
differently in the table of contents.  @code[@@unnumbered] chapters
appear without chapter numbers of any kind, and @code[@@appendix]
chapters are given a letter instead of a number.

@subsection @@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] differ only in
that @code[@@section] underlines with @code[=].@refill

@subsection @@unnumberedsec, @@appendixsection

Use these constructs for sections within chapters made by
@code[@@unnumbered] or @code[@@appendix].

@subsection @@subsection

Subsections are to sections as sections are to chapters.
They are underlines with @code{-}.

@subsection @@unnumberedsubsec, @@appendixsubsec

Use these constructs for subsections within sections within
chapters made by @code[@@unnumbered] or @code[@@appendix].

@subsection @@subsubsection

Subsubsections are to subsections as subsections are to sections.
They are underlined with periods.

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

@subsection @@kbd

@code[@@kbd] is used much like @code[@@code].  The difference
is that @code[@@kbd] is for names of keys on the keyboard, or
of characters you can type.  It has the same effect as @code[@@code]
in texinfo, but may produce a different font in a printed manual.

@example
To give the @@code[logout] command, type the characters
@@kbd[l o g o u t Newline].
@end example

produces

@example
To give the @code[logout] command, type the characters
@kbd[l o g o u t Newline].
@end example

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

@subsection @@dfn or @@defn

@code[@@dfn] 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 @@dfn{deleting} it.
@end example

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

@code[@@defn] and @code[@@dfn] are synonymous.  The spelling
@code[@@defn] is being replaced by @code[@@dfn].  Use the latter.@refill

@subsection @@i or @@b

@code[@@i] produces italic text in a printed manual, but has
no effect on the Info file output.  @code[@@b] does likewise,
for bold face.

@subsection @@w

In a printed manual, @code[@@w[@var[text]]] outputs @var[text] and prohibits
line breaks within @var[text].  @code[@@w] has no effect on the Info
file output; it is the same as would result from just @var[text].

@subsection @@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!

@subsection @@menu

Info file nodes can contain @dfn{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

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

@subsection @@xref

@code[@@xref] generates a cross-reference.  In texinfo, it turns into
an Info @dfn{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.  Here we show the input text, followed
after a blank line by the output text for Info files and the output
text for printed manuals.

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

@xref[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.

@xref[foo node, foo], 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.

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

If a third argument is given and the second one is empty,
then the third argument serves both purposes:

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

@xref[foo node, , using foo], 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.

@xref[foo node, foo, using foo, myinfofile], 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.

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

@subsection @@infonote

@code[@@infonote] is used for cross-references to Info files for
which there are no printed manuals.  Even in a printed manual,
@code[@@infonote] generates a reference directing the user to look
in an Info file.  The syntax is @code[@@infonote[@var[node], @var[name], @var[file]]].

@example
@@infonote[foo node, fooing, FOO], to lose.

@infonote[foo node, fooing, FOO], to lose.
See Info file FOO, node `foo node', to lose.
@end example

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

Texinfo indents the lines of the itemization by five additional
columns, but it does not fill them.  If @code{@@refill} is used, the
paragraph is filled to the same width as usual.  This may be changed
some day.

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

@subsection @@table

@code[@@table] is similar to @code[@@itemize], but allows
you to specify a name or heading line for each item.

You must follow each use of @code[@@item] inside of @code[@@table]
with text to serve as the heading line for that item.

Also, @code[@@table] itself must be followed by an argument
which is either @code[1], @code[2] or @code[3].  @code[2]
causes the @code[@@item] strings to be treated as if inside
a @code[@@var].  @code[3] causes them to be treated as if
inside a @code[@@code].  @code[1] says that the @code[@@item]
strings should be used as given.@refill

@example
@@table 3
@@item foo
This is the text for
@@code[foo].
@@item bar
Text for @@code[bar].
@@end table
@end example

produces

@example
@table 3
@item foo
This is the text for
@code[foo].
@item bar
Text for @code[bar].
@end table
@end example

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

@node[info, ,commands, top]

@section Converting Texinfo Files into Info Files

Just visit a texinfo file and invoke

@example
@kbd{Meta-x texinfo-format-buffer}
@end example

to convert it to an Info file.  A new buffer is created
and the Info file text is generated there.  @kbd{C-x C-s}
will save it under the name specified in the @code{@@setfilename}
command.
