4.4BSD/usr/src/contrib/emacs-18.57/info/texinfo-1

Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
input file texinfo.texinfo.

This file documents Texinfo, a documentation system that uses a
single source file to produce both on-line help and a printed manual.

This is edition 1.1 of the Texinfo documentation, and is for the
Texinfo that is distributed as part of Version 18 of GNU Emacs.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

File: texinfo, Node: Top, Next: License, Prev: (dir), Up: (dir)

* Menu:

* License:: Licensing information.
* Overview:: What is Texinfo?
* Texinfo Mode:: Special features in GNU Emacs.
* Beginning a File:: What to put at the beginning of a Texinfo file.
* Ending a File:: What to put at the end of a Texinfo file.
* Structuring:: How to make nodes and chapters.
* Quotations and Examples:: How to insert quotations and examples.
* Lists and Tables:: How to make lists and tables.
* Cross References:: How to make cross references.
* Formatting Paragraphs:: How to format paragraphs.
* Marking Text:: How to mark code, definitions, variables etc.
* Conditionals:: Putting text in only Info or the printed work.
* Printing Hardcopy:: How to print a hardcopy of the manual.
* Creating an Info File:: How to create an on-line Info file.
* Catching Mistakes:: How to find problems.

Indices, nodes containing large menus

* Command Index:: An item for each @-command.
* Concept Index:: An item for each concept.

A detailed node listing

Overview
* Info File:: Characteristics of the Info file.
* Printed Manual:: Characteristics of the printed manual.
* Conventions:: General syntactic conventions.
* Short Sample:: A short sample Texinfo file.

Using Texinfo Mode
* Info on a Region:: Formatting a region for Info.
* Showing the Structure:: Showing the structure of a file.
* Inserting:: Inserting frequently used commands.

Beginning a Texinfo File.
* First Line:: The first line of a Texinfo file.
* Start-of-Header:: Identifying the start of the header.
* Setfilename:: Specifying the name of the Info file.
* Settitle:: Specifying the title used by the headings.
* Setchapternewpage:: Starting chapters on odd numbered pages.
* Titlepage:: The title and copyright page.
* Center:: Centering a line.
* Copyright & Printed Permissions:: Ensuring free distributability.
* Top Node:: The master menu.
* License and Distribution:: Your are free to copy and distribute this.

Ending a Texinfo File
* Contents:: Generating tables of contents.
* Indices:: Generating indices.
* Index Entries:: Defining the entries of an index.
* Combining Indices:: Putting two or more indices together.
* Printing Indices & Menus:: Printing an index and generating menus.

Node and Chapter Structuring
* Chapter:: Creating a chapter.
* Unnumbered and Appendix:: Chapter-like parts.
* Section:: Creating sections
* Subsection:: Creating subsections.
* Subsubsection:: Creating subsubsections.

* Node:: Creating nodes.
* Menu:: Creating menus.

Making quotations and examples
* Quotation:: Inserting long quotations.
* Example:: Inserting examples of code and the like.
* Display:: Inserting displayed text.

Making lists and two column tables
* Itemize:: Creating itemized lists.
* Enumerate:: Creating enumerated lists.
* Table:: Creating two column tables.
* Itemx:: Putting an extra item in the
first column of a table.

Making Cross References
* Xref:: Making a regular cross reference.
* Pxref:: Making a parenthetical cross reference.
* Inforef:: Making a cross reference to an Info file.

Formatting Paragraphs
* Refilling & Noindent:: Refilling paragraphs
and preventing indentation
* Refill:: Using the `@refill' command.
* Noindent:: Using the `@noindent' command.

Breaks, Blank Lines and Groups
* Line Breaks:: Inserting line breaks in TeX.
* Sp:: Inserting blank lines.
* Br:: Inserting paragraph breaks.
* W:: Preventing line breaks.
* Page:: Starting new pages.
* Group:: Holding text together on one page.
* Need:: Keeping text together.

Marking Text Within a Paragraph
* Code:: A literal example of a piece of a program.
* Samp:: A literal example of a sequence of characters.
* File:: The name of a file.
* Kbd:: The names of keys or else characters you type.
* Key:: The conventional name for a key on a keyboard.
* Ctrl:: Indicates the ASCII control character.
* Var:: A variable.
* Dfn:: The introductory or defining use of a term.
* Cite:: The name of a book.

Inserting Braces, `@' and Periods
* Braces Atsigns Periods:: Inserting braces, `@' and periods.
* Dots Bullets Tex:: Inserting dots, bullets and the TeX logo
* Emphasis:: Emphasizing text.

Emphasizing Text
* Emph and Strong:: Emphasizing text.
* Fonts:: Selecting italic, bold or typewriter fonts.

