texinfo.texi

gcc-2.95.3 Linux下最常用的C编译器

limited.@refill

@xref{Obtaining TeX, , How to Obtain @TeX{}}.


@node Formatting Commands, Conventions, Printed Books, Overview
@comment  node-name,  next,  previous,  up
@section @@-commands
@cindex @@-commands
@cindex Formatting commands

In a Texinfo file, the commands that tell @TeX{} how to typeset the
printed manual and tell @code{makeinfo} and
@code{texinfo-format-buffer} how to create an Info file are preceded
by @samp{@@}; they are called @dfn{@@-commands}.  For example,
@code{@@node} is the command to indicate a node and @code{@@chapter}
is the command to indicate the start of a chapter.@refill

@quotation
@strong{Please note:} All the @@-commands, with the exception of the
@code{@@TeX@{@}} command, must be written entirely in lower
case.@refill
@end quotation

The Texinfo @@-commands are a strictly limited set of constructs.  The
strict limits make it possible for Texinfo files to be understood both
by @TeX{} and by the code that converts them into Info files.  You can
display Info files on any terminal that displays alphabetic and
numeric characters.  Similarly, you can print the output generated by
@TeX{} on a wide variety of printers.@refill

Depending on what they do or what arguments@footnote{The word
@dfn{argument} comes from the way it is used in mathematics and does
not refer to a disputation between two people; it refers to the
information presented to the command.  According to the @cite{Oxford
English Dictionary}, the word derives from the Latin for @dfn{to make
clear, prove}; thus it came to mean `the evidence offered as proof',
which is to say, `the information offered', which led to its
mathematical meaning.  In its other thread of derivation, the word
came to mean `to assert in a manner against which others may make
counter assertions', which led to the meaning of `argument' as a
disputation.} they take, you need to write @@-commands on lines of
their own or as part of sentences:@refill

@itemize @bullet
@item
Write a command such as @code{@@noindent} at the beginning of a line as
the only text on the line.  (@code{@@noindent} prevents the beginning of
the next line from being indented as the beginning of a
paragraph.)@refill

@item
Write a command such as @code{@@chapter} at the beginning of a line
followed by the command's arguments, in this case the chapter title, on
the rest of the line.  (@code{@@chapter} creates chapter titles.)@refill

@item
Write a command such as @code{@@dots@{@}} wherever you wish but usually
within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill

@item
Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
wish (but usually within a sentence) with its argument,
@var{sample-code} in this example, between the braces.  (@code{@@code}
marks text as being code.)@refill

@item
Write a command such as @code{@@example} at the beginning of a line of
its own; write the body-text on following lines; and write the matching
@code{@@end} command, @code{@@end example} in this case, at the
beginning of a line of its own after the body-text. (@code{@@example}
@dots{} @code{@@end example} indents and typesets body-text as an
example.)@refill
@end itemize

@noindent
@cindex Braces, when to use
As a general rule, a command requires braces if it mingles among other
text; but it does not need braces if it starts a line of its own.  The
non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
they do not need braces.@refill

As you gain experience with Texinfo, you will rapidly learn how to
write the different commands: the different ways to write commands
make it easier to write and read Texinfo files than if all commands
followed exactly the same syntax.  (For details about @@-command
syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill

@node Conventions, Comments, Formatting Commands, Overview
@comment  node-name,  next,  previous,  up
@section General Syntactic Conventions
@cindex General syntactic conventions
@cindex Syntactic conventions
@cindex Conventions, syntactic

All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
@samp{@}} can appear in a Texinfo file and stand for themselves.
@samp{@@} is the escape character which introduces commands.
@samp{@{} and @samp{@}} should be used only to surround arguments to
certain commands.  To put one of these special characters into the
document, put an @samp{@@} character in front of it, like this:
@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill

