# Beginning a Texinfo File

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:

1. The header, delimited by special comment lines, that includes the commands for naming the Texinfo file and telling TeX what definitions' file to use when processing the Texinfo file.
2. A short statement of what the file is about, with a copyright notice and copying permissions. This is enclosed in `@ifinfo` and `@end ifinfo` commands so that the formatters place it only in the Info file.
3. A title page and copyright page, with a copyright notice and copying permissions. This is enclosed between `@titlepage` and `@end titlepage` commands. The title and copyright page appear only in the printed manual.
4. The `Top' node that contains a menu for the whole Info file. The contents of this node appear only in the Info file.

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.

## Sample Texinfo File Beginning

The following sample shows what is needed.

```\input texinfo   @c -*-texinfo-*-
@setfilename name-of-info-file
@settitle name-of-manual
@setchapternewpage odd

@ifinfo
This file documents ...

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
@page
@vskip 0pt plus 1filll

Permission is granted to ...
@end titlepage

@node Top, Overview, (dir), (dir)

@ifinfo
This document describes ...

This document applies to version ...
of the program named ...
@end ifinfo

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

@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-*-
@setfilename sample.info
@settitle Sample Document
```

### 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 is usually located in the `/usr/lib/tex/macros' directory. TeX uses the backslash, `\', to mark the beginning of a command, just 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.

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 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 a comment.

The `@setfilename` line specifies the name of the Info 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 `.tex' extension from the input file name, or replace it with the `.info' 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 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'.

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 need to be commented out.

The `@setfilename` line produces no output when you typeset a printed manual, but is does an essential job: it opens the index, cross-reference, and other auxiliary files used by Texinfo.

### `@settitle`

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

### `@setchapternewpage`

In a book or a manual, 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 typeset pages 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. (You can override the headers format with the `@headings double` command; see section The `@headings` Command.)
`@setchapternewpage on`
Cause TeX to start new chapters on new pages and to typeset page headers for single-sided printing. This is the form most often used for short reports. This alternative 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.

(You can countermand or modify an `@setchapternewpage` command with an `@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 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.

Usually, you do not write an `@setchapternewpage` command for single-sided printing, but accept the default which is to typeset for single-sided printing and to start new chapters on new pages. Usually, you write an `@setchapternewpage odd` command for double-sided printing.

### Paragraph Indenting

The Info formatting commands may insert spaces at the beginning of the first line of each paragraph, thereby indenting that paragraph. You can use the `@paragraphindent` command to specify the indentation. Write an `@paragraphindent` command at the beginning of a line followed by either `asis' or a number. The template is:

```@paragraphindent indent
```

The Info formatting commands indent according to the value of indent:

• If the value of indent is `asis', the Info formatting commands do not change the existing indentation.
• If the value of indent is 0, the Info formatting commands delete existing indentation.
• If the value of indent is greater than 0, the Info formatting commands indent the paragraph by that number of spaces.

The default value of indent is `asis'.

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 Refilling Paragraphs, for a detailed description of what goes on.

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

## Summary and Copying Permissions for Info

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.

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

## The Title and Copyright Pages

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.

See section Titlepage Copying Permissions, for the standard text for the copyright permissions.

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

For extremely simple applications, 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.

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` 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 1/2 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.

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

By international treaty, the copyright notice for a book should be either on the title page or on the back of the title page. The copyright notice should include the year followed by the name of the organization or person who owns the copyright.

When the copyright notice is on the back of the title page, that page is customarily not numbered. Therefore, in Texinfo, the information on the copyright page should be within `@titlepage` and `@end titlepage` commands.

Use the `@page` command to cause a page break. To push the copyright notice and the other text on the copyright page towards the bottom of the page, you can write a somewhat mysterious line after the `@page` command that reads like this:

```@vskip 0pt plus 1filll
```

This is a TeX command that is not supported by the Info formatting commands. The `@vskip` command inserts whitespace. The `0pt plus 1filll' means to put in zero points of mandatory whitespace, and as much optional whitespace as needed to push the following text to the bottom of the page. Note the use of three `l's in the word `filll'; this is the correct usage in TeX.

In a printed manual, the `@copyright{}` command generates a `c' inside a circle. (In Info, it generates `(C)'.) The copyright notice itself has the following legally defined sequence:

```Copyright (C) year copyright-owner
```

It is customary to put information on how to get a manual after the copyright notice, followed by the copying permissions for the manual.

Note that permissions must be given here as well as in the summary segment within `@ifinfo` and `@end ifinfo` that immediately follows the header since this text appears only in the printed manual and the `ifinfo' text appears only in the Info file.

See section 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 `@setchapternewpage`.) You can specify these formats in different ways:

• The conventional way is to write an `@setchapternewpage` command before the title page commands, and then have the ```@end titlepage``` command start generating page headings in the manner desired. (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.

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

The `@headings off` command overrides the `@end titlepage` command, which would otherwise cause TeX to print page headings.

## The `Top' Node and Master Menu

The `Top' node is the node from which you enter an Info file.

A `Top' node should contain a brief description of the Info file and an extensive, master menu for the whole Info file. This helps the reader understand what the Info file is about. Also, you should write the version number of the program to which the Info file applies; or, at least, the edition number.

The contents of the `Top' node should appear only in the Info file; none of it should appear in printed output, so enclose it between `@ifinfo` and `@end ifinfo` commands. (TeX does not print either an `@node` line or a menu; they appear only in Info; strictly speaking, you are not required to enclose these parts between `@ifinfo` and `@end ifinfo`, but it is simplest to do so. See section 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 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

@ifinfo
@node Top, Copying, (dir), (dir)
@top Texinfo

Texinfo is a documentation system...

This is edition...
...
@end ifinfo

* Copying::                 Texinfo is freely
redistributable.
* Overview::                What is Texinfo?
...
```

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.

### 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::             Texinfo is freely
redistributable.
* Overview::            What is Texinfo?
* Texinfo Mode::        Special features in GNU Emacs.
...
...
* Command and Variable Index::
An entry for each @-command.
* Concept Index::       An entry for each concept.

--- The Detailed Node Listing ---

Overview of Texinfo

* Info Files::          What is an Info file?
* Printed Manuals::     Characteristics of
a printed manual.
...
...

Using Texinfo Mode

* Info on a Region::    Formatting part of a file
for Info.
...
...
```

## Software Copying Permissions

If the Texinfo file has a section containing the "General Public License" and the distribution information and a warranty disclaimer for the software that is documented, this section usually follows the `Top' node. The General Public License is very important to Project GNU software. It ensures that you and others will continue to have a right to use and share the software.

The copying and distribution information and the disclaimer are followed by an introduction or else by the first chapter of the manual.

Although an introduction is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, an introduction would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, an introduction is put in an `@unnumbered` section. (See section `@unnumbered`, `@appendix`.)