Creating an Info File
* Installing an Info File:: Putting the Info file in the
`info' directory.

Catching Mistakes
* Debugging with Info:: Catching errors with info formatting.
* Using the Emacs Lisp Debugger:: Using the Emacs Lisp Debugger
* Debugging with Tex:: Catching errors with TeX formatting.
* Using texinfo-show-structure:: Using `texinfo-show-structure'
to catch mistakes.
* Using Occur:: Using `occur' to catch mistakes.
* Running Info-Validate:: Checking for unreferenced nodes.

Finding badly referenced nodes
* Info-Validating a Large File:: Running `Info-validate'
on a large file.
* Splitting:: Splitting a file manually.

Appendices
* Command Syntax:: Details about the syntax.
* Include Files:: Making one printed file out of
several Info files.
* TeX Input:: Where TeX finds its `\input' file.
* Sample Permissions:: You may copy GNU Software.
* Ifinfo Permissions:: What to put in the `ifinfo' section.
* Titlepage Permissions:: What to put in the `@titlepage' section.

File: texinfo, Node: License, Next: Overview, Prev: Top, Up: Top

Licensing Information
*********************

The programs currently being distributed that relate to Texinfo
include two portions of GNU Emacs, plus two other separate programs
(`texindex' and `texinfo.tex'). These programs are "free"; this
means that everyone is free to use them and free to redistribute them
on a free basis. The Texinfo related programs are not in the public
domain; they are copyrighted and there are restrictions on their
distribution, but these restrictions are designed to permit
everything that a good cooperating citizen would want to do. What is
not allowed is to try to prevent others from further sharing any
version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to Texinfo, that you receive
source code or else can get it if you want it, that you can change
these programs or use pieces of them in new free programs, and that
you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights. For example, if you distribute
copies of the Texinfo related programs, you must give the recipients
all the rights that you have. You must make sure that they, too,
receive or can get the source code. And you must tell them their
rights.

Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for the programs that relate to
Texinfo. If these programs are modified by someone else and passed
on, we want their recipients to know that what they have is not what
we distributed, so that any problems introduced by others will not
reflect on our reputation.

The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General
Public Licenses that accompany them. The programs that are part of
GNU Emacs are covered by the GNU Emacs copying terms (*note :
(emacs)License.), and other programs are covered by licenses that are
contained in their source files.

File: texinfo, Node: Overview, Next: Texinfo Mode, Prev: License, Up: Top

Overview of Texinfo
*******************

Texinfo is a documentation system that uses a single source file for
both on-line help and a printed manual. This means that instead of
writing two different documents, one for the on-line help and the
other for the printed manual, only one document needs to be written.
When the system is revised, only one file has to be revised.

Using Texinfo, you can create a document with the normal features of
a book such as chapters, sections, cross references and indices. The
chapters and sections of the printed manual can be made to correspond
to the nodes of the on-line help. The cross references and indices
can be used in both the on-line help and in the printed document.
Indices are generated semi-automatically. The ``GNU Emacs Manual''
is a good example of a Texinfo file.

To make the printed manual, the Texinfo source file is processed by
the TeX typesetting program; the resulting DVI file can be typeset
and printed as a book. To make the on-line help, the Texinfo source
file is by processed the `M-x texinfo-format-buffer' command; the
resulting Info file is installed in the `info' directory.

