1263 lines
49 KiB
Plaintext
1263 lines
49 KiB
Plaintext
This is Info file texi.info, produced by Makeinfo-1.55 from the input
|
||
file texi.texi.
|
||
|
||
This file documents Texinfo, a documentation system that uses a
|
||
single source file to produce both on-line information and a printed
|
||
manual.
|
||
|
||
Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
|
||
Inc.
|
||
|
||
This is the second edition of the Texinfo documentation,
|
||
and is consistent with version 2 of `texinfo.tex'.
|
||
|
||
Permission is granted to make and distribute verbatim copies of this
|
||
manual provided the copyright notice and this permission notice are
|
||
preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided that
|
||
the entire resulting derived work is distributed under the terms of a
|
||
permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions, except that this permission notice may be stated in a
|
||
translation approved by the Free Software Foundation.
|
||
|
||
|
||
File: texi.info, Node: titlepage, Next: titlefont center sp, Up: Titlepage & Copyright Page
|
||
|
||
`@titlepage'
|
||
------------
|
||
|
||
Start the material for the title page and following copyright page
|
||
with `@titlepage' on a line by itself and end it with `@end titlepage'
|
||
on a line by itself.
|
||
|
||
The `@end titlepage' command starts a new page and turns on page
|
||
numbering. (*Note Page Headings: Headings, for details about how to
|
||
generate of page headings.) All the material that you want to appear
|
||
on unnumbered pages should be put between the `@titlepage' and `@end
|
||
titlepage' commands. By using the `@page' command you can force a page
|
||
break within the region delineated by the `@titlepage' and `@end
|
||
titlepage' commands and thereby create more than one unnumbered page.
|
||
This is how the copyright page is produced. (The `@titlepage' command
|
||
might perhaps have been better named the `@titleandadditionalpages'
|
||
command, but that would have been rather long!)
|
||
|
||
When you write a manual about a computer program, you should write
|
||
the version of the program to which the manual applies on the title
|
||
page. If the manual changes more frequently than the program or is
|
||
independent of it, you should also include an edition number(1) for the
|
||
manual. This helps readers keep track of which manual is for which
|
||
version of the program. (The `Top' node should also contain this
|
||
information; see *Note `@top': makeinfo top.)
|
||
|
||
Texinfo provides two methods for creating a title page. One method
|
||
uses the `@titlefont', `@sp', and `@center' commands to generate a
|
||
title page in which the words on the page are centered.
|
||
|
||
The second method uses the `@title', `@subtitle', and `@author'
|
||
commands to create a title page with black rules under the title and
|
||
author lines and the subtitle text set flush to the right hand side of
|
||
the page. With this method, you do not specify any of the actual
|
||
formatting of the title page. You specify the text you want, and
|
||
Texinfo does the formatting. You may use either method.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) We have found that it is helpful to refer to versions of
|
||
manuals as `editions' and versions of programs as `versions';
|
||
otherwise, we find we are liable to confuse each other in conversation
|
||
by referring to both the documentation and the software with the same
|
||
words.
|
||
|
||
|
||
File: texi.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page
|
||
|
||
`@titlefont', `@center', and `@sp'
|
||
----------------------------------
|
||
|
||
You can use the `@titlefont', `@sp', and `@center' commands to
|
||
create a title page for a printed document. (This is the first of the
|
||
two methods for creating a title page in Texinfo.)
|
||
|
||
Use the `@titlefont' command to select a large font suitable for the
|
||
title itself.
|
||
|
||
For example:
|
||
|
||
@titlefont{Texinfo}
|
||
|
||
Use the `@center' command at the beginning of a line to center the
|
||
remaining text on that line. Thus,
|
||
|
||
@center @titlefont{Texinfo}
|
||
|
||
centers the title, which in this example is "Texinfo" printed in the
|
||
title font.
|
||
|
||
Use the `@sp' command to insert vertical space. For example:
|
||
|
||
@sp 2
|
||
|
||
This inserts two blank lines on the printed page. (*Note `@sp': sp,
|
||
for more information about the `@sp' command.)
|
||
|
||
A template for this method looks like this:
|
||
|
||
@titlepage
|
||
@sp 10
|
||
@center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
|
||
@sp 2
|
||
@center SUBTITLE-IF-ANY
|
||
@sp 2
|
||
@center AUTHOR
|
||
...
|
||
@end titlepage
|
||
|
||
The spacing of the example fits an 8 1/2 by 11 inch manual.
|
||
|
||
|
||
File: texi.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page
|
||
|
||
`@title', `@subtitle', and `@author'
|
||
------------------------------------
|
||
|
||
You can use the `@title', `@subtitle', and `@author' commands to
|
||
create a title page in which the vertical and horizontal spacing is
|
||
done for you automatically. This contrasts with the method described in
|
||
the previous section, in which the `@sp' command is needed to adjust
|
||
vertical spacing.
|
||
|
||
Write the `@title', `@subtitle', or `@author' commands at the
|
||
beginning of a line followed by the title, subtitle, or author.
|
||
|
||
The `@title' command produces a line in which the title is set flush
|
||
to the left-hand side of the page in a larger than normal font. The
|
||
title is underlined with a black rule.
|
||
|
||
The `@subtitle' command sets subtitles in a normal-sized font flush
|
||
to the right-hand side of the page.
|
||
|
||
The `@author' command sets the names of the author or authors in a
|
||
middle-sized font flush to the left-hand side of the page on a line
|
||
near the bottom of the title page. The names are underlined with a
|
||
black rule that is thinner than the rule that underlines the title.
|
||
(The black rule only occurs if the `@author' command line is followed
|
||
by an `@page' command line.)
|
||
|
||
There are two ways to use the `@author' command: you can write the
|
||
name or names on the remaining part of the line that starts with an
|
||
`@author' command:
|
||
|
||
@author by Jane Smith and John Doe
|
||
|
||
or you can write the names one above each other by using two (or more)
|
||
`@author' commands:
|
||
|
||
@author Jane Smith
|
||
@author John Doe
|
||
|
||
(Only the bottom name is underlined with a black rule.)
|
||
|
||
A template for this method looks like this:
|
||
|
||
@titlepage
|
||
@title NAME-OF-MANUAL-WHEN-PRINTED
|
||
@subtitle SUBTITLE-IF-ANY
|
||
@subtitle SECOND-SUBTITLE
|
||
@author AUTHOR
|
||
@page
|
||
...
|
||
@end titlepage
|
||
|
||
Contrast this form with the form of a title page written using the
|
||
`@sp', `@center', and `@titlefont' commands:
|
||
|
||
@titlepage
|
||
@sp 10
|
||
@center @titlefont{Name of Manual When Printed}
|
||
@sp 2
|
||
@center Subtitle, If Any
|
||
@sp 1
|
||
@center Second subtitle
|
||
@sp 2
|
||
@center Author
|
||
@page
|
||
...
|
||
@end titlepage
|
||
|
||
|
||
File: texi.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page
|
||
|
||
Copyright Page and Permissions
|
||
------------------------------
|
||
|
||
By international treaty, the copyright notice for a book should be
|
||
either on the title page or on the back of the title page. The
|
||
copyright notice should include the year followed by the name of the
|
||
organization or person who owns the copyright.
|
||
|
||
When the copyright notice is on the back of the title page, that page
|
||
is customarily not numbered. Therefore, in Texinfo, the information on
|
||
the copyright page should be within `@titlepage' and `@end titlepage'
|
||
commands.
|
||
|
||
Use the `@page' command to cause a page break. To push the
|
||
copyright notice and the other text on the copyright page towards the
|
||
bottom of the page, you can write a somewhat mysterious line after the
|
||
`@page' command that reads like this:
|
||
|
||
@vskip 0pt plus 1filll
|
||
|
||
This is a TeX command that is not supported by the Info formatting
|
||
commands. The `@vskip' command inserts whitespace. The `0pt plus
|
||
1filll' means to put in zero points of mandatory whitespace, and as
|
||
much optional whitespace as needed to push the following text to the
|
||
bottom of the page. Note the use of three `l's in the word `filll';
|
||
this is the correct usage in TeX.
|
||
|
||
In a printed manual, the `@copyright{}' command generates a `c'
|
||
inside a circle. (In Info, it generates `(C)'.) The copyright notice
|
||
itself has the following legally defined sequence:
|
||
|
||
Copyright (C) YEAR COPYRIGHT-OWNER
|
||
|
||
It is customary to put information on how to get a manual after the
|
||
copyright notice, followed by the copying permissions for the manual.
|
||
|
||
Note that permissions must be given here as well as in the summary
|
||
segment within `@ifinfo' and `@end ifinfo' that immediately follows the
|
||
header since this text appears only in the printed manual and the
|
||
`ifinfo' text appears only in the Info file.
|
||
|
||
*Note Sample Permissions::, for the standard text.
|
||
|
||
|
||
File: texi.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page
|
||
|
||
Heading Generation
|
||
------------------
|
||
|
||
An `@end titlepage' command on a line by itself not only marks the
|
||
end of the title and copyright pages, but also causes TeX to start
|
||
generating page headings and page numbers.
|
||
|
||
To repeat what is said elsewhere, Texinfo has two standard page
|
||
heading formats, one for documents which are printed on one side of
|
||
each sheet of paper (single-sided printing), and the other for
|
||
documents which are printed on both sides of each sheet (double-sided
|
||
printing). (*Note `@setchapternewpage': setchapternewpage.) You can
|
||
specify these formats in different ways:
|
||
|
||
* The conventional way is to write an `@setchapternewpage' command
|
||
before the title page commands, and then have the `@end titlepage'
|
||
command start generating page headings in the manner desired.
|
||
(*Note `@setchapternewpage': setchapternewpage.)
|
||
|
||
* Alternatively, you can use the `@headings' command to prevent page
|
||
headings from being generated or to start them for either single or
|
||
double-sided printing. (Write an `@headings' command immediately
|
||
after the `@end titlepage' command. *Note The `@headings'
|
||
Command: headings on off, for more information.)
|
||
|
||
* Or, you may specify your own page heading and footing format.
|
||
*Note Page Headings: Headings, for detailed information about page
|
||
headings and footings.
|
||
|
||
Most documents are formatted with the standard single-sided or
|
||
double-sided format, using `@setchapternewpage odd' for double-sided
|
||
printing and no `@setchapternewpage' command for single-sided printing.
|
||
|
||
|
||
File: texi.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page
|
||
|
||
The `@headings' Command
|
||
-----------------------
|
||
|
||
The `@headings' command is rarely used. It specifies what kind of
|
||
page headings and footings to print on each page. Usually, this is
|
||
controlled by the `@setchapternewpage' command. You need the
|
||
`@headings' command only if the `@setchapternewpage' command does not
|
||
do what you want, or if you want to turn off pre-defined page headings
|
||
prior to defining your own. Write an `@headings' command immediately
|
||
after the `@end titlepage' command.
|
||
|
||
There are four ways to use the `@headings' command:
|
||
|
||
`@headings off'
|
||
Turn off printing of page headings.
|
||
|
||
`@headings single'
|
||
Turn on page headings appropriate for single-sided printing.
|
||
|
||
`@headings double'
|
||
`@headings on'
|
||
Turn on page headings appropriate for double-sided printing. The
|
||
two commands, `@headings on' and `@headings double', are
|
||
synonymous.
|
||
|
||
For example, suppose you write `@setchapternewpage off' before the
|
||
`@titlepage' command to tell TeX to start a new chapter on the same
|
||
page as the end of the last chapter. This command also causes TeX to
|
||
typeset page headers for single-sided printing. To cause TeX to
|
||
typeset for double sided printing, write `@headings double' after the
|
||
`@end titlepage' command.
|
||
|
||
You can stop TeX from generating any page headings at all by writing
|
||
`@headings off' on a line of its own immediately after the line
|
||
containing the `@end titlepage' command, like this:
|
||
|
||
@end titlepage
|
||
@headings off
|
||
|
||
The `@headings off' command overrides the `@end titlepage' command,
|
||
which would otherwise cause TeX to print page headings.
|
||
|
||
You can also specify your own style of page heading and footing.
|
||
*Note Page Headings: Headings, for more information.
|
||
|
||
|
||
File: texi.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File
|
||
|
||
The `Top' Node and Master Menu
|
||
==============================
|
||
|
||
The `Top' node is the node from which you enter an Info file.
|
||
|
||
A `Top' node should contain a brief description of the Info file and
|
||
an extensive, master menu for the whole Info file. This helps the
|
||
reader understand what the Info file is about. Also, you should write
|
||
the version number of the program to which the Info file applies; or,
|
||
at least, the edition number.
|
||
|
||
The contents of the `Top' node should appear only in the Info file;
|
||
none of it should appear in printed output, so enclose it between
|
||
`@ifinfo' and `@end ifinfo' commands. (TeX does not print either an
|
||
`@node' line or a menu; they appear only in Info; strictly speaking,
|
||
you are not required to enclose these parts between `@ifinfo' and `@end
|
||
ifinfo', but it is simplest to do so. *Note Conditionally Visible
|
||
Text: Conditionals.)
|
||
|
||
* Menu:
|
||
|
||
* Title of Top Node:: Sketch what the file is about.
|
||
* Master Menu Parts:: A master menu has three or more parts.
|
||
|
||
|
||
File: texi.info, Node: Title of Top Node, Next: Master Menu Parts, Up: The Top Node
|
||
|
||
`Top' Node Title
|
||
----------------
|
||
|
||
Sometimes, you will want to place an `@top' sectioning command line
|
||
containing the title of the document immediately after the `@node Top'
|
||
line (*note The `@top' Sectioning Command: makeinfo top command., for
|
||
more information).
|
||
|
||
For example, the beginning of the Top node of this manual contains an
|
||
`@top' sectioning command, a short description, and edition and version
|
||
information. It looks like this:
|
||
|
||
...
|
||
@end titlepage
|
||
|
||
@ifinfo
|
||
@node Top, Copying, (dir), (dir)
|
||
@top Texinfo
|
||
|
||
Texinfo is a documentation system...
|
||
|
||
This is edition...
|
||
...
|
||
@end ifinfo
|
||
|
||
@menu
|
||
* Copying:: Texinfo is freely
|
||
redistributable.
|
||
* Overview:: What is Texinfo?
|
||
...
|
||
@end menu
|
||
|
||
In a `Top' node, the `Previous', and `Up' nodes usually refer to the
|
||
top level directory of the whole Info system, which is called `(dir)'.
|
||
The `Next' node refers to the first node that follows the main or master
|
||
menu, which is usually the copying permissions, introduction, or first
|
||
chapter.
|
||
|
||
|
||
File: texi.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node
|
||
|
||
Parts of a Master Menu
|
||
----------------------
|
||
|
||
A "master menu" is a detailed main menu listing all the nodes in a
|
||
file.
|
||
|
||
A master menu is enclosed in `@menu' and `@end menu' commands and
|
||
does not appear in the printed document.
|
||
|
||
Generally, a master menu is divided into parts.
|
||
|
||
* The first part contains the major nodes in the Texinfo file: the
|
||
nodes for the chapters, chapter-like sections, and the appendices.
|
||
|
||
* The second part contains nodes for the indices.
|
||
|
||
* The third and subsequent parts contain a listing of the other,
|
||
lower level nodes, often ordered by chapter. This way, rather
|
||
than go through an intermediary menu, an inquirer can go directly
|
||
to a particular node when searching for specific information.
|
||
These menu items are not required; add them if you think they are a
|
||
convenience.
|
||
|
||
Each section in the menu can be introduced by a descriptive line. So
|
||
long as the line does not begin with an asterisk, it will not be
|
||
treated as a menu entry. (*Note Writing a Menu::, for more
|
||
information.)
|
||
|
||
For example, the master menu for this manual looks like the following
|
||
(but has many more entries):
|
||
|
||
@menu
|
||
* Copying:: Texinfo is freely
|
||
redistributable.
|
||
* Overview:: What is Texinfo?
|
||
* Texinfo Mode:: Special features in GNU Emacs.
|
||
...
|
||
...
|
||
* Command and Variable Index::
|
||
An entry for each @-command.
|
||
* Concept Index:: An entry for each concept.
|
||
|
||
--- The Detailed Node Listing ---
|
||
|
||
Overview of Texinfo
|
||
|
||
* Info Files:: What is an Info file?
|
||
* Printed Manuals:: Characteristics of
|
||
a printed manual.
|
||
...
|
||
...
|
||
|
||
Using Texinfo Mode
|
||
|
||
* Info on a Region:: Formatting part of a file
|
||
for Info.
|
||
...
|
||
...
|
||
@end menu
|
||
|
||
|
||
File: texi.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File
|
||
|
||
Software Copying Permissions
|
||
============================
|
||
|
||
If the Texinfo file has a section containing the "General Public
|
||
License" and the distribution information and a warranty disclaimer for
|
||
the software that is documented, this section usually follows the `Top'
|
||
node. The General Public License is very important to Project GNU
|
||
software. It ensures that you and others will continue to have a right
|
||
to use and share the software.
|
||
|
||
The copying and distribution information and the disclaimer are
|
||
followed by an introduction or else by the first chapter of the manual.
|
||
|
||
Although an introduction is not a required part of a Texinfo file, it
|
||
is very helpful. Ideally, it should state clearly and concisely what
|
||
the file is about and who would be interested in reading it. In
|
||
general, an introduction would follow the licensing and distribution
|
||
information, although sometimes people put it earlier in the document.
|
||
Usually, an introduction is put in an `@unnumbered' section. (*Note
|
||
The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
|
||
|
||
|
||
File: texi.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top
|
||
|
||
Ending a Texinfo File
|
||
*********************
|
||
|
||
The end of a Texinfo file should include the commands that create
|
||
indices and generate detailed and summary tables of contents. And it
|
||
must include the `@bye' command that marks the last line processed by
|
||
TeX.
|
||
|
||
For example:
|
||
|
||
@node Concept Index, , Variables Index, Top
|
||
@c node-name, next, previous, up
|
||
@unnumbered Concept Index
|
||
|
||
@printindex cp
|
||
|
||
@contents
|
||
@bye
|
||
|
||
* Menu:
|
||
|
||
* Printing Indices & Menus:: How to print an index in hardcopy and
|
||
generate index menus in Info.
|
||
* Contents:: How to create a table of contents.
|
||
* File End:: How to mark the end of a file.
|
||
|
||
|
||
File: texi.info, Node: Printing Indices & Menus, Next: Contents, Up: Ending a File
|
||
|
||
Index Menus and Printing an Index
|
||
=================================
|
||
|
||
To print an index means to include it as part of a manual or Info
|
||
file. This does not happen automatically just because you use
|
||
`@cindex' or other index-entry generating commands in the Texinfo file;
|
||
those just cause the raw data for the index to be accumulated. To
|
||
generate an index, you must include the `@printindex' command at the
|
||
place in the document where you want the index to appear. Also, as
|
||
part of the process of creating a printed manual, you must run a
|
||
program called `texindex' (*note Format/Print Hardcopy::.) to sort the
|
||
raw data to produce a sorted index file. The sorted index file is what
|
||
is actually used to print the index.
|
||
|
||
Texinfo offers six different types of predefined index: the concept
|
||
index, the function index, the variables index, the keystroke index, the
|
||
program index, and the data type index (*note Predefined Indices::.).
|
||
Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
|
||
and `tp'. You may merge indices, or put them into separate sections
|
||
(*note Combining Indices::.); or you may define your own indices (*note
|
||
Defining New Indices: New Indices.).
|
||
|
||
The `@printindex' command takes a two-letter index name, reads the
|
||
corresponding sorted index file and formats it appropriately into an
|
||
index.
|
||
|
||
The `@printindex' command does not generate a chapter heading for
|
||
the index. Consequently, you should precede the `@printindex' command
|
||
with a suitable section or chapter command (usually `@unnumbered') to
|
||
supply the chapter heading and put the index into the table of
|
||
contents. Precede the `@unnumbered' command with an `@node' line.
|
||
|
||
For example:
|
||
|
||
@node Variable Index, Concept Index, Function Index, Top
|
||
@comment node-name, next, previous, up
|
||
@unnumbered Variable Index
|
||
|
||
@printindex vr
|
||
|
||
@node Concept Index, , Variable Index, Top
|
||
@comment node-name, next, previous, up
|
||
@unnumbered Concept Index
|
||
|
||
@printindex cp
|
||
|
||
@summarycontents
|
||
@contents
|
||
@bye
|
||
|
||
(Readers often prefer that the concept index come last in a book, since
|
||
that makes it easiest to find.)
|
||
|
||
|
||
File: texi.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File
|
||
|
||
Generating a Table of Contents
|
||
==============================
|
||
|
||
The `@chapter', `@section', and other structuring commands supply
|
||
the information to make up a table of contents, but they do not cause
|
||
an actual table to appear in the manual. To do this, you must use the
|
||
`@contents' and `@summarycontents' commands:
|
||
|
||
`@contents'
|
||
Generate a table of contents in a printed manual, including all
|
||
chapters, sections, subsections, etc., as well as appendices and
|
||
unnumbered chapters. (Headings generated by the `@heading' series
|
||
of commands do not appear in the table of contents.) The
|
||
`@contents' command should be written on a line by itself.
|
||
|
||
`@shortcontents'
|
||
`@summarycontents'
|
||
(`@summarycontents' is a synonym for `@shortcontents'; the two
|
||
commands are exactly the same.)
|
||
|
||
Generate a short or summary table of contents that lists only the
|
||
chapters (and appendices and unnumbered chapters). Omit sections,
|
||
subsections and subsubsections. Only a long manual needs a short
|
||
table of contents in addition to the full table of contents.
|
||
|
||
Write the `@shortcontents' command on a line by itself right
|
||
*before* the `@contents' command.
|
||
|
||
The table of contents commands automatically generate a chapter-like
|
||
heading at the top of the first table of contents page. Write the table
|
||
of contents commands at the very end of a Texinfo file, just before the
|
||
`@bye' command, following any index sections--anything in the Texinfo
|
||
file after the table of contents commands will be omitted from the
|
||
table of contents.
|
||
|
||
When you print a manual with a table of contents, the table of
|
||
contents are printed last and numbered with roman numerals. You need
|
||
to place those pages in their proper place, after the title page,
|
||
yourself. (This is the only collating you need to do for a printed
|
||
manual. The table of contents is printed last because it is generated
|
||
after the rest of the manual is typeset.)
|
||
|
||
Here is an example of where to write table of contents commands:
|
||
|
||
INDICES...
|
||
@shortcontents
|
||
@contents
|
||
@bye
|
||
|
||
Since an Info file uses menus instead of tables of contents, the Info
|
||
formatting commands ignore the `@contents' and `@shortcontents'
|
||
commands.
|
||
|
||
|
||
File: texi.info, Node: File End, Prev: Contents, Up: Ending a File
|
||
|
||
`@bye' File Ending
|
||
==================
|
||
|
||
An `@bye' command terminates TeX or Info formatting. None of the
|
||
formatting commands see any of the file following `@bye'. The `@bye'
|
||
command should be on a line by itself.
|
||
|
||
If you wish, you may follow the `@bye' line with notes. These notes
|
||
will not be formatted and will not appear in either Info or a printed
|
||
manual; it is as if text after `@bye' were within `@ignore' ... `@end
|
||
ignore'. Also, you may follow the `@bye' line with a local variables
|
||
list. *Note Using Local Variables and the Compile Command:
|
||
Compile-Command, for more information.
|
||
|
||
|
||
File: texi.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top
|
||
|
||
Chapter Structuring
|
||
*******************
|
||
|
||
The "chapter structuring" commands divide a document into a
|
||
hierarchy of chapters, sections, subsections, and subsubsections.
|
||
These commands generate large headings; they also provide information
|
||
for the table of contents of a printed manual (*note Generating a Table
|
||
of Contents: Contents.).
|
||
|
||
The chapter structuring commands do not create an Info node
|
||
structure, so normally you should put an `@node' command immediately
|
||
before each chapter structuring command (*note Nodes::.). The only
|
||
time you are likely to use the chapter structuring commands without
|
||
using the node structuring commands is if you are writing a document
|
||
that contains no cross references and will never be transformed into
|
||
Info format.
|
||
|
||
It is unlikely that you will ever write a Texinfo file that is
|
||
intended only as an Info file and not as a printable document. If you
|
||
do, you might still use chapter structuring commands to create a
|
||
heading at the top of each node--but you don't need to.
|
||
|
||
* Menu:
|
||
|
||
* Tree Structuring:: A manual is like an upside down tree ...
|
||
* Structuring Command Types:: How to divide a manual into parts.
|
||
* makeinfo top:: The `@top' command, part of the `Top' node.
|
||
* chapter::
|
||
* unnumbered & appendix::
|
||
* majorheading & chapheading::
|
||
* section::
|
||
* unnumberedsec appendixsec heading::
|
||
* subsection::
|
||
* unnumberedsubsec appendixsubsec subheading::
|
||
* subsubsection:: Commands for the lowest level sections.
|
||
|
||
|
||
File: texi.info, Node: Tree Structuring, Next: Structuring Command Types, Up: Structuring
|
||
|
||
Tree Structure of Sections
|
||
==========================
|
||
|
||
A Texinfo file is usually structured like a book with chapters,
|
||
sections, subsections, and the like. This structure can be visualized
|
||
as a tree (or rather as an upside-down tree) with the root at the top
|
||
and the levels corresponding to chapters, sections, subsection, and
|
||
subsubsections.
|
||
|
||
Here is a diagram that shows a Texinfo file with three chapters,
|
||
each of which has two sections.
|
||
|
||
Top
|
||
|
|
||
-------------------------------------
|
||
| | |
|
||
Chapter 1 Chapter 2 Chapter 3
|
||
| | |
|
||
-------- -------- --------
|
||
| | | | | |
|
||
Section Section Section Section Section Section
|
||
1.1 1.2 2.1 2.2 3.1 3.2
|
||
|
||
In a Texinfo file that has this structure, the beginning of Chapter 2
|
||
looks like this:
|
||
|
||
@node Chapter 2, Chapter 3, Chapter 1, top
|
||
@chapter Chapter 2
|
||
|
||
The chapter structuring commands are described in the sections that
|
||
follow; the `@node' and `@menu' commands are described in following
|
||
chapters. (*Note Nodes::, and see *Note Menus::.)
|
||
|
||
|
||
File: texi.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring
|
||
|
||
Types of Structuring Command
|
||
============================
|
||
|
||
The chapter structuring commands fall into four groups or series,
|
||
each of which contains structuring commands corresponding to the
|
||
hierarchical levels of chapters, sections, subsections, and
|
||
subsubsections.
|
||
|
||
The four groups are the `@chapter' series, the `@unnumbered' series,
|
||
the `@appendix' series, and the `@heading' series.
|
||
|
||
Each command produces titles that have a different appearance on the
|
||
printed page or Info file; only some of the commands produce titles
|
||
that are listed in the table of contents of a printed book or manual.
|
||
|
||
* The `@chapter' and `@appendix' series of commands produce numbered
|
||
or lettered entries both in the body of a printed work and in its
|
||
table of contents.
|
||
|
||
* The `@unnumbered' series of commands produce unnumbered entries
|
||
both in the body of a printed work and in its table of contents.
|
||
The `@top' command, which has a special use, is a member of this
|
||
series (*note `@top': makeinfo top.).
|
||
|
||
* The `@heading' series of commands produce unnumbered headings that
|
||
do not appear in a table of contents. The heading commands never
|
||
start a new page.
|
||
|
||
* The `@majorheading' command produces results similar to using the
|
||
`@chapheading' command but generates a larger vertical whitespace
|
||
before the heading.
|
||
|
||
* When an `@setchapternewpage' command says to do so, the
|
||
`@chapter', `@unnumbered', and `@appendix' commands start new
|
||
pages in the printed manual; the `@heading' commands do not.
|
||
|
||
Here are the four groups of chapter structuring commands:
|
||
|
||
No new pages
|
||
Numbered Unnumbered Lettered and numbered Unnumbered
|
||
In contents In contents In contents Not in contents
|
||
|
||
@top @majorheading
|
||
@chapter @unnumbered @appendix @chapheading
|
||
@section @unnumberedsec @appendixsec @heading
|
||
@subsection @unnumberedsubsec @appendixsubsec @subheading
|
||
@subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
|
||
|
||
|
||
File: texi.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring
|
||
|
||
`@top'
|
||
======
|
||
|
||
The `@top' command is a special sectioning command that you use only
|
||
after an `@node Top' line at the beginning of a Texinfo file. The
|
||
`@top' command tells the `makeinfo' formatter which node is the `Top'
|
||
node. It has the same typesetting effect as `@unnumbered' (*note
|
||
`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed
|
||
information, see *Note The `@top' Command: makeinfo top command.
|
||
|
||
|
||
File: texi.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring
|
||
|
||
`@chapter'
|
||
==========
|
||
|
||
`@chapter' identifies a chapter in the document. Write the command
|
||
at the beginning of a line and follow it on the same line by the title
|
||
of the chapter.
|
||
|
||
For example, this chapter in this manual is entitled "Chapter
|
||
Structuring"; the `@chapter' line looks like this:
|
||
|
||
@chapter Chapter Structuring
|
||
|
||
In TeX, the `@chapter' command creates a chapter in the document,
|
||
specifying the chapter title. The chapter is numbered automatically.
|
||
|
||
In Info, the `@chapter' command causes the title to appear on a line
|
||
by itself, with a line of asterisks inserted underneath. Thus, in
|
||
Info, the above example produces the following output:
|
||
|
||
Chapter Structuring
|
||
*******************
|
||
|
||
|
||
File: texi.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring
|
||
|
||
`@unnumbered', `@appendix'
|
||
==========================
|
||
|
||
Use the `@unnumbered' command to create a chapter that appears in a
|
||
printed manual without chapter numbers of any kind. Use the
|
||
`@appendix' command to create an appendix in a printed manual that is
|
||
labelled by letter instead of by number.
|
||
|
||
For Info file output, the `@unnumbered' and `@appendix' commands are
|
||
equivalent to `@chapter': the title is printed on a line by itself with
|
||
a line of asterisks underneath. (*Note `@chapter': chapter.)
|
||
|
||
To create an appendix or an unnumbered chapter, write an `@appendix'
|
||
or `@unnumbered' command at the beginning of a line and follow it on
|
||
the same line by the title, as you would if you were creating a chapter.
|
||
|
||
|
||
File: texi.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring
|
||
|
||
`@majorheading', `@chapheading'
|
||
===============================
|
||
|
||
The `@majorheading' and `@chapheading' commands put chapter-like
|
||
headings in the body of a document.
|
||
|
||
However, neither command causes TeX to produce a numbered heading or
|
||
an entry in the table of contents; and neither command causes TeX to
|
||
start a new page in a printed manual.
|
||
|
||
In TeX, an `@majorheading' command generates a larger vertical
|
||
whitespace before the heading than an `@chapheading' command but is
|
||
otherwise the same.
|
||
|
||
In Info, the `@majorheading' and `@chapheading' commands are
|
||
equivalent to `@chapter': the title is printed on a line by itself with
|
||
a line of asterisks underneath. (*Note `@chapter': chapter.)
|
||
|
||
|
||
File: texi.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring
|
||
|
||
`@section'
|
||
==========
|
||
|
||
In a printed manual, an `@section' command identifies a numbered
|
||
section within a chapter. The section title appears in the table of
|
||
contents. In Info, an `@section' command provides a title for a
|
||
segment of text, underlined with `='.
|
||
|
||
This section is headed with an `@section' command and looks like
|
||
this in the Texinfo file:
|
||
|
||
@section @code{@@section}
|
||
|
||
To create a section, write the `@section' command at the beginning
|
||
of a line and follow it on the same line by the section title.
|
||
|
||
Thus,
|
||
|
||
@section This is a section
|
||
|
||
produces
|
||
|
||
This is a section
|
||
=================
|
||
|
||
in Info.
|
||
|
||
|
||
File: texi.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring
|
||
|
||
`@unnumberedsec', `@appendixsec', `@heading'
|
||
============================================
|
||
|
||
The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
|
||
respectively, the unnumbered, appendix-like, and heading-like
|
||
equivalents of the `@section' command. (*Note `@section': section.)
|
||
|
||
`@unnumberedsec'
|
||
The `@unnumberedsec' command may be used within an unnumbered
|
||
chapter or within a regular chapter or appendix to provide an
|
||
unnumbered section.
|
||
|
||
`@appendixsec'
|
||
`@appendixsection'
|
||
`@appendixsection' is a longer spelling of the `@appendixsec'
|
||
command; the two are synonymous.
|
||
|
||
Conventionally, the `@appendixsec' or `@appendixsection' command
|
||
is used only within appendices.
|
||
|
||
`@heading'
|
||
You may use the `@heading' command anywhere you wish for a
|
||
section-style heading that will not appear in the table of
|
||
contents.
|
||
|
||
|
||
File: texi.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring
|
||
|
||
The `@subsection' Command
|
||
=========================
|
||
|
||
Subsections are to sections as sections are to chapters. (*Note
|
||
`@section': section.) In Info, subsection titles are underlined with
|
||
`-'. For example,
|
||
|
||
@subsection This is a subsection
|
||
|
||
produces
|
||
|
||
This is a subsection
|
||
--------------------
|
||
|
||
In a printed manual, subsections are listed in the table of contents
|
||
and are numbered three levels deep.
|
||
|
||
|
||
File: texi.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
|
||
|
||
The `@subsection'-like Commands
|
||
===============================
|
||
|
||
The `@unnumberedsubsec', `@appendixsubsec', and `@subheading'
|
||
commands are, respectively, the unnumbered, appendix-like, and
|
||
heading-like equivalents of the `@subsection' command. (*Note
|
||
`@subsection': subsection.)
|
||
|
||
In Info, the `@subsection'-like commands generate a title underlined
|
||
with hyphens. In a printed manual, an `@subheading' command produces a
|
||
heading like that of a subsection except that it is not numbered and
|
||
does not appear in the table of contents. Similarly, an
|
||
`@unnumberedsubsec' command produces an unnumbered heading like that of
|
||
a subsection and an `@appendixsubsec' command produces a
|
||
subsection-like heading labelled with a letter and numbers; both of
|
||
these commands produce headings that appear in the table of contents.
|
||
|
||
|
||
File: texi.info, Node: subsubsection, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
|
||
|
||
The `subsub' Commands
|
||
=====================
|
||
|
||
The fourth and lowest level sectioning commands in Texinfo are the
|
||
`subsub' commands. They are:
|
||
|
||
`@subsubsection'
|
||
Subsubsections are to subsections as subsections are to sections.
|
||
(*Note `@subsection': subsection.) In a printed manual,
|
||
subsubsection titles appear in the table of contents and are
|
||
numbered four levels deep.
|
||
|
||
`@unnumberedsubsubsec'
|
||
Unnumbered subsubsection titles appear in the table of contents of
|
||
a printed manual, but lack numbers. Otherwise, unnumbered
|
||
subsubsections are the same as subsubsections. In Info, unnumbered
|
||
subsubsections look exactly like ordinary subsubsections.
|
||
|
||
`@appendixsubsubsec'
|
||
Conventionally, appendix commands are used only for appendices and
|
||
are lettered and numbered appropriately in a printed manual. They
|
||
also appear in the table of contents. In Info, appendix
|
||
subsubsections look exactly like ordinary subsubsections.
|
||
|
||
`@subsubheading'
|
||
The `@subsubheading' command may be used anywhere that you need a
|
||
small heading that will not appear in the table of contents. In
|
||
Info, subsubheadings look exactly like ordinary subsubsection
|
||
headings.
|
||
|
||
In Info, `subsub' titles are underlined with periods. For example,
|
||
|
||
@subsubsection This is a subsubsection
|
||
|
||
produces
|
||
|
||
This is a subsubsection
|
||
.......................
|
||
|
||
|
||
File: texi.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
|
||
|
||
Nodes
|
||
*****
|
||
|
||
"Nodes" are the primary segments of a Texinfo file. They do not
|
||
themselves impose a hierarchic or any other kind of structure on a file.
|
||
Nodes contain "node pointers" that name other nodes, and can contain
|
||
"menus" which are lists of nodes. In Info, the movement commands can
|
||
carry you to a pointed-to node or to a node listed in a menu. Node
|
||
pointers and menus provide structure for Info files just as chapters,
|
||
sections, subsections, and the like, provide structure for printed
|
||
books.
|
||
|
||
* Menu:
|
||
|
||
* Two Paths:: Different commands to structure
|
||
Info output and printed output.
|
||
* Node Menu Illustration:: A diagram, and sample nodes and menus.
|
||
* node:: How to write a node, in detail.
|
||
* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
|
||
|
||
|
||
File: texi.info, Node: Two Paths, Next: Node Menu Illustration, Up: Nodes
|
||
|
||
Two Paths
|
||
=========
|
||
|
||
The node and menu commands and the chapter structuring commands are
|
||
independent of each other:
|
||
|
||
* In Info, node and menu commands provide structure. The chapter
|
||
structuring commands generate headings with different kinds of
|
||
underlining--asterisks for chapters, hyphens for sections, and so
|
||
on; they do nothing else.
|
||
|
||
* In TeX, the chapter structuring commands generate chapter and
|
||
section numbers and tables of contents. The node and menu
|
||
commands provide information for cross references; they do nothing
|
||
else.
|
||
|
||
You can use node pointers and menus to structure an Info file any way
|
||
you want; and you can write a Texinfo file so that its Info output has a
|
||
different structure than its printed output. However, most Texinfo
|
||
files are written such that the structure for the Info output
|
||
corresponds to the structure for the printed output. It is not
|
||
convenient to do otherwise.
|
||
|
||
Generally, printed output is structured in a tree-like hierarchy in
|
||
which the chapters are the major limbs from which the sections branch
|
||
out. Similarly, node pointers and menus are organized to create a
|
||
matching structure in the Info output.
|
||
|
||
|
||
File: texi.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes
|
||
|
||
Node and Menu Illustration
|
||
==========================
|
||
|
||
Here is a copy of the diagram shown earlier that illustrates a
|
||
Texinfo file with three chapters, each of which contains two sections.
|
||
|
||
Note that the "root" is at the top of the diagram and the "leaves"
|
||
are at the bottom. This is how such a diagram is drawn conventionally;
|
||
it illustrates an upside-down tree. For this reason, the root node is
|
||
called the `Top' node, and `Up' node pointers carry you closer to the
|
||
root.
|
||
|
||
Top
|
||
|
|
||
-------------------------------------
|
||
| | |
|
||
Chapter 1 Chapter 2 Chapter 3
|
||
| | |
|
||
-------- -------- --------
|
||
| | | | | |
|
||
Section Section Section Section Section Section
|
||
1.1 1.2 2.1 2.2 3.1 3.2
|
||
|
||
Write the beginning of the node for Chapter 2 like this:
|
||
|
||
@node Chapter 2, Chapter 3, Chapter 1, top
|
||
@comment node-name, next, previous, up
|
||
|
||
This `@node' line says that the name of this node is "Chapter 2", the
|
||
name of the `Next' node is "Chapter 3", the name of the `Previous' node
|
||
is "Chapter 1", and the name of the `Up' node is "Top".
|
||
|
||
*Please Note:* `Next' refers to the next node at the same
|
||
hierarchical level in the manual, not necessarily to the next node
|
||
within the Texinfo file. In the Texinfo file, the subsequent node
|
||
may be at a lower level--a section-level node may follow a
|
||
chapter-level node, and a subsection-level node may follow a
|
||
section-level node. `Next' and `Previous' refer to nodes at the
|
||
*same* hierarchical level. (The `Top' node contains the exception
|
||
to this rule. Since the `Top' node is the only node at that
|
||
level, `Next' refers to the first following node, which is almost
|
||
always a chapter or chapter-level node.)
|
||
|
||
To go to Sections 2.1 and 2.2 using Info, you need a menu inside
|
||
Chapter 2. (*Note Menus::.) You would write the menu just before the
|
||
beginning of Section 2.1, like this:
|
||
|
||
@menu
|
||
* Sect. 2.1:: Description of this section.
|
||
* Sect. 2.2::
|
||
@end menu
|
||
|
||
Write the node for Sect. 2.1 like this:
|
||
|
||
@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
|
||
@comment node-name, next, previous, up
|
||
|
||
In Info format, the `Next' and `Previous' pointers of a node usually
|
||
lead to other nodes at the same level--from chapter to chapter or from
|
||
section to section (sometimes, as shown, the `Previous' pointer points
|
||
up); an `Up' pointer usually leads to a node at the level above (closer
|
||
to the `Top' node); and a `Menu' leads to nodes at a level below (closer
|
||
to `leaves'). (A cross reference can point to a node at any level; see
|
||
*Note Cross References::.)
|
||
|
||
Usually, an `@node' command and a chapter structuring command are
|
||
used in sequence, along with indexing commands. (You may follow the
|
||
`@node' line with a comment line that reminds you which pointer is
|
||
which.)
|
||
|
||
Here is the beginning of the chapter in this manual called "Ending a
|
||
Texinfo File". This shows an `@node' line followed by a comment line,
|
||
an `@chapter' line, and then by indexing lines.
|
||
|
||
@node Ending a File, Structuring, Beginning a File, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter Ending a Texinfo File
|
||
@cindex Ending a Texinfo file
|
||
@cindex Texinfo file ending
|
||
@cindex File ending
|
||
|
||
|
||
File: texi.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes
|
||
|
||
The `@node' Command
|
||
===================
|
||
|
||
A "node" is a segment of text that begins at an `@node' command and
|
||
continues until the next `@node' command. The definition of node is
|
||
different from that for chapter or section. A chapter may contain
|
||
sections and a section may contain subsections; but a node cannot
|
||
contain subnodes; the text of a node continues only until the next
|
||
`@node' command in the file. A node usually contains only one chapter
|
||
structuring command, the one that follows the `@node' line. On the
|
||
other hand, in printed output nodes are used only for cross references,
|
||
so a chapter or section may contain any number of nodes. Indeed, a
|
||
chapter usually contains several nodes, one for each section,
|
||
subsection, and subsubsection.
|
||
|
||
To create a node, write an `@node' command at the beginning of a
|
||
line, and follow it with four arguments, separated by commas, on the
|
||
rest of the same line. These arguments are the name of the node, and
|
||
the names of the `Next', `Previous', and `Up' pointers, in that order.
|
||
You may insert spaces before each pointer if you wish; the spaces are
|
||
ignored. You must write the name of the node, and the names of the
|
||
`Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
|
||
the formatters fail. (*note info: (info)Top, for more information
|
||
about nodes in Info.)
|
||
|
||
Usually, you write one of the chapter-structuring command lines
|
||
immediately after an `@node' line--for example, an `@section' or
|
||
`@subsection' line. (*Note Types of Structuring Command: Structuring
|
||
Command Types.)
|
||
|
||
*Please note:* The GNU Emacs Texinfo mode updating commands work
|
||
only with Texinfo files in which `@node' lines are followed by
|
||
chapter structuring lines. *Note Updating Requirements::.
|
||
|
||
TeX uses `@node' lines to identify the names to use for cross
|
||
references. For this reason, you must write `@node' lines in a Texinfo
|
||
file that you intend to format for printing, even if you do not intend
|
||
to format it for Info. (Cross references, such as the one at the end
|
||
of this sentence, are made with `@xref' and its related commands; see
|
||
*Note Cross References::.)
|
||
|
||
* Menu:
|
||
|
||
* Node Names:: How to choose node and pointer names.
|
||
* Writing a Node:: How to write an `@node' line.
|
||
* Node Line Tips:: Keep names short.
|
||
* Node Line Requirements:: Keep names unique, without @-commands.
|
||
* First Node:: How to write a `Top' node.
|
||
* makeinfo top command:: How to use the `@top' command.
|
||
* Top Node Summary:: Write a brief description for readers.
|
||
|
||
|
||
File: texi.info, Node: Node Names, Next: Writing a Node, Up: node
|
||
|
||
Choosing Node and Pointer Names
|
||
-------------------------------
|
||
|
||
The name of a node identifies the node. The pointers enable you to
|
||
reach other nodes and consist of the names of those nodes.
|
||
|
||
Normally, a node's `Up' pointer contains the name of the node whose
|
||
menu mentions that node. The node's `Next' pointer contains the name
|
||
of the node that follows that node in that menu and its `Previous'
|
||
pointer contains the name of the node that precedes it in that menu.
|
||
When a node's `Previous' node is the same as its `Up' node, both node
|
||
pointers name the same node.
|
||
|
||
Usually, the first node of a Texinfo file is the `Top' node, and its
|
||
`Up' and `Previous' pointers point to the `dir' file, which contains
|
||
the main menu for all of Info.
|
||
|
||
The `Top' node itself contains the main or master menu for the
|
||
manual. Also, it is helpful to include a brief description of the
|
||
manual in the `Top' node. *Note First Node::, for information on how
|
||
to write the first node of a Texinfo file.
|
||
|
||
|
||
File: texi.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node
|
||
|
||
How to Write an `@node' Line
|
||
----------------------------
|
||
|
||
The easiest way to write an `@node' line is to write `@node' at the
|
||
beginning of a line and then the name of the node, like this:
|
||
|
||
@node NODE-NAME
|
||
|
||
If you are using GNU Emacs, you can use the update node commands
|
||
provided by Texinfo mode to insert the names of the pointers; or you
|
||
can leave the pointers out of the Texinfo file and let `makeinfo'
|
||
insert node pointers into the Info file it creates. (*Note Texinfo
|
||
Mode::, and *Note makeinfo Pointer Creation::.)
|
||
|
||
Alternatively, you can insert the `Next', `Previous', and `Up'
|
||
pointers yourself. If you do this, you may find it helpful to use the
|
||
Texinfo mode keyboard command `C-c C-c n'. This command inserts
|
||
`@node' and a comment line listing the names of the pointers in their
|
||
proper order. The comment line helps you keep track of which arguments
|
||
are for which pointers. This comment line is especially useful if you
|
||
are not familiar with Texinfo.
|
||
|
||
The template for a node line with `Next', `Previous', and `Up'
|
||
pointers looks like this:
|
||
|
||
@node NODE-NAME, NEXT, PREVIOUS, UP
|
||
|
||
If you wish, you can ignore `@node' lines altogether in your first
|
||
draft and then use the `texinfo-insert-node-lines' command to create
|
||
`@node' lines for you. However, we do not recommend this practice. It
|
||
is better to name the node itself at the same time that you write a
|
||
segment so you can easily make cross references. A large number of
|
||
cross references are an especially important feature of a good Info
|
||
file.
|
||
|
||
After you have inserted an `@node' line, you should immediately
|
||
write an @-command for the chapter or section and insert its name.
|
||
Next (and this is important!), put in several index entries. Usually,
|
||
you will find at least two and often as many as four or five ways of
|
||
referring to the node in the index. Use them all. This will make it
|
||
much easier for people to find the node.
|
||
|
||
|
||
File: texi.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node
|
||
|
||
`@node' Line Tips
|
||
-----------------
|
||
|
||
Here are three suggestions:
|
||
|
||
* Try to pick node names that are informative but short.
|
||
|
||
In the Info file, the file name, node name, and pointer names are
|
||
all inserted on one line, which may run into the right edge of the
|
||
window. (This does not cause a problem with Info, but is ugly.)
|
||
|
||
* Try to pick node names that differ from each other near the
|
||
beginnings of their names. This way, it is easy to use automatic
|
||
name completion in Info.
|
||
|
||
* By convention, node names are capitalized just as they would be for
|
||
section or chapter titles--initial and significant words are
|
||
capitalized; others are not.
|
||
|