3 Beginning a Texinfo File
**************************

Certain pieces of information must be provided at the beginning of a
Texinfo file, such as the name for the output file(s), the title of the
document, and the Top node.

This chapter expands on the minimal complete Texinfo source file
previously given (see Six Parts).

* Sample Beginning::            A sample beginning for a Texinfo file.
* Texinfo File Header::         The first lines.
* Document Permissions::        Ensuring your manual is free.
* Titlepage & Copyright Page::  Creating the title and copyright pages.
* The Top Node::                Creating the `Top' node and master menu.
* Global Document Commands::    Affecting formatting throughout.
* Software Copying Permissions::  Ensure that you and others continue to
                                    have the right to use and share software.


3.1 Sample Texinfo File Beginning
=================================


The following sample shows what is needed.  The elements given here are
explained in more detail in the following sections.  Other commands are
often included at the beginning of Texinfo files, but the ones here are
the most critical.

See GNU Sample Texts, for the full texts to be used in GNU manuals.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename infoname.info
@settitle name-of-manual version
@c %**end of header

@copying
This manual is for program, version version.

Copyright @copyright{} years copyright-owner.

@quotation
Permission is granted to ...
@end quotation
@end copying

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

Published by ...
@end titlepage

@c So the toc is printed in the right place.
@contents

@ifnottex
@node Top
@top title

@insertcopying
@end ifnottex

@menu
* First Chapter::    Getting started ...
* Second Chapter::          ...
  ...
* Copying::          Your rights and freedoms.
@end menu

@node First Chapter
@chapter First Chapter

@cindex first chapter
@cindex chapter, first
...


3.2 Texinfo File Header
=======================

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.

Also, if you want to format just part of the Texinfo file, you must
write the @settitle and @setfilename lines between
start-of-header and end-of-header lines.  The start- and end-of-header
lines are optional, but they do no harm, so you might as well always
include them.

Any command that affects document formatting as a whole makes sense to
include in the header.  @synindex (see synindex), for
instance, is another command often included in the header.  See GNU Sample Texts, for complete sample texts.

Thus, the beginning of a Texinfo file generally looks like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Manual 1.0
@c %**end of header

* First Line::                  The first line of a Texinfo file.
* Start of Header::             Formatting a region requires this.
* setfilename::                 Tell Info the name of the Info file.
* settitle::                    Create a title for the printed work.
* End of Header::               Formatting a region requires this.


3.2.1 The First Line of a Texinfo File
--------------------------------------

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:

1. When the file is processed by TeX, the `\input texinfo' command
tells TeX to load the macros needed for processing a Texinfo file.
These are in a file called `texinfo.tex', which should have been
installed on your system along with either the TeX or Texinfo
software.  TeX uses the backslash, `\', to mark the beginning of
a command, exactly as Texinfo uses `@'.  The `texinfo.tex'
file causes the switch from `\' to `@'; before the switch
occurs, TeX requires `\', which is why it appears at the
beginning of the file.

2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
specification tells Emacs to use Texinfo mode.


3.2.2 Start of Header
---------------------

A start-of-header line is a Texinfo comment that looks like this:

@c %**start of header

Write the 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 commands that
globally affect the document formatting, such as @synindex or
@footnotestyle; and then by an end-of-header line (see End of Header).

The start- and end-of-header lines allow you to format only part of a
Texinfo file for Info or printing.  See texinfo-format commands.

The odd string of characters, `%**', is to ensure that no other
comment is accidentally taken for a start-of-header line.  You can
change it if you wish by setting the tex-start-of-header and/or
tex-end-of-header Emacs variables.  See Texinfo Mode Printing.


3.2.3 @setfilename: Set the output file name
--------------------------------------------

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 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 specifies the name of the output file to
be generated.  This name must 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') entirely from the input file
name, or, preferably, replace it with the `.info' extension.

Although an explicit `.info' extension is preferable, 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 Tag and Split Files.)  The subfile name
`texinfo.info-10', for example, is too long for old systems with a
14-character limit on filenames; 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 severe
limits on file names, it may 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.

When producing HTML output, makeinfo will replace any extension
with `html', or add `.html' if the given name has no
extension.

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 Preparing for TeX).


3.2.4 @settitle: Set the document title
---------------------------------------

In 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 what would otherwise be a comment.

The @settitle command should precede everything that generates
actual output in TeX.

In the HTML file produced by makeinfo, title also serves
as the document `<title>' and the default document description in
the `<head>' part; see documentdescription, for how to change
that.

The title in the @settitle command does not affect the title as
it appears on the title page.  Thus, the two do not need not match
exactly.  A practice we recommend is to include the version or edition
number of the manual in the @settitle title; on the title page,
the version number generally appears as a @subtitle so it would
be omitted from the @title.  (See titlepage.)

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.)  By default, no page footer is
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.

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 The @headings Command, for more
information.)