Since the Texinfo source file is used for a dual task--to create both
the on-line help and the printed manual--it must be written in a
special format that uses @-commands (words preceded by an `@') to
indicate chapters, sections, nodes, examples, index entries and the
like.

Before writing a Texinfo source file, you should be familiar with the
on-line Info documentation reading program. (*note info: (info)Info,
for more information.) If you are writing a document that will be
both on-line and printed, you will need both Info and TeX.

To make an Info file, you use the `M-x texinfo-format-buffer' command
in GNU Emacs.

To make a printed manual, you need to use TeX, a powerful,
sophisticated typesetting program written by Donald Knuth. TeX is
freely distributable. It is written in a dialect of Pascal called WEB
and can be compiled either in Pascal or (by using a conversion
program that comes with the TeX distribution) in C. (For information
about getting TeX, *note : (emacs)TeX Mode.)

When TeX processes a Texinfo source file, TeX makes use of a macro
definitions file called `texinfo.tex' that comes with the GNU Emacs
distribution in the `emacs/man' sources directory. (The first line
of every Texinfo file has a command that says `\input texinfo'; this
tells TeX to use the `texinfo.tex' file.)

If the `texinfo.tex' file has not already been copied to the
directory which contains the other TeX macro definition files when
Emacs was installed, you will probably want to copy it to that
directory. Usually, this is the `/usr/lib/tex/macros' directory.
For more information, *note @TeX{} Input Initialization: TeX Input.

Documentation for GNU utilities and libraries should be written in
Texinfo format.

* Menu:

* Info File:: Characteristics of the Info file.
* Printed Manual:: Characteristics of the Printed Manual.
* Conventions:: General Syntactic Conventions.
* Short Sample:: A short sample Texinfo file.

File: texinfo, Node: Info File, Next: Printed Manual, Up: Overview

Characteristics of the Info file
================================

A Texinfo file can be transformed into a printed manual and an
on-line Info file.

An on-line Info file is a file formatted so that the Info
documentation reading program can operate on it. Info files are
divided into pieces called "nodes", each of which contains the
discussion of one topic. Each node has a name, and contains both
text for the user to read and pointers to other nodes, which are
identified by their names. The Info program displays one node at a
time, and provides commands with which the user can move to the other
nodes to which the current node points.

*note info: (info)Info, for more information about using Info.

Normally, most of the nodes are arranged in a tree which branches down.
Each node may have any number of child nodes that describe subtopics
of the node's topic. The names of these child nodes, if any, are
listed in a "menu" within the parent node; this allows certain Info
commands to be used to move to one of the child nodes. Each child
node records the parent node name, as its `Up' pointer. Thus, if a
node were at the logical level of a `chapter', its child nodes would
be `sections'; likewise, the child nodes of a section would be
subsections.

The root of the tree is the top node of the file, through which users
enter the file from the Info directory. By convention, this node is
always called `Top'. This node normally contains just a brief
summary of the file's purpose, and a large menu through which the
rest of the file is reached.

Generally you enter the Info file from the top; then you can either
traverse the file systematically by going from node to node or you
can search large menus that correspond to indices and go directly to
the node that has the information you want.

If you want to read through an Info file in sequence, as if it were a
printed manual, you can get the whole file with the advanced Info
command `g *'. (*note info: (info)Expert.)

All the children of any one parent are linked together in a
bidirectional chain of `Next' and `Previous' pointers. This means
that all the nodes that are logically parallel to sections within a
chapter are all linked together. Normally the order in this chain is
the same as the order of the children in the parent's menu. The last
child has no `Next' pointer, and the first child normally has the
parent as its `Previous' pointer (as well as its `Up' pointer, of
course).

Structuring the nodes in a tree is a matter of convention, not a
requirement. In fact, the `Up', `Previous' and `Next' pointers of a
node can point to any other nodes, and the menu can contain any other
nodes. The structure of nodes can be any directed graph. But it is
usually more comprehensible to make it a tree. Info provides another
kind of pointer between nodes, called a reference, that can be
sprinkled through the text of a node. This is usually the best way
to represent links that do not fit the tree structure.

Most often the nodes fall into a strict tree structure that
corresponds to the structure of chapters and sections in the printed
manual. But there are times when this is not right for the material
being discussed. Therefore, Texinfo uses separate commands to
specify the node structure of the Info file and the section structure
of the printed manual. Also, Texinfo requires that you specify menus
explicitly, rather than generate them automatically based on an
assumed tree structure.

File: texinfo, Node: Printed Manual, Next: Conventions, Prev: Info File, Up: Top

Characteristics of the Printed Manual
=====================================

A Texinfo file can be formatted and typeset as a printed manual. The
printed manual will be the same as any other book; it will have a
title page, copyright page, table of contents, and preface as you
would expect, as well as chapters, numbered or unnumbered sections
and subsections, not to mention page headers, cross references and
indices.

Texinfo can be used for writing a book without ever having the
intention of converting it into on-line help. Texinfo can be used
for writing a novel; and it can even be used to write a memo,
although this application is not recommended since electronic mail is
so much easier.

