Certain pieces of information must be provided at the beginning of a Texinfo file, such as the name of the file and the title of the document.
Generally, the beginning of a Texinfo file has four parts:
@ifinfo and
@end ifinfo commands so that the formatters place it only
in the Info file.
@titlepage and
@end titlepage commands. The title and copyright page appear
only in the printed manual.
Also, optionally, you may include the copying conditions for a program and a warranty disclaimer. The copying section will be followed by an introduction or else by the first chapter of the manual.
Since the copyright notice and copying permissions for the Texinfo document (in contrast to the copying permissions for a program) are in parts that appear only in the Info file or only in the printed manual, this information must be given twice.
The following sample shows what is needed.
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename name-of-info-file
@settitle name-of-manual
@setchapternewpage odd
@c %**end of header
@ifinfo
This file documents ...
Copyright year copyright-owner
Permission is granted to ...
@end ifinfo
@c This title page illustrates only one of the
@c two methods of forming a title page.
@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author
@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner
Published by ...
Permission is granted to ...
@end titlepage
@node Top, Overview, , (dir)
@ifinfo
This document describes ...
This document applies to version ...
of the program named ...
@end ifinfo
@menu
* Copying:: Your rights and freedoms.
* First Chapter:: Getting started ...
* Second Chapter:: ...
...
...
@end menu
@node First Chapter, Second Chapter, top, top
@comment node-name, next, previous, up
@chapter First Chapter
@cindex Index entry for First Chapter
Texinfo files start with at least three lines that provide Info and
TeX with necessary information. These are the \input
texinfo line, the @settitle line, and the
@setfilename line. If you want to run TeX on just a part
of the Texinfo File, you must write the @settitle
and @setfilename lines between start-of-header and end-of-header
lines.
Thus, the beginning of a Texinfo file looks like this:
\input texinfo @c -*-texinfo-*- @setfilename sample.info @settitle Sample Document
or else like this:
\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename sample.info @settitle Sample Document @c %**end of header
Every Texinfo file that is to be the top-level input to TeX must begin with a line that looks like this:
\input texinfo @c -*-texinfo-*-
This line serves two functions:
Write a start-of-header line on the second line of a Texinfo file.
Follow the start-of-header line with @setfilename and
@settitle lines and, optionally, with other command lines, such
as @smallbook or @footnotestyle; and then by an
end-of-header line (see section 3.3.8 End of Header).
With these lines, you can format part of a Texinfo file for Info or typeset part for printing.
A start-of-header line looks like this:
@c %**start of header
The odd string of characters, `%**', is to ensure that no other comment is accidentally taken for a start-of-header line.
@setfilename
In order to serve as the primary input file for either makeinfo
or TeX, a Texinfo file must contain a line that looks like this:
@setfilename info-file-name
Write the @setfilename command at the beginning of a line and
follow it on the same line by the Info file name. Do not write anything
else on the line; anything on the line after the command is considered
part of the file name, including what would otherwise be a
comment.
The @setfilename line specifies the name of the output file to
be generated. This name should be different from the name of the
Texinfo file. There are two conventions for choosing the name: you can
either remove the extension (such as `.texi') from the input file
name, or replace it with the `.info' extension. When producing
HTML output, makeinfo will replace any extension with
`html', or add `.html' if the given name has no extension.
Some operating systems cannot handle long file names. You can run into
a problem even when the file name you specify is itself short enough.
This occurs because the Info formatters split a long Info file into
short indirect subfiles, and name them by appending `-1',
`-2', ..., `-10', `-11', and so on, to the original
file name. (See section 20.1.8 Tag Files and Split Files.)
The subfile name `texinfo.info-10', for example, is too long for
some systems; so the Info file name for this document is `texinfo'
rather than `texinfo.info'. When makeinfo is running on
operating systems such as MS-DOS which impose grave limits on file
names, it will sometimes remove some characters from the original file
name to leave enough space for the subfile suffix, thus producing files
named `texin-10', `gcc.i12', etc.
The Info formatting commands ignore everything written before the
@setfilename line, which is why the very first line of
the file (the \input line) does not show up in the output.
The @setfilename line produces no output when you typeset a
manual with TeX, but it is nevertheless essential: it opens the
index, cross-reference, and other auxiliary files used by Texinfo, and
also reads `texinfo.cnf' if that file is present on your system
(see section 19.9 Preparing for TeX).
@settitleIn order to be made into a printed manual, a Texinfo file must contain a line that looks like this:
@settitle title
Write the @settitle command at the beginning of a line and
follow it on the same line by the title. This tells TeX the title
to use in a header or footer. Do not write anything else on the line;
anything on the line after the command is considered part of the
title, including a comment.
Conventionally, when TeX formats a Texinfo file for double-sided
output, the title is printed in the left-hand (even-numbered) page
headings and the current chapter title is printed in the right-hand
(odd-numbered) page headings. (TeX learns the title of each chapter
from each @chapter command.) Page footers are not
printed.
Even if you are printing in a single-sided style, TeX looks for an
@settitle command line, in case you include the manual title
in the heading.
The @settitle command should precede everything that generates
actual output in TeX.
Although the title in the @settitle command is usually the
same as the title on the title page, it does not affect the title as
it appears on the title page. Thus, the two do not need not match
exactly; and the title in the @settitle command can be a
shortened or expanded version of the title as it appears on the title
page. (See section 3.5.1 @titlepage.)
TeX prints page headings only for that text that comes after the
@end titlepage command in the Texinfo file, or that comes
after an @headings command that turns on headings.
(See section 3.5.6 The @headings Command, for more
information.)
You may, if you wish, create your own, customized headings and footings. See section F. Page Headings, for a detailed discussion of this process.
@setchapternewpageIn an officially bound book, text is usually printed on both sides of the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the preceding chapter, after a small amount of vertical whitespace.
You can use the @setchapternewpage command with various
arguments to specify how TeX should start chapters and whether it
should format headers for printing on one or both sides of the paper
(single-sided or double-sided printing).
Write the @setchapternewpage command at the beginning of a
line followed by its argument.
For example, you would write the following to cause each chapter to start on a fresh odd-numbered page:
@setchapternewpage odd
You can specify one of three alternatives with the
@setchapternewpage command:
@setchapternewpage off
@headings double command; see
section 3.5.6 The @headings Command.)
@setchapternewpage on
@setchapternewpage odd
Texinfo does not have an @setchapternewpage even command.
You can countermand or modify the effect on headers of an
@setchapternewpage command with an @headings command.
See section 3.5.6 The @headings Command.
At the beginning of a manual or book, pages are not numbered--for example, the title and copyright pages of a book are not numbered. By convention, table of contents pages are numbered with roman numerals and not in sequence with the rest of the document.
Since an Info file does not have pages, the @setchapternewpage
command has no effect on it.
We recommend not including any @setchapternewpage command in
your manual sources at all, since the desired output is not intrinsic to
the document. Instead, if you don't want the default option (no blank
pages, same headers on all pages) use the @option{--texinfo} option to
@command{texi2dvi} to specify the output you want.
The Texinfo processors may insert whitespace at the beginning of the
first line of each paragraph, thereby indenting that paragraph. You can
use the @paragraphindent command to specify this indentation.
Write an @paragraphindent command at the beginning of a line
followed by either `asis' or a number:
@paragraphindent indent
The indentation is according to the value of indent:
asis
The default value of indent is `asis'.
@paragraphindent is ignored for HTML output.
Write the @paragraphindent command before or shortly after the
end-of-header line at the beginning of a Texinfo file. (If you write
the command between the start-of-header and end-of-header lines, the
region formatting commands indent paragraphs as specified.)
A peculiarity of the texinfo-format-buffer and
texinfo-format-region commands is that they do not indent (nor
fill) paragraphs that contain @w or @* commands.
See section H. Refilling Paragraphs, for further information.
@exampleindent: Environment Indenting
The Texinfo processors indent each line of @example and similar
environments. You can use the @exampleindent command to specify
this indentation. Write an @exampleindent command at the
beginning of a line followed by either `asis' or a number:
@exampleindent indent
The indentation is according to the value of indent:
asis
The default value of indent is 5. @exampleindent is
ignored for HTML output.
Write the @exampleindent command before or shortly after the
end-of-header line at the beginning of a Texinfo file. (If you write
the command between the start-of-header and end-of-header lines, the
region formatting commands indent examples as specified.)
Follow the header lines with an end-of-header line. An end-of-header line looks like this:
@c %**end of header
If you include the @setchapternewpage command between the
start-of-header and end-of-header lines, TeX will typeset a region as
that command specifies. Similarly, if you include an @smallbook
command between the start-of-header and end-of-header lines, TeX will
typeset a region in the "small" book format.
The reason for the odd string of characters (`%**') is so that the
texinfo-tex-region command does not accidentally find
something that it should not when it is looking for the header.
The start-of-header line and the end-of-header line are Texinfo mode variables that you can change.
The title page and the copyright page appear only in the printed copy of the manual; therefore, the same information must be inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice, and copying permissions.
The copyright notice should read:
Copyright year copyright-owner
and be put on a line by itself.
Standard text for the copyright permissions is contained in an appendix to this manual; see section 20.4 `ifinfo' Copying Permissions, for the complete text.
The permissions text appears in an Info file before the first node. This mean that a reader does not see this text when reading the file using Info, except when using the advanced Info command g *.
A manual's name and author are usually printed on a title page. Sometimes copyright information is printed on the title page as well; more often, copyright information is printed on the back of the title page.
The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use several slightly obscure TeX typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.
You may wish to include titlepage-like information for plain text
output. Simply place any such leading material between @ifinfo
and @end ifinfo; @command{makeinfo} includes this in its plain
text output. It will not show up in the Info readers.
See section 20.5 Titlepage Copying Permissions, for the standard text for the copyright permissions.
@titlefont, @center,
and @sp commands.
@title, @subtitle,
and @author commands.
@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. (See section F. Page Headings, for details about how to
generate page headings.) All the material that you want to appear on
unnumbered pages should be put between the @titlepage and
@end titlepage commands. You can force the table of contents to
appear there with the @setcontentsaftertitlepage command
(see section 4.2 Generating a Table of Contents).
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(5) 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
section 5.3 @top.)
Texinfo provides two main 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, or you may combine them; see the examples in the sections below.
For extremely simple applications, and for the bastard title page in
traditional book front matter, Texinfo also provides a command
@shorttitlepage which takes a single argument as the title. The
argument is typeset on a page by itself and followed by a blank 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. You can use @titlefont more than once if you
have an especially long title.
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. (See section 14.5 @sp n: Insert Blank Lines, 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.5 by 11 inch manual.
@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. Only a single line is
allowed; the @* command may not be used to break the title into
two lines. To handle very long titles, you may find it profitable to
use both @title and @titlefont; see the final example in
this section.
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
You may also combine the @titlefont method described in the
previous section and @title method described in this one. This
may be useful if you have a very long title. Here is a real-life example:
@titlepage
@titlefont{GNU Software}
@sp 1
@title for MS-Windows and MS-DOS
@subtitle Edition @value{edition} for Release @value{cd-edition}
@author by Daniel Hagerty, Melissa Weisshaus
@author and Eli Zaretskii
(The use of @value here is explained in section 16.4.3 @value Example.)
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.
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.
See section D. Sample Permissions, for the standard text.
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).
(See section 3.3.5 @setchapternewpage.)
You can specify these formats in different ways:
@setchapternewpage command
before the title page commands, and then have the @end
titlepage command start generating page headings in the manner desired.
(See section 3.3.5 @setchapternewpage.)
@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. See section 3.5.6 The @headings Command, for more information.)
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.
@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.
You can use @headings as follows:
@headings off
@headings single
@headings double
@headings on
@headings on and @headings double, are
synonymous.
@headings singleafter
@headings doubleafter
single or double headings, respectively, after the
current page is output.
@headings on
single if `@setchapternewpage
on', double otherwise.
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. See section F. Page Headings, for more information.
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.
See section 16. Conditionally Visible Text.)
Sometimes, you will want to place an @top sectioning command
line containing the title of the document immediately after the
@node Top line (see section 6.3.6 The @top Sectioning 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
@ifnottex
@node Top, Copying, , (dir)
@top Texinfo
Texinfo is a documentation system...
This is edition...
...
@end ifnottex
@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.
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.
@detailmenu before the
first one, and @end detailmenu after the last; otherwise,
makeinfo will get confused.
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. (See section 7.2 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.
@detailmenu
--- 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 detailmenu
@end menu
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.
(See section 5.5 @unnumbered and @appendix.)
Go to the first, previous, next, last section, table of contents.