[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

# 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. A table of contents is also generally produced here.

This chapter expands on the minimal complete Texinfo source file previously given (see section Six Parts of a Texinfo File). It describes the numerous commands for handling the traditional frontmatter items in Texinfo.

Straight text outside of any command before the Top node should be avoided. Such text is treated differently in the different output formats: visible in TeX and HTML, by default not shown in Info readers, and so on.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

## 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 section 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 at the start. @contents @ifnottex @node Top @top title This manual is for program, version version. @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 … ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

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 section `@synindex`), for instance, is another command often included in the header. See section 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 ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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 XEmacs, the ‘-*-texinfo-*-’ mode specification tells XEmacs to use Texinfo mode.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

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 section 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 section The `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` XEmacs variables. See section Formatting and Printing in Texinfo Mode.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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 section Tag Files 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 section Preparing for TeX).

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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. The best place for it is right after the `@setfilename` command (see the previous section).

In the HTML file produced by `makeinfo`, title serves as the document ‘<title>’. It also becomes the default document description in the ‘<head>’ part (see section `@documentdescription`: Summary Text).

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

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

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

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

 ```@c %**end of header ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

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

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.3.1 `@copying`: Declare Copying Permissions

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

 ```@copying This manual is for program (version version, updated date), 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 section GNU Sample Texts, for the full text to be used in GNU manuals. See section GNU Free Documentation License, for the license itself under which GNU and other free manuals are distributed. You need to include the license as an appendix to your document.

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.

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

 ```Copyright © years copyright-owner. ```

The word ‘Copyright’ must always be written in English, even if the document is otherwise written 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 and in full, 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.’.

The copyright ‘line’ may actually be split across multiple lines, both in the source document and in the output. This often happens for documents with a long history, having many different years of publication. If you do use several lines, do not indent any of them (or anything else in the `@copying` block) in the source file.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.3.2 `@insertcopying`: Include Permissions Text

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

 ```@insertcopying ```

This inserts the text previously defined by `@copying`. To meet legal requirements, it must be used on the copyright page in the printed manual (see section Copyright Page).

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 *), but this does not matter for legal purposes, because the text is present.

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

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

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

## 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`.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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 section 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 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 The ‘Top’ Node and Master Menu.)

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 documents, and for the bastard title page in traditional book frontmatter, 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.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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 HTML output, each `@titlefont` command produces an `<h1>` heading, but the HTML document `<title>` is not affected. For that, you must put an `@settitle` command before the `@titlefont` command (see section `@settitle`: Set the document 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 `@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.

You can in fact use these commands anywhere, not just on a title page, but since they are not logical markup commands, we don’t recommend them.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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. These commands are only effective in TeX output; it’s an error to use them anywhere except within `@titlepage`.

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.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

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 incantation 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 section 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 ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Like all `@end` commands (see section Quotations and Examples), the `@end titlepage` command must be written at the beginning of a line by itself, with only one space between the `@end` and the `titlepage`. 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 section `@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 section 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.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 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 predefined 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`

Turn on page headings appropriate for double-sided printing.

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

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

The `@chapter`, `@section`, and other structuring commands (see section Chapter Structuring) 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/or `@summarycontents` command(s).

`@contents`

Generates a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. Headings generated by `@majorheading`, `@chapheading`, and the other `@…heading` commands do not appear in the table of contents (see section Structuring Command Types).

`@shortcontents`
`@summarycontents`

(`@summarycontents` is a synonym for `@shortcontents`.)

Both contents commands should be written on a line by themselves, and are best placed near the beginning of the file, after the ```@end titlepage``` (see section `@titlepage`). The contents commands automatically generate a chapter-like heading at the top of the first table of contents page, so don’t include any sectioning command such as `@unnumbered` before them.

Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are included in plain text output (generated by ```makeinfo --no-headers```), unless `makeinfo` is writing its output to standard output.

When `makeinfo` writes a short table of contents while producing HTML output, the links in the short table of contents point to corresponding entries in the full table of contents rather than the text of the document. The links in the full table of contents point to the main text of the document.

In the past, the contents commands were sometimes placed at the end of the file, after any indices and just before the `@bye`, but we no longer recommend this.

However, since many existing Texinfo documents still do have the `@contents` at the end of the manual, if you are a user printing a manual, you may wish to force the contents to be printed after the title page. You can do this by specifying `@setcontentsaftertitlepage` and/or `@setshortcontentsaftertitlepage`. The first prints only the main contents after the `@end titlepage`; the second prints both the short contents and the main contents. In either case, any subsequent `@contents` or `@shortcontents` is ignored (unless, erroneously, no `@end titlepage` is ever encountered).

You need to include the `@set…contentsaftertitlepage` commands early in the document (just after `@setfilename`, for example). We recommend using `texi2dvi` (see section Format with `texi2dvi`) to specify this without altering the source file at all. For example:

 ```texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

## 3.6 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 a brief description of the manual (including the version number), 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 conventional and desirable to write an `@top` sectioning command line containing the title of the document immediately after the `@node Top` line (see section 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 ifnottex`, but it is simplest to do so. See section Conditionally Visible Text.)

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.6.1 Top Node Example

Here is an example of a Top node.

 ```@ifnottex @node Top @top Sample Title @insertcopying @end ifnottex ``````Additional general information. ``````@menu * First Chapter:: * Second Chapter:: … * Index:: ``````@end menu ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.6.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 section 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:: * General Index:: ``````@detailmenu --- The Detailed Node Listing --- Overview of Texinfo * Reporting Bugs:: … … ``````Beginning a Texinfo File * Sample Beginning:: … … @end detailmenu @end menu ```

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

## 3.7 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.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.7.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 section `@settitle`: Set the document title). 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:

 ``` ```

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

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.7.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 section 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.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.7.3 `@paragraphindent`: 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 section 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.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.7.4 `@firstparagraphindent`: Indenting After Headings

As you can see in the present manual, the first paragraph in any section is not indented by default. Typographically, indentation is a paragraph separator, which means that it is unnecessary when a new section begins. This indentation is controlled with the `@firstparagraphindent` command:

 ```@firstparagraphindent word ```

The first paragraph after a heading is indented according to the value of word:

`none`

Prevents the first paragraph from being indented (default). This option is ignored by `makeinfo` if `@paragraphindent asis` is in effect.

`insert`

Include normal paragraph indentation. This respects the paragraph indentation set by a `@paragraphindent` command (see section `@paragraphindent`: Paragraph Indenting).

For HTML and XML output, the `@firstparagraphindent` setting is ignored.

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 section Start of Header.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

### 3.7.5 `@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 ```

`@exampleindent` is ignored for HTML output. Otherwise, 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 spaces in Info, and 0.4in in TeX, which is somewhat less. (The reduction is to help TeX fit more characters onto physical lines.)

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 section Start of Header.

 [ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

## 3.8 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.

 [ << ] [ >> ] [Top] [Contents] [Index] [ ? ]

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.