Texinfo uses the formatting language called TeX for typesetting. A
file called `texinfo.tex' contains information (definitions or
"macros") that TeX uses when it typesets a Texinfo file. (The macros
tell TeX how to convert the Texinfo @-commands to TeX commands which
TeX can then process to create the typeset document.) `texinfo.tex'
contains the specifications for printing a document, either with 7
inch by 9.25 inch pages or with 8.5 inch by 11 inch pages. (This is
178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
parameters in `texinfo.tex' you can easily change the size of the
printed document. In addition, you can readily change the style in
which the printed document is formatted; for example, you can change
the sizes and fonts used, the amount of indentation for each
paragraph, the degree to which words are hyphenated, and the like.
By changing the specifications, you can make a book look dignified,
old and serious, or light-hearted, young and cheery.

TeX is very powerful and has a great many features. Because a
Texinfo file must be able to present information both on a
character-only terminal in Info form and in a typeset book, the
commands that Texinfo supports are necessarily limited.

File: texinfo, Node: Conventions, Next: Short Sample, Prev: Printed Manual, Up: Overview

General Syntactic Conventions
=============================

Texinfo files contain a strictly limited set of constructs. The
strict limits make it possible for Texinfo files to be understood
both by TeX and by the code which converts them into Info files.

All ASCII printing characters except `@', `{' and `}' can appear in
body text in a Texinfo file and stand for themselves. `@' is the
escape character which introduces commands. `{' and `}' should be
used only to surround arguments to certain commands. `{' and `}'
appearing anywhere else will be treated by TeX as a grouping but
treated by the code that produces an Info file as themselves; this
inconsistency is undesirable, so don't let it occur. To put one of
these special characters into the document, put an `@' character in
front of it. For example, you would insert `@@', `@{', and `@}'.

It is customary in TeX to use doubled single-quote characters to
begin and end quotations, `"' like these `"'. This convention should
be followed in Texinfo files. Also, three hyphens in a row, `--',
are used for a dash--like this. In TeX, a single or even a double
hyphen produces a dash that is shorter than you want.

TeX ignores the line-breaks in the input text, except for blank
lines, which separate paragraphs. Info generally preserves the line
breaks that are present in the input file. Therefore, break the
lines in the Texinfo file the way you want them to appear in the
output Info file, and let TeX take care of itself.

Since Info does not normally refill paragraphs when it processes
them, a line with @-commands in it will sometimes look bad after Info
has run on it. To cause Info to refill the paragraph after finishing
with the other processing, you need to put the command `@refill' at
the end of the paragraph. (*Note Refilling paragraphs and Preventing
indentation: Refilling & Noindent.)

To prevent a paragraph from being indented in the printed manual, put
the command `@noindent' on a line by itself before the start of the
text that should not be indented.

If you mark off a region of the Texinfo file with the `@iftex' and
`@end iftex' commands so that the region will appear only in the
printed copy, you can use TeX commands that cannot be used in the
Info file.

In order to be made into a printed manual, a Texinfo file *must*
begin with lines that looks like

\input texinfo @c -*-texinfo-*-
@setfilename INFO-FILE-NAME
@settitle NAME OF MANUAL

The `\input texinfo' line tells TeX to use the `texinfo.tex' file.
This line is usually followed by a start-of-header line (not shown
here) and then by the `@setfilename INFO-FILE-NAME' and `@settitle
NAME OF MANUAL' lines. These two lines are needed to provide a name
for the Info file and to specify the name used on the left-hand page
headers of the printed manual.

The two lines that contain the `@setfilename' and `@settitle'
commands usually are sandwiched between the start-of-header line and
the end-of-header line. (*Note Start-of-Header::, for more
information.) The start-of-header and end-of-header lines are needed
if you are going to run TeX or Info on just part of a file.

File: texinfo, Node: Short Sample, Prev: Conventions, Up: Overview

A Short Sample Texinfo File
===========================

A Texinfo file looks like the following, which is a complete but very
short Texinfo file. The `@comment' command introduces comments that
will not appear in either the Info file or the printed manual; they
are for the person who reads the Texinfo file.

The first part of the file, from `\input texinfo' through to `@end
titlepage', looks more intimidating than it is. Most of the material
is standard boilerplate; when you write a manual, you just put in the
name of your own manual in this section.

All the commands that tell TeX how to typeset the printed manual and
tell `texinfo-format-buffer' how to create an Info file are preceded
by `@'; thus, `@node' indicates a node and `@chapter' indicates the
start of a chapter.

\input texinfo @c -*-texinfo-*-
@setfilename name-of-texinfo-file
@settitle Name of Manual
@setchapternewpage odd

@ifinfo
@comment The following line inserts the copyright notice
@comment into the Info file.
Copyright @copyright{} 1988 Free Software Foundation, Inc.
@end ifinfo

@comment The titlepage section does not appear in the Info file.
@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@comment The following two commands start the copyright page
@comment for the printed manual. This will not appear in the Info file.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner
@end titlepage

@comment The Top node contains the master menu for the Info file.
@comment This appears only in the Info file, not the printed manual.

@node Top, First Chapter, (dir), (dir)
@comment node-name, next, previous, up

@menu
* First Chapter:: The first chapter is the
only chapter in this sample.
@end menu

@node First Chapter, , Top, Top
@comment node-name, next, previous, up
@chapter First Chapter
@cindex Reference to First Chapter

This is the contents of the first chapter.

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file
like this into an Info file; and @TeX{} typesets it for a printed
manual.

@node Concept Index, , Previous Node, Top
@comment node-name, next, previous, up
@unnumbered Concept Index

@printindex cp

@contents
@bye

Here is what the contents of the first chapter of the sample look like:

This is the contents of the first chapter.

Here is a numbered list.

1. This is the first item.

2. This is the second item.

The `M-x texinfo-format-buffer' command transforms a Texinfo
file like this into an Info file; and TeX typesets it for a
printed manual.