You may, if you wish, create your own, customized headings and footings.
See Headings, for a detailed discussion of this.


3.2.5 End of Header
-------------------

Follow the header lines with an end-of-header line, which is a
Texinfo comment that looks like this:

@c %**end of header

See Start of Header.


3.3 Document Permissions
========================

The copyright notice and copying permissions for a document need to
appear in several places in the various Texinfo output formats.
Therefore, Texinfo provides a command (@copying) to declare
this text once, and another command (@insertcopying) to
insert the text at appropriate points.

* copying::                 Declare the document's copying permissions.
* insertcopying::           Where to insert the permissions.


3.3.1 @copying: Declare copying permissions
-------------------------------------------

The @copying command should be given very early in the document;
right after the header material (see Texinfo File Header) is the
recommended location.  It conventionally consists of a sentence or two
about what the program is, the legal copyright line, and the copying
permissions.  Here is a skeletal example:

@copying
This manual is for program (version version),
which ...

Copyright @copyright{} years copyright-owner.

@quotation
Permission is granted to ...
@end quotation
@end copying

The @quotation has no legal significance; it's there to improve
readability in some contexts.

See GNU Sample Texts, for the full text to be used in GNU manuals.
See GNU Free Documentation License, for the license itself under
which GNU and other free manuals are distributed.

The text of @copying is output as a comment at the beginning of
Info, HTML, and XML output files.  It is not output implicitly in
plain text or TeX; it's up to you to use @insertcopying to
emit the copying information.  See the next section for details.

In output formats that support it (print and HTML), the
@copyright{} command generates a `c' inside a circle.  In
Info and plain text, it generates `(C)'.  The copyright notice
itself has the following legally defined sequence:

Copyright (C) years copyright-owner.

The word `Copyright' must always be written in English, even if the
manual is otherwise in another language.  This is due to international
law.

The list of years should include all years in which a version was
completed (even if it was released in a subsequent year).  Ranges are
not allowed, each year must be written out individually, separated by
commas.

The copyright owner (or owners) is whoever holds legal copyright on the
work.  In the case of works assigned to the FSF, the owner is `Free
Software Foundation, Inc.'.

See Copyright Notices in GNU Maintenance Instructions, for
additional information.


3.3.2 @insertcopying: Include permissions text
----------------------------------------------

The @insertcopying command is simply written on a line by
itself, like this:

@insertcopying

It inserts the text previously defined by @copying.  Legally, it
must be used on the copyright page in the printed manual
(see Copyright).

Although it's not a legal requirement, we also strongly recommend using
@insertcopying in the Top node of your manual (see The Top Node).  Here's why:

The @copying command itself causes the permissions text to
appear in an Info file before the first node.  The text is also
copied into the beginning of each split Info output file, as is legally
necessary.  This location implies a human reading the manual using Info
does not see this text (except when using the advanced Info
command g *).  Therefore, an explicit @insertcopying
in the Top node makes it apparent to readers that the manual is free.

Similarly, the @copying text is automatically included at the
beginning of each HTML output file, as an HTML comment.  Again, this
text is not visible (unless the reader views the HTML source).  And
therefore again, the @insertcopying in the Top node is valuable
because it makes the copying permissions visible and thus promotes
freedom.

The permissions text defined by @copying also appears
automatically at the beginning of the XML output file.


3.4 Title and Copyright Pages
=============================

In hard copy output, the manual's name and author are usually printed on
a title page.  Copyright information is usually 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 appears in the printed manual.

You may wish to include titlepage-like information for plain text
output.  Simply place any such leading material between
@ifplaintext and @end ifplaintext; makeinfo
includes this when writing plain text (`--no-headers'), along with
an @insertcopying.

* titlepage::                   Create a title for the printed document.
* titlefont center sp::         The @titlefont, @center,
                                  and @sp commands.
* title subtitle author::       The @title, @subtitle,
                                  and @author commands.
* Copyright::                   How to write the copyright notice and
                                  include copying permissions.
* end titlepage::               Turn on page headings after the title and
                                  copyright pages.
* headings on off::             An option for turning headings on and off
                                  and double or single sided printing.


3.4.1 @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 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 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
The Top Node.)

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 the rest of the line as the title.
The argument is typeset on a page by itself and followed by a blank
page.


3.4.2 @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 @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.5 by 11 inch manual.


3.4.3 @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{e} for Release @value{cde}
@author by Daniel Hagerty, Melissa Weisshaus
@author and Eli Zaretskii

(The use of @value here is explained in value Example.


3.4.4 Copyright Page
--------------------

By international treaty, the copyright notice for a book must be either
on the title page or on the back of the title page.  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, use the following incantantion after @page:

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

To insert the copyright text itself, write @insertcopying
next (see Document Permissions):

@insertcopying

Follow the copying text by the publisher, ISBN numbers, cover art
credits, and other such information.

Here is an example putting all this together:

@titlepage
...
@page
@vskip 0pt plus 1filll
@insertcopying

Published by ...

Cover art by ...
@end titlepage


3.4.5 Heading Generation
------------------------

The @end titlepage command must be written on a line by itself.
It 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).
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.
(See 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.  See The @headings Command, for more information.)

* Or, you may specify your own page heading and footing format.
See Page 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.


3.4.6 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.

You can use @headings as follows:

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

@headings singleafter
@headings doubleafter
Turn on single or double headings, respectively, after the
current page is output.

@headings on
Turn on page headings: 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 Page Headings, for more information.


3.5 The `Top' Node and Master Menu
==================================

The `Top' node is the node in which a reader enters an Info manual.  As
such, it should begin with the @insertcopying command
(see Document Permissions) to provide a brief description of the
manual (including the version number) and copying permissions, and end
with a master menu for the whole manual.  Of course you should include
any other general information you feel a reader would find helpful.

It is also conventional to write an @top sectioning command line
containing the title of the document immediately after the @node
Top line (see The @top Sectioning Command).

The contents of the `Top' node should appear only in the online output;
none of it should appear in printed output, so enclose it between
@ifnottex and @end ifnottex 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
@ifnottex and @end ifnottext, but it is simplest to do
so.  See Conditionally Visible Text.)