@ifinfo
It is customary in @TeX{} to use doubled single-quote characters to
begin and end quotations: ` ` and ' ' (but without a space between the
two single-quote characters).  This convention should be followed in
Texinfo files.  @TeX{} converts doubled single-quote characters to
left- and right-hand doubled quotation marks and Info converts doubled
single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
@end ifinfo
@iftex
It is customary in @TeX{} to use doubled single-quote characters to
begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}.  This
convention should be followed in Texinfo files.  @TeX{} converts
doubled single-quote characters to left- and right-hand doubled
quotation marks, ``like this'', and Info converts doubled single-quote
characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and
@w{@tt{ '' }} to @w{@tt{ " }}.@refill
@end iftex

Use three hyphens in a row, @samp{---}, for a dash---like this.  In
@TeX{}, a single or double hyphen produces a printed dash that is
shorter than the usual typeset dash. Info reduces three hyphens to two
for display on the screen.

To prevent a paragraph from being indented in the printed manual, put
the command @code{@@noindent} on a line by itself before the
paragraph.@refill

If you mark off a region of the Texinfo file with the @code{@@iftex}
and @w{@code{@@end iftex}} commands, that region will appear only in
the printed copy; in that region, you can use certain commands
borrowed from plain @TeX{} that you cannot use in Info.  Likewise, if
you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
commands, that region will appear only in the Info file; in that
region, you can use Info commands that you cannot use in @TeX{}.
Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
@code{@@ifnothtml @dots{} @@end ifnothtml},
@code{@@ifnotinfo @dots{} @@end ifnotinfo},
@code{@@ifnottex @dots{} @@end ifnottex},
@xref{Conditionals}.

@cindex Tabs; don't use!
@quotation
@strong{Caution:} Do not use tabs in a Texinfo file!  @TeX{} uses
variable-width fonts, which means that it cannot predefine a tab to work
in all circumstances.  Consequently, @TeX{} treats tabs like single
spaces, and that is not what they look like.  Furthermore,
@code{makeinfo} does nothing special with tabs, and thus a tab character
in your input file may appear differently in the output.

@noindent
To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
spaces when you press the @key{TAB} key.@refill

@noindent
Also, you can run @code{untabify} in Emacs to convert tabs in a region
to multiple spaces.@refill

@noindent
Don't use tabs.
@end quotation

@node Comments, Minimum, Conventions, Overview
@comment  node-name,  next,  previous,  up
@section Comments

You can write comments in a Texinfo file that will not appear in
either the Info file or the printed manual by using the
@code{@@comment} command (which may be abbreviated to @code{@@c}).
Such comments are for the person who reads the Texinfo file.  All the
text on a line that follows either @code{@@comment} or @code{@@c} is a
comment; the rest of the line does not appear in either the Info file
or the printed manual. (Often, you can write the @code{@@comment} or
@code{@@c} in the middle of a line, and only the text that follows after
the @code{@@comment} or @code{@@c} command does not appear; but some
commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
whole line.  You cannot use @code{@@comment} or @code{@@c} in a line
beginning with such a command.)@refill
@cindex Comments
@findex comment
@findex c @r{(comment)}

You can write long stretches of text that will not appear in either
the Info file or the printed manual by using the @code{@@ignore} and
@code{@@end ignore} commands.  Write each of these commands on a line
of its own, starting each command at the beginning of the line.  Text
between these two commands does not appear in the processed output.
You can use @code{@@ignore} and @code{@@end ignore} for writing
comments.  Often, @code{@@ignore} and @code{@@end ignore} is used
to enclose a part of the copying permissions that applies to the
Texinfo source file of a document, but not to the Info or printed
version of the document.@refill
@cindex Ignored text
@cindex Unprocessed text
@findex ignore
@c !!! Perhaps include this comment about ignore and ifset:
@ignore
Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
@code{@@ifclear} conditions is ignored in the sense that it will not
contribute to the formatted output.  However, TeX and makeinfo must
still parse the ignored text, in order to understand when to
@emph{stop} ignoring text from the source file; that means that you
will still get error messages if you have invalid Texinfo markup
within ignored text.
@end ignore

@node Minimum, Six Parts, Comments, Overview
@comment  node-name,  next,  previous,  up
@section What a Texinfo File Must Have
@cindex Minimal Texinfo file (requirements)
@cindex Must have in Texinfo file
@cindex Required in Texinfo file
@cindex Texinfo file minimum

By convention, the names of Texinfo files end with one of the
extensions @file{.texinfo}, @file{.texi}, or @file{.tex}.  The longer
extension is preferred since it describes more clearly to a human
reader the nature of the file.  The shorter extensions are for
operating systems that cannot handle long file names.@refill

In order to be made into a printed manual and an Info file, a Texinfo
file @strong{must} begin with lines like this:@refill

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

@noindent
The contents of the file follow this beginning, and then you @strong{must} end
a Texinfo file with a line like this:@refill

@example
@@bye
@end example

@findex input @r{(@TeX{} command)}
@noindent
The @samp{\input texinfo} line tells @TeX{} to use the
@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
@@-commands into @TeX{} typesetting commands.  (Note the use of the
backslash, @samp{\}; this is correct for @TeX{}.)  The
@samp{@@setfilename} line provides a name for the Info file and tells
@TeX{} to open auxiliary files.  The @samp{@@settitle} line specifies a
title for the page headers (or footers) of the printed manual.@refill

The @code{@@bye} line at the end of the file on a line of its own tells
the formatters that the file is ended and to stop formatting.@refill

Usually, you will not use quite such a spare format, but will include
mode setting and start-of-header and end-of-header lines at the
beginning of a Texinfo file, like this:@refill

@example
@group
\input texinfo   @@c -*-texinfo-*-
@@c %**start of header
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}
@@c %**end of header
@end group
@end example

@noindent
In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
Texinfo mode when you edit the file.

The @code{@@c} lines which surround the @samp{@@setfilename} and
@samp{@@settitle} lines are optional, but you need them in order to
run @TeX{} or Info on just part of the file.  (@xref{Start of Header},
for more information.)@refill

Furthermore, you will usually provide a Texinfo file with a title
page, indices, and the like.  But the minimum, which can be useful
for short documents, is just the three lines at the beginning and the
one line at the end.@refill

@node Six Parts, Short Sample, Minimum, Overview
@comment  node-name,  next,  previous,  up
@section Six Parts of a Texinfo File

Generally, a Texinfo file contains more than the minimal
beginning and end---it usually contains six parts:@refill

@table @r
@item 1. Header
The @dfn{Header} names the file, tells @TeX{} which definitions' file to
use, and performs other ``housekeeping'' tasks.@refill

@item 2. Summary Description and Copyright
The @dfn{Summary Description and Copyright} segment describes the document
and contains the copyright notice and copying permissions for the Info
file.  The segment must be enclosed between @code{@@ifinfo} and
@code{@@end ifinfo} commands so that the formatters place it only in the Info
file.@refill

@item 3. Title and Copyright
The @dfn{Title and Copyright} segment contains the title and copyright pages
and copying permissions for the printed manual.  The segment must be
enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
The title and copyright page appear only in the printed @w{manual}.@refill

@item 4. `Top' Node and Master Menu
The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
Info file.  It appears only in the Info file, in the `Top' node.@refill

@item 5. Body
The @dfn{Body} of the document may be structured like a traditional book or