File: texinfo, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top

Using Texinfo Mode
******************

In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
This means that Emacs has commands and features especially designed
for working with Texinfo files. Like all other Emacs features, you
can customize or enhance these as you wish. In particular, the
keybindings are very easy to change. The keybindings described here
are the default or standard ones.

The major features of Texinfo mode are:

* Paragraph filling control.

* A command to show the structure of the file.

* Pre-defined keystroke commands to insert commonly used strings
of text.

* Formatting a part of a file for Info, rather than the whole file.

In general, in Texinfo mode, the GNU Emacs editing commands are like
those in text-mode. The major difference is that the paragraph
separation variable and syntax table are set up so expression
commands skip Texinfo bracket groups. This means, for example, that
the `M-q' (`fill-paragraph') command will refill a paragraph but not
the @-command on a line adjacent to it.

By convention, the Texinfo file name shall end with the extension
`.texinfo' so that Emacs knows to use Texinfo mode for editing it.

* Menu:

* Info on a Region:: Formatting part of a file for Info.
* Showing the Structure:: Showing the structure of a file.
* Inserting:: Inserting frequently used commands.

File: texinfo, Node: Info on a Region, Next: Showing the Structure, Prev: Texinfo Mode, Up: Texinfo Mode

Formatting a Region for Info
============================

To see what part of a Texinfo file will look like after it has been
transformed into an Info file, use the command `C-c C-f'
(`texinfo-format-region'). This command formats the current region
of the Texinfo file for Info and writes it to a temporary buffer
called `*Info Region*'.

For `texinfo-format-region' to work, the file *must* include a line
that has `@setfilename' in its header.

The command is:

`C-c C-f'
texinfo-format-region

File: texinfo, Node: Showing the Structure, Next: Inserting, Prev: Info on a Region, Up: Texinfo Mode

Showing the Structure of a File
===============================

You can show the structure of a Texinfo file by using the `C-c C-s'
command (`texinfo-show-structure'). This command shows the structure
of a Texinfo file by listing the lines with the @-commands for
`@node', `@chapter', `@section' and the like. These lines are
displayed in another window called the `*Occur*' window. In that
window, you can position the cursor over one of the lines and use the
`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
corresponding spot in the Texinfo file.

The two commands are:

`C-c C-s'
texinfo-show-structure

`C-c C-c'
occur-mode-goto-occurrence

Often, when you are working on a manual, you will be interested only
in the structure of the current chapter. In this case, you can mark
off the region of the buffer that you are interested in with the `C-x
n' (`narrow-to-region') command and `texinfo-show-structure' will
work on only that region. (To see the whole buffer again, use `C-x
w' (`widen').)

File: texinfo, Node: Inserting, Prev: Showing the Structure, Up: Texinfo Mode

Inserting Frequently Used Commands
==================================