* Top Node Example::            
* Master Menu Parts::           


3.5.1 Top Node Example
----------------------


Here is an example of a Top node.

@ifnottex
@node Top
@top Sample Title

@insertcopying

Additional general information.

@menu
* First Chapter::
* Second Chapter::
...
* Index::
@end menu


3.5.2 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.  If you do use them, put @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 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 Conditions::  Your rights.
* Overview::            Texinfo in brief.
...
* Command and Variable Index::
* Concept Index::       

@detailmenu
 --- The Detailed Node Listing ---

Overview of Texinfo

* Reporting Bugs:: ...
...

Beginning a Texinfo File

* Sample Beginning:: ...
...
@end detailmenu
@end menu


3.6 Global Document Commands
============================

Besides the basic commands mentioned in the previous sections, here are
additional commands which affect the document as a whole.  They are
generally all given before the Top node, if they are given at all.

* documentdescription::         Document summary for the HTML output.
* setchapternewpage::           Start chapters on right-hand pages.
* paragraphindent::             Specify paragraph indentation.
* exampleindent::               Specify environment indentation.


3.6.1 @documentdescription: Summary text
----------------------------------------

When producing HTML output for a document, makeinfo writes a
`<meta>' element in the `<head>' to give some idea of the
content of the document.  By default, this description is the title
of the document, taken from the @settitle command
(see settitle).  To change this, use the @documentdescription
environment, as in:

@documentdescription
descriptive text.
@end documentdescription

This will produce the following output in the `<head>' of the HTML:

<meta name=description content="descriptive text.">

@documentdescription must be specified before the first node of
the document.


3.6.2 @setchapternewpage:
-------------------------

In 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
Cause TeX to typeset a new chapter on the same page as the last
chapter, after skipping some vertical whitespace.  Also, cause TeX to
format page headers for single-sided printing.

@setchapternewpage on
Cause TeX to start new chapters on new pages and to format page
headers for single-sided printing.  This is the form most often used for
short reports or personal printing. This is the default.

@setchapternewpage odd
Cause TeX to start new chapters on new, odd-numbered pages
(right-handed pages) and to typeset for double-sided printing.  This is
the form most often used for books and manuals.

Texinfo does not have an @setchapternewpage even command,
because there is no printing tradition of starting chapters or books on
an even-numbered page.

If you don't like the default headers that @setchapternewpage
sets, you can explicit control them with the @headings command.
See 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 and frontmatter 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.  For a particular hard copy run, if you don't want the
default option (no blank pages, same headers on all pages) use the
`--texinfo' option to texi2dvi to specify the output
you want.


3.6.3 Paragraph Indenting
-------------------------

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
Do not change the existing indentation (not implemented in TeX).

none
0
Omit all indentation.

n
Indent by n space characters in Info output, by n ems in
TeX.


The default value of indent is 3.  @paragraphindent is
ignored for HTML output.

It is best to write the @paragraphindent command before the
end-of-header line at the beginning of a Texinfo file, so the region
formatting commands indent paragraphs as specified.  See Start of Header.

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 Refilling Paragraphs, for further information.


3.6.4 @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
Do not change the existing indentation (not implemented in TeX).

0
Omit all indentation.

n
Indent environments by n space characters in Info output, by
n ems in TeX.


The default value of indent is 5.  @exampleindent is
ignored for HTML output.

It is best to write the @exampleindent command before the
end-of-header line at the beginning of a Texinfo file, so the region
formatting commands indent paragraphs as specified.  See Start of Header.


3.7 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, we recommend placing this right after
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.