Texinfo mode provides commands that insert various frequently used
@-commands into the buffer. You can use these commands to save
keystrokes. And you can insert balanced curly braces with the `M-{'
command, (`texinfo-insert-braces') and later use the `M-}' command
(`up-list') to move forward past the closing brace.

The special commands are invoked by typing `C-c' twice and then the
first letter of the @-command.

`C-c C-c c'
texinfo-insert-@code

`C-c C-c d'
texinfo-insert-@dfn

`C-c C-c e'
texinfo-insert-@end

`C-c C-c i'
texinfo-insert-@item

`C-c C-c n'
texinfo-insert-@node

`C-c C-c s'
texinfo-insert-@samp

`C-c C-c v'
texinfo-insert-@var

`M-{'
texinfo-insert-braces

`M-}'
up-list

This list was generated by analyzing the frequency with which
commands were used in the ``GNU Emacs Manual'' and the ``GDB
Manual''. If you wish to add your own insert commands, you can bind
a keyboard macro to a key, use abbreviations or extend the code in
`texinfo.el'.

File: texinfo, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top

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

Various pieces of information have to be provided to Texinfo at the
beginning of a Texinfo file, such as the name of the file, the title
of the document and the like. Generally, the beginning of a Texinfo
file has four parts:

1. The header, marked by start-of-header and end-of-header lines,
that includes the commands for naming the Texinfo file and
telling TeX what definitions' file to use when processing the
file.

2. A section, marked by the `@ifinfo' and `@end ifinfo' commands,
that contains a short statement of what the file is about, the
copyright notice and copying permissions. This section appears
only in the Info file.

3. A section, marked by the `@titlepage' and `@end titlepage'
commands, that contains the title page, the copyright page and
copying permissions. This section appears only in the printed
manual.

4. The `Top' node that contains an extensive menu for the whole
Info file. The contents of this node only appear in the Info
file.

If the Texinfo file has a section containing licensing information
and a warranty disclaimer, that section usually follows the `Top'
node. The licensing section will be followed by a preface or else by
the first chapter of the manual.

Since the copyright notice and the copying permissions are in
sections that appear only in the Info file or only in the printed
manual, this information has to be repeated twice.

The following sample shows what is needed.

\input texinfo @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename name-of-texinfo-file
@settitle Name of Manual
@setchapternewpage odd
@comment %**end of header (This is for running Texinfo on a region.)

@ifinfo
This file documents ...

Permission is granted to ...
@end ifinfo

@titlepage
@sp 10
@center @titlefont{Name of Manual When Printed}
@sp 2
@center Subtitle, If Any
@sp 2
@center Author

@comment The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner

Published by ...

Permission is granted to ...
@end titlepage

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

@menu
* First Chapter:: The first chapter is usually an overview.
* Second Chapter:: ...
<many more menu items here>
@end menu

@node First Chapter, Second Chapter, top, top
@comment node-name, next, previous, up
@chapter First Chapter
@cindex Reference to First Chapter

* Menu:

* Header:: Necessary first lines.
* Permissions for Info:: Copyright notice and copying permissions.
* Titlepage & Copyright Page:: Printed title and copyright pages.
* Top Node:: The top node and master menu.
* License and Distribution:: The importance of the license.

File: texinfo, Node: Header, Next: Permissions for Info, Prev: Beginning a File, Up: Beginning a File

The Texinfo File Header
=======================

Texinfo files start with at least three lines that provide Info and
TeX with necessary information. If you want to run TeX on just a
part of the Texinfo File, you also have to mark these heading lines
with start-of-header and end-of-header lines.

* Menu:

* First Line:: The first line of a Texinfo file.
* Start-of-Header:: Identifying the start of the header.
* Setfilename:: Specifying the name of the Info file.
* Settitle:: Specifying the title used by the headings.
* Setchapternewpage:: Starting chapters on odd numbered pages.
* End-of-Header:: Identifying the end of the header.

File: texinfo, Node: First Line, Next: Start-of-Header, Prev: Header, Up: Header

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

The line serves two functions:

1. When the file is processed by TeX, it loads 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.

2. When the file is edited in GNU Emacs, it causes Texinfo mode to
be used.

The `\input texinfo' line should be followed by the start-of-header
line. This makes it possible for the command for running TeX on a
part of the Texinfo file (`texinfo-hardcopy-region') to operate. The
reason for this is that the `texinfo-hardcopy-region' command will
look on the line preceding the start-of-header line for the `\input
texinfo' line.

File: texinfo, Node: Start-of-Header, Next: Setfilename, Prev: First Line, Up: Header

`start-of-header'
-----------------

The start-of-header line should immediately follow the first line of
the Texinfo file.

The `texinfo-hardcopy-region' command will look at the line preceding
the start-of-header line to find the `\input texinfo' line.

Usually, the start-of-header line looks like this:

@comment %**start of header (This is for running Texinfo on a region.)

The reason for the odd string of characters (`%**') is so that the
`texinfo-hardcopy-region' command does not accidently find something
that it shouldn't when it is looking for the header.

In the default configuration, the phrase `(This is for running
Texinfo on a region.)' is not needed and is just included to make it
easier for someone reading the Texinfo file.

The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.

File: texinfo, Node: Setfilename, Next: Settitle, Prev: Start-of-Header, Up: Header

@setfilename
------------

In order to be made into an Info file, a Texinfo file must contain a
line that looks like this:

@setfilename INFO-FILE-NAME

This line specifies the name of the Info file to be generated. In
fact, there can be other things in the file before this line, but
they are ignored in the generation of an Info file. The
`@setfilename' line is ignored when a printed manual is generated.

File: texinfo, Node: Settitle, Next: Setchapternewpage, Prev: Setfilename, Up: Header

@settitle
---------

In order to be made into a printed manual file, a Texinfo file must
contain a line that specifies the title of the manual. Texinfo uses
this information during printing to put the title on every other page
as a heading; Texinfo puts the current chapter title on the other
pages. Texinfo can find the name of the chapter title from the
information provided by the `@chapter' command, but you must tell it
the manual title with `@settitle':

@settitle TITLE

This command, on a line by itself, causes TITLE to be used for the
headings. Usually, you will use the same words for the title on the
title page and for the title specified by this command for the
headings, but the two could be different. For example, the title on
the title page may be longer than the title specified by the
`settitle' command.

The `@settitle' command should precede everything that generates
actual output.

File: texinfo, Node: Setchapternewpage, Next: End-of-Header, Prev: Settitle, Up: Header

@setchapternewpage
------------------

Conventionally, chapters start on the page on the right hand side of
a book; and the right hand page has an odd number. To make sure that
Texinfo does this, you can use the command `@setchapternewpage'. For
example, to cause each chapter to start on a fresh odd-numbered page:

@setchapternewpage odd

Page numbering is turned on by the `@end titlepage' command, so the
`@setchapternewpage' should come before it. Although it can occur
anywhere in the beginning of the file, it is most convenient to put
it in this location.

File: texinfo, Node: End-of-Header, Prev: Setchapternewpage, Up: Header

`end-of-header'
---------------

The end-of-header line should follow the line containing the
`@setchapternewpage' command.

Usually, the end-of-header line looks like this:

@comment %**end of header (This is for running Texinfo on a region.)

In the default configuration, the phrase `(This is for running
Texinfo on a region.)' is not needed and is just included to make it
easier for someone reading the Texinfo file.

The reason for the odd string of characters (`%**') is so that the
`texinfo-hardcopy-region' command does not accidently find something
that it shouldn't when it is looking for the header.

The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.

File: texinfo, Node: Permissions for Info, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File

Copying Permissions for Info
============================

Since the title page and the copyright page appear only in the
printed copy of the manual, the same information has to inserted in a
section that appears only in the Info file. This section usually
contains a brief description of the contents of the Info file, a
copyright notice and copying permissions.

The copyright notice should read:

and be put on a line by itself.

Standard text for the copyright permissions is contained in the
appendix. *Note Ifinfo Permissions::, for the complete text.

File: texinfo, Node: Titlepage & Copyright Page, Next: Top Node, Prev: Permissions for Info, Up: Beginning a File

The Title and Copyright Pages
=============================

The title and copyright pages appear in the printed manual, but not
in the Info file. Because of this, it is possible to use a couple of
slightly obscure TeX typesetting commands that could not 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.

* Menu:

* Titlepage:: Creating a title page for the printed manual.
* Center:: Centering a line.
* Copyright & Printed Permissions:: Inserting the copyright notice
and printed permissions.

File: texinfo, Node: Titlepage, Next: Center, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page

@titlepage
----------

Start the material for the title page and following copyright page
with `@titlepage' on a line by itself and end it with `@end
titlepage' on a line by itself. The title page and copyright page
material appears only in the printed manual, not in the Info file.

Also, the `@end titlepage' command starts a new page and turns on
page numbering (generation of headings). Therefore, 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 create more than
one unnumbered page. This is how the copyright page is produced.

To select a large font suitable for the title itself, you can use the
command `@titlefont'. For example:

@center @titlefont{Texinfo}

Also, you can use `@sp' commands to adjust vertical spacing. For
example:

@sp 2

In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch
manual.

File: texinfo, Node: Center, Next: Copyright & Printed Permissions, Prev: Titlepage, Up: Titlepage & Copyright Page

@center
-------

A line containing `@center TEXT' produces a line of output containing
TEXT, centered between the margins.

File: texinfo, Node: Copyright & Printed Permissions, Prev: Center, Up: Titlepage & Copyright Page

The Copyright Page and Printed Permissions
------------------------------------------

By international treaty, the copyright notice for a book should
either be on the title page or on the back of the title page. Other
locations in a book are not official and do not provide copyright
protection. The copyright notice should include the year followed by
the name of the person or organization who has the copyright.

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

To cause a page break, the `@page' command is used. In the sample,
the `@page' command is followed by the somewhat mysterious line that
reads: `@vskip 0pt plus 1filll'. This is a line that uses TeX
commands to push the copyright notice and the other text on the
copyright page towards the bottom of the page. The `@vskip' command
means to skip lines and put in white space. The `0pt plus 1filll'
means to put in zero points of mandatory white space, and as much
optional white space as needed. Note the use of three `l's in the
word `filll'; this is the correct use in TeX.

The `@copyright{}' command generates a `c' inside a circle. The
copyright notice itself has the following legally defined sequence:

It is customary to put information on how to get a manual after the
copyright notice (the address of the Free Software Foundation, for
example) and the permissions.

Note that the permissions have to be repeated here as well as in the
`ifinfo' section that immediately follows the header since this
section appears only in the printed manual and the `ifinfo' section
appears only in the Info file.

Standard text for the permissions appears in the appendix. *Note
Sample Permissions::.

File: texinfo, Node: Top Node, Next: License and Distribution, Prev: Titlepage & Copyright Page, Up: Beginning a File

The Top Node and Master Menu
============================

The `Top' node contains an extensive, master menu for the whole Info
file. The contents of this node appear only in the Info file.
Nothing in this node should appear in the printed file. Since a node
line by itself and a menu by itself are not printed, the contents of
this node do not have to be within a region delineated by `@ifinfo'
and `@end ifinfo' commands. However, any text within the node should
be marked off in that manner. You may want to put a short summary
before the master menu inside a region delineated by `@ifinfo' and
`@end ifinfo' commands. Usually, the `Previous' and `Up' nodes refer
to the top level directory of the whole Info system, with pointers to
`(dir)'.

Generally, the top 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 major
appendices.

* The second part contains entries for the indices. In an Info
file, it is very useful to have indices here at the beginning of
the file in the top node rather than at the end, as in a printed
book.

* The third and subsequent parts contain a listing of the other,
lower level nodes, often ordered by chapter. This way, an
inquirer can go directly to a particular node if he or she is
searching for specific information. (These nodes are not
required; use them if you think they are a convenience.)

Each section in the menu can be introduced a descriptive line. So
long as the line does not begin with an asterisk, it will not be
treated as a menu item. (*Note Making Menus: Menu, for more
information.)

For example, the Top node of this manual looks like this (but with
many more entries):

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

@menu
* Overview:: What is Texinfo?
* Texinfo Mode:: Special features in GNU Emacs.
...

Indices, nodes containing large menus

* Command Index:: An item for each @-command.
* Concept Index:: An item for each concept.

A detailed node listing

Overview
* Info File:: Characteristics of the Info file.
* Printed Manual:: Characteristics of the printed manual.

Using Texinfo Mode
* Info on a Region:: Formatting a region for Info.
* Showing the Structure:: Showing the structure of a file.
...
...

File: texinfo, Node: License and Distribution, Prev: Top Node, Up: Beginning a File

Licensing and Distribution Information
======================================

If the Texinfo file has a section containing the "General Public
License" and the distribution information and a warranty disclaimer,
this section usually follows the `Top' node. The licensing and
distribution information and the disclaimer are followed by a preface
or else by the first chapter of the manual.

The licensing agreement is very important to Project GNU
documentation and software. Without it, you may find that you can no
longer get the software or its documentation. This sounds
paradoxical, but the state of the world is such that documentation
and software that does not have a "restrictive" license to make them
freely distributable may be lost to the public. This has happened.

For a good example of the text that could be used for the
Distribution, General Public License and NO WARRANTY sections of your
document, see the latest version of the ``GNU Emacs Manual''.

Although a preface 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, the preface would follow the licensing and distribution
information, although sometimes people put it earlier in the
document. Usually, a preface is put in an `@unnumbered' section.
(*Note Unnumbered and Appendix::.)

File: texinfo, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top

Ending a Texinfo File
*********************

The end of a Texinfo file should include the indices, the commands to
generate detailed and summary tables of contents and the @-command
that tells TeX that it has reached the end of the file.

For example, a Texinfo file might be ended as follows:

@node Concept Index, , Previous Node, Top
@comment node-name, next, previous, up
@unnumbered Concept Index

@printindex cp

@contents
@bye

The `@bye' command should be on a line by itself and every Texinfo
file must end with such a line. This command terminates TeX
processing and forces out unfinished pages.

* Menu:

* Contents:: Generating a table of contents
* Indices:: Generating, sorting and printing indices

File: texinfo, Node: Contents, Next: Indices, Up: Ending a File

Generating a Table of Contents
==============================

The commands `@chapter', `@section', etc., supply the information to
make up a table of contents, but they do not cause an actual table to
be generated. To do this, you must use the commands `@contents' and
`@summarycontents'.

`@contents'
The table of contents command outputs (into a printed manual) a
complete table of contents, based on the `@chapter',
`@unnumbered' and other sectioning commands. This command
should be used on a line by itself.

`@summarycontents'
The summary contents command generates a summary table of
contents that lists only the chapters (and appendices and
unnumbered chapters); sections, subsections and subsubsections
are omitted. This command should be used on a line by itself.
Only large manuals need a summary table of contents.

You can use either one of these commands, or both. Each command
automatically generates a chapter-like heading at the top of the page.
Tables of contents should be generated at the very end of the manual,
just before the `@bye' command; the tables of contents commands
should follow any indices that are output, so that the indices will
appear in the contents.

INDICES...
@summarycontents
@contents
@bye

The commands `@contents' and `@summarycontents' are ignored when an
Info file is being generated.