path: root/gnu/usr.bin/texinfo/info-files/texi.info-9

This is Info file texi.info, produced by Makeinfo-1.55 from the input
file texi.texi.

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

   Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
Inc.

   This is the second edition of the Texinfo documentation,
and is consistent with version 2 of `texinfo.tex'.

   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 Free Software Foundation.


File: texi.info,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top

Tips and Hints
**************

   Here are some tips for writing Texinfo documentation:

   * Write in the present tense, not in the past or the future.

   * Write actively!  For example, write "We recommend that ..." rather
     than "It is recommended that ...".

   * Use 70 or 72 as your fill column.  Longer lines are hard to read.

   * Include a copyright notice and copying permissions.

Index, index, index!
....................

   Write many index entries, in different ways.  Readers like indices;
they are helpful and convenient.

   Although it is easiest to write index entries as you write the body
of the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

   Here are more hints we have found valuable:

   * Write each index entry differently, so each entry refers to a
     different place in the document.  The index of an Info file lists
     only one location for each entry.

   * Write index entries only where a topic is discussed significantly.
     For example, it is not useful to index "debugging information" in
     a chapter on reporting bugs.  Someone who wants to know about
     debugging information will certainly not find it in that chapter.

   * Consistently capitalize the first word of every index entry, or
     else use lower case.  According to convention, you should
     capitalize the first word of an index entry.  However, this
     practice may make an index look crowded.  Some writers prefer
     lower case.  Regardless of which you prefer, choose one style and
     stick to it.  Mixing the two styles looks bad.

   * Always capitalize or use upper case for those words in an index for
     which this is proper, such as names of countries or acronyms.

   * Write the indexing commands that refer to a whole section
     immediately after the section command, and write the indexing
     commands that refer to the paragraph before the paragraph.

     In the example that follows, a blank line comes after the index
     entry for "Leaping":

          @section The Dog and the Fox
          @cindex Jumping, in general
          @cindex Leaping
          
          @cindex Dog, lazy, jumped over
          @cindex Lazy dog jumped over
          @cindex Fox, jumps over dog
          @cindex Quick fox jumps over dog
          The quick brown fox jumps over the lazy dog.

     (Note that the example shows entries for the same concept that are
     written in different ways--`Lazy dog', and `Dog, lazy'--so readers
     can look up the concept in different ways.)

Blank lines
...........

   * Insert a blank line between a sectioning command and the first
     following sentence or paragraph, or between the indexing commands
     associated with the sectioning command and the first following
     sentence or paragraph, as shown in the tip on indexing.
     Otherwise, a formatter may fold title and paragraph together.

   * Always insert a blank line before an `@table' command and after an
     `@end table' command; but never insert a blank line after an
     `@table' command or before an `@end table' command.

     For example,

          Types of fox:
          
          @table @samp
          @item Quick
          Jump over lazy dogs.
          
          @item Brown
          Also jump over lazy dogs.
          @end table
          @noindent
          On the other hand, ...

     Insert blank lines before and after `@itemize' ... `@end itemize'
     and `@enumerate' ... `@end enumerate' in the same way.

Complete phrases
................

   Complete phrases are easier to read than ...

   * Write entries in an itemized list as complete sentences; or at
     least, as complete phrases.  Incomplete expressions ... awkward
     ... like this.

   * Write the prefatory sentence or phrase for a multi-item list or
     table as a complete expression.  Do not write "You can set:";
     instead, write "You can set these variables:".  The former
     expression sounds cut off.

Editions, dates and versions
............................

   Write the edition and version numbers and date in three places in
every manual:

  1. In the first `@ifinfo' section, for people reading the Texinfo
     file.

  2. In the `@titlepage' section, for people reading the printed manual.

  3. In the `Top' node, for people reading the Info file.

Also, it helps to write a note before the first `@ifinfo' section to
explain what you are doing.

For example:

     @c ===> NOTE! <==
     @c Specify the edition and version numbers and date
     @c in *three* places:
     @c   1. First ifinfo section  2. title page  3. top node
     @c To find the locations, search for !!set
     
     @ifinfo
     @c !!set edition, date, version
     This is Edition 4.03, January 1992,
     of the @cite{GDB Manual} for GDB Version 4.3.
     ...

--or use `@set' and `@value' (*note `@value' Example: value Example.).

Definition Commands
...................

   Definition commands are `@deffn', `@defun', `@defmac', and the like,
and enable you to write descriptions in a uniform format.

   * Write just one definition command for each entity you define with a
     definition command.  The automatic indexing feature creates an
     index entry that leads the reader to the definition.

   * Use `@table' ... `@end table' in an appendix that contains a
     summary of functions, not `@deffn' or other definition commands.

Capitalization
..............

   * Capitalize `Texinfo'; it is a name.  Do not write the `x' or `i'
     in upper case.

   * Capitalize `Info'; it is a name.

   * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
     `X'.  This command causes the formatters to typeset the name
     according to the wishes of Donald Knuth, who wrote TeX.

Spaces
......

   Do not use spaces to format a Texinfo file, except inside of
`@example' ... `@end example' and similar commands.

   For example, TeX fills the following:

         @kbd{C-x v}
         @kbd{M-x vc-next-action}
            Perform the next logical operation
            on the version-controlled file
            corresponding to the current buffer.

so it looks like this:

     `C-x v' `M-x vc-next-action' Perform the next logical operation on
     the version-controlled file corresponding to the current buffer.

In this case, the text should be formatted with `@table', `@item', and
`@itemx', to create a table.

@code, @samp, @var, and `---'
.............................

   * Use `@code' around Lisp symbols, including command names.  For
     example,

          The main function is @code{vc-next-action}, ...

   * Avoid putting letters such as `s' immediately after an `@code'.
     Such letters look bad.

   * Use `@var' around meta-variables.  Do not write angle brackets
     around them.

   * Use three hyphens in a row, `---', to indicate a long dash.  TeX
     typesets these as a long dash and the Info formatters reduce three
     hyphens to two.

Periods Outside of Quotes
.........................

   Place periods and other punctuation marks *outside* of quotations,
unless the punctuation is part of the quotation.  This practice goes
against convention, but enables the reader to distinguish between the
contents of the quotation and the whole passage.

   For example, you should write the following sentence with the period
outside the end quotation marks:

     Evidently, `au' is an abbreviation for ``author''.

since `au' does *not* serve as an  abbreviation for `author.' (with a
period following the word).

Introducing New Terms
.....................

   * Introduce new terms so that a user who does not know them can
     understand them from context; or write a definition for the term.

     For example, in the following, the terms "check in", "register" and
     "delta" are all appearing for the first time; the example sentence
     should be rewritten so they are understandable.

          The major function assists you in checking in a file to your
          version control system and registering successive sets of
          changes to it as deltas.

   * Use the `@dfn' command around a word being introduced, to indicate
     that the user should not expect to know the meaning already, and
     should expect to learn the meaning from this passage.

@pxref
......

   Absolutely never use `@pxref' except in the special context for
which it is designed: inside parentheses, with the closing parenthesis
following immediately after the closing brace.  One formatter
automatically inserts closing punctuation and the other does not.  This
means that the output looks right both in printed output and in an Info
file, but only when the command is used inside parentheses.

Invoking from a Shell
.....................

   You can invoke programs such as Emacs, GCC, and GAWK from a shell.
The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, readers find it hard to search for the
section.

   Name such sections with a phrase beginning with the word
`Invoking ...', as in `Invoking Emacs'; this way users can find the
section easily.

ANSI C Syntax
.............

   When you use `@example' to describe a C function's calling
conventions, use the ANSI C syntax, like this:

     void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with `@var'.

   Avoid the obsolete style that looks like this:

     #include <dld.h>
     
     dld_init (path)
     char *path;

   Also, it is best to avoid writing `#include' above the declaration
just to indicate that the function is declared in a header file.  The
practice may give the misimpression that the `#include' belongs near
the declaration of the function.  Either state explicitly which header
file holds the declaration or, better yet, name the header file used
for a group of functions at the beginning of the section that describes
the functions.

Bad Examples
............

   Here are several examples of bad writing to avoid:

   In this example, say, " ... you must `@dfn'{check in} the new
version."  That flows better.

     When you are done editing the file, you must perform a
     `@dfn'{check in}.

   In the following example, say, "... makes a unified interface such
as VC mode possible."

     SCCS, RCS and other version-control systems all perform similar
     functions in broadly similar ways (it is this resemblance which
     makes a unified control mode like this possible).

   And in this example, you should specify what `it' refers to:

     If you are working with other people, it assists in coordinating
     everyone's changes so they do not step on each other.

And Finally ...
...............

   * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
     in the name `Bach'.  But pronounce Texinfo as in `speck':
     `teckinfo'.

   * Write notes for yourself at the very end of a Texinfo file after
     the `@bye'.  None of the formatters process text after the `@bye';
     it is as if the text were within `@ignore' ...  `@end ignore'.


File: texi.info,  Node: Sample Texinfo File,  Next: Sample Permissions,  Prev: Tips,  Up: Top

A Sample Texinfo File
*********************

   Here is a complete, short sample Texinfo file, without any
commentary.  You can see this file, with comments, in the first chapter.
*Note A Short Sample Texinfo File: Short Sample.

     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename sample.info
     @settitle Sample Document
     @c %**end of header
     
     @setchapternewpage odd
     
     @ifinfo
     This is a short example of a complete Texinfo file.
     
     Copyright 1990 Free Software Foundation, Inc.
     @end ifinfo
     
     @titlepage
     @sp 10
     @comment The title is printed in a large font.
     @center @titlefont{Sample Title}
     
     @c The following two commands start the copyright page.
     @page
     @vskip 0pt plus 1filll
     Copyright @copyright{} 1990 Free Software Foundation, Inc.
     @end titlepage
     
     @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.
     * Concept Index::    This index has two entries.
     @end menu
     
     @node    First Chapter, Concept Index, Top,      Top
     @comment node-name,     next,          previous, up
     @chapter First Chapter
     @cindex Sample index entry
     
     This is the contents of the first chapter.
     @cindex Another sample index entry
     
     Here is a numbered list.
     
     @enumerate
     @item
     This is the first item.
     
     @item
     This is the second item.
     @end enumerate
     
     The @code{makeinfo} and @code{texinfo-format-buffer}
     commands transform a Texinfo file such as this into
     an Info file; and @TeX{} typesets it for a printed
     manual.
     
     @node    Concept Index,    ,  First Chapter, Top
     @comment node-name,    next,  previous,      up
     @unnumbered Concept Index
     
     @printindex cp
     
     @contents
     @bye


File: texi.info,  Node: Sample Permissions,  Next: Include Files,  Prev: Sample Texinfo File,  Up: Top

Sample Permissions
******************

   Texinfo files should contain sections that tell the readers that they
have the right to copy and distribute the Texinfo file, the Info file,
and the printed manual.

   Also, if you are writing a manual about software, you should explain
that the software is free and either include the GNU General Public
License (GPL) or provide a reference to it.  *Note Distribution:
(emacs)Distrib, for an example of the text that could be used in the
software "Distribution", "General Public License", and "NO WARRANTY"
sections of a document.  *Note Texinfo Copying Conditions: Copying, for
an example of a brief explanation of how the copying conditions provide
you with rights.

* Menu:

* Inserting Permissions::       How to put permissions in your document.
* ifinfo Permissions::          Sample `ifinfo' copying permissions.
* Titlepage Permissions::       Sample Titlepage copying permissions.


File: texi.info,  Node: Inserting Permissions,  Next: ifinfo Permissions,  Up: Sample Permissions

Inserting Permissions
=====================

   In a Texinfo file, the first `@ifinfo' section usually begins with a
line that says what the file documents.  This is what a person reading
the unprocessed Texinfo file or using the advanced Info command `g *'
sees first.  *note Advanced Info commands: (info)Expert, for more
information. (A reader using the regular Info commands usually starts
reading at the first node and skips this first section, which is not in
a node.)

   In the `@ifinfo' section, the summary sentence is followed by a
copyright notice and then by the copying permission notice.  One of the
copying permission paragraphs is enclosed in `@ignore' and `@end
ignore' commands.  This paragraph states that the Texinfo file can be
processed through TeX and printed, provided the printed manual carries
the proper copying permission notice.  This paragraph is not made part
of the Info file since it is not relevant to the Info file; but it is a
mandatory part of the Texinfo file since it permits people to process
the Texinfo file in TeX and print the results.

   In the printed manual, the Free Software Foundation copying
permission notice follows the copyright notice and publishing
information and is located within the region delineated by the
`@titlepage' and `@end titlepage' commands.  The copying permission
notice is exactly the same as the notice in the `@ifinfo' section
except that the paragraph enclosed in `@ignore' and `@end ignore'
commands is not part of the notice.

   To make it simple to insert a permission notice into each section of
the Texinfo file, sample permission notices for each section are
reproduced in full below.

   Note that you may need to specify the correct name of a section
mentioned in the permission notice.  For example, in `The GDB Manual',
the name of the section referring to the General Public License is
called the "GDB General Public License", but in the sample shown below,
that section is referred to generically as the "GNU General Public
License".  If the Texinfo file does not carry a copy of the General
Public License, leave out the reference to it, but be sure to include
the rest of the sentence.


File: texi.info,  Node: ifinfo Permissions,  Next: Titlepage Permissions,  Prev: Inserting Permissions,  Up: Sample Permissions

`ifinfo' Copying Permissions
============================

   In the `@ifinfo' section of a Texinfo file, the standard Free
Software Foundation permission notice reads as follows:

     This file documents ...
     
     Copyright 1992 Free Software Foundation, Inc.
     
     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.
     
     @ignore
     Permission is granted to process this file through TeX
     and print the results, provided the printed document
     carries a copying permission notice identical to this
     one except for the removal of this paragraph (this
     paragraph not being relevant to the printed manual).
     
     @end ignore
     Permission is granted to copy and distribute modified
     versions of this manual under the conditions for
     verbatim copying, provided also that the sections
     entitled ``Copying'' and ``GNU General Public License''
     are included exactly as in the original, and 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 Free Software Foundation.


File: texi.info,  Node: Titlepage Permissions,  Prev: ifinfo Permissions,  Up: Sample Permissions

Titlepage Copying Permissions
=============================

   In the `@titlepage' section of a Texinfo file, the standard Free
Software Foundation copying permission notice follows the copyright
notice and publishing information.  The standard phrasing is as follows:

     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 also that the sections
     entitled ``Copying'' and ``GNU General Public License''
     are included exactly as in the original, and 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 Free Software Foundation.


File: texi.info,  Node: Include Files,  Next: Headings,  Prev: Sample Permissions,  Up: Top

Include Files
*************

   When TeX or an Info formatting command sees an `@include' command in
a Texinfo file, it processes the contents of the file named by the
command and incorporates them into the DVI or Info file being created.
Index entries from the included file are incorporated into the indices
of the output file.

   Include files let you keep a single large document as a collection of
conveniently small parts.

* Menu:

* Using Include Files::         How to use the `@include' command.
* texinfo-multiple-files-update::  How to create and update nodes and
                                  menus when using included files.
* Include File Requirements::   What `texinfo-multiple-files-update' expects.
* Sample Include File::         A sample outer file with included files
                                  within it; and a sample included file.
* Include Files Evolution::     How use of the `@include' command
                                  has changed over time.


File: texi.info,  Node: Using Include Files,  Next: texinfo-multiple-files-update,  Up: Include Files

How to Use Include Files
========================

   To include another file within a Texinfo file, write the `@include'
command at the beginning of a line and follow it on the same line by
the name of a file to be included.  For example:

     @include buffers.texi

   An included file should simply be a segment of text that you expect
to be included as is into the overall or "outer" Texinfo file; it
should not contain the standard beginning and end parts of a Texinfo
file.  In particular, you should not start an included file with a line
saying `\input texinfo'; if you do, that phrase is inserted into the
output file as is.  Likewise, you should not end an included file with
an `@bye' command; nothing after `@bye' is formatted.

   In the past, you were required to write an `@setfilename' line at the
beginning of an included file, but no longer.  Now, it does not matter
whether you write such a line.  If an `@setfilename' line exists in an
included file, it is ignored.

   Conventionally, an included file begins with an `@node' line that is
followed by an `@chapter' line.  Each included file is one chapter.
This makes it easy to use the regular node and menu creating and
updating commands to create the node pointers and menus within the
included file.  However, the simple Emacs node and menu creating and
updating commands do not work with multiple Texinfo files.  Thus you
cannot use these commands to fill in the `Next', `Previous', and `Up'
pointers of the `@node' line that begins the included file.  Also, you
cannot use the regular commands to create a master menu for the whole
file.  Either you must insert the menus and the `Next', `Previous', and
`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
command, `texinfo-multiple-files-update', that is designed for
`@include' files.


File: texi.info,  Node: texinfo-multiple-files-update,  Next: Include File Requirements,  Prev: Using Include Files,  Up: Include Files

`texinfo-multiple-files-update'
===============================

   GNU Emacs Texinfo mode provides a command to handle included files
called `texinfo-multiple-files-update'.  This command creates or
updates `Next', `Previous', and `Up' pointers of included files as well
as those in the outer or overall Texinfo file, and it creates or
updates a main menu in the outer file.  Depending whether you call it
with optional arguments, the command updates only the pointers in the
first `@node' line of the included files or all of them:

`M-x texinfo-multiple-files-update'
     Called without any arguments:

        - Create or update the `Next', `Previous', and `Up' pointers of
          the first `@node' line in each file included in an outer or
          overall Texinfo file.

        - Create or update the `Top' level node pointers of the outer or
          overall file.

        - Create or update a main menu in the outer file.

`C-u M-x texinfo-multiple-files-update'
     Called with `C-u' as a prefix argument:

        - Create or update pointers in the first `@node' line in each
          included file.

        - Create or update the `Top' level node pointers of the outer
          file.

        - Create and insert a master menu in the outer file.  The
          master menu is made from all the menus in all the included
          files.

`C-u 8 M-x texinfo-multiple-files-update'
     Called with a numeric prefix argument, such as `C-u 8':

        - Create or update *all* the `Next', `Previous', and `Up'
          pointers of all the included files.

        - Create or update *all* the menus of all the included files.

        - Create or update the `Top' level node pointers of the outer or
          overall file.

        - And then create a master menu in the outer file.  This is
          similar to invoking `texinfo-master-menu' with an argument
          when you are working with just one file.

   Note the use of the prefix argument in interactive use: with a
regular prefix argument, just `C-u', the
`texinfo-multiple-files-update' command inserts a master menu; with a
numeric prefix argument, such as `C-u 8', the command updates *every*
pointer and menu in *all* the files and then inserts a master menu.


File: texi.info,  Node: Include File Requirements,  Next: Sample Include File,  Prev: texinfo-multiple-files-update,  Up: Include Files

Include File Requirements
=========================

   If you plan to use the `texinfo-multiple-files-update' command, the
outer Texinfo file that lists included files within it should contain
nothing but the beginning and end parts of a Texinfo file, and a number
of `@include' commands listing the included files.  It should not even
include indices, which should be listed in an included file of their
own.

   Moreover, each of the included files must contain exactly one highest
level node (conventionally, `@chapter' or equivalent), and this node
must be the first node in the included file.  Furthermore, each of
these highest level nodes in each included file must be at the same
hierarchical level in the file structure.  Usually, each is an
`@chapter', an `@appendix', or an `@unnumbered' node.  Thus, normally,
each included file contains one, and only one, chapter or
equivalent-level node.

   The outer file should contain only *one* node, the `Top' node.  It
should *not* contain any nodes besides the single `Top' node.  The
`texinfo-multiple-files-update' command will not process them.


File: texi.info,  Node: Sample Include File,  Next: Include Files Evolution,  Prev: Include File Requirements,  Up: Include Files

Sample File with `@include'
===========================

   Here is an example of a complete outer Texinfo file with `@include'
files within it before running `texinfo-multiple-files-update', which
would insert a main or master menu:

     \input texinfo @c -*-texinfo-*-
     @setfilename  include-example.info
     @settitle Include Example
     
     @setchapternewpage odd
     @titlepage
     @sp 12
     @center @titlefont{Include Example}
     @sp 2
     @center by Whom Ever
     
     @page
     @vskip 0pt plus 1filll
     Copyright @copyright{} 1990 Free Software Foundation, Inc.
     @end titlepage
     
     @ifinfo
     @node Top, First, (dir), (dir)
     @top Master Menu
     @end ifinfo
     
     @include foo.texinfo
     @include bar.texinfo
     @include concept-index.texinfo
     
     @summarycontents
     @contents
     
     @bye

   An included file, such as `foo.texinfo', might look like this:

     @node First, Second, , Top
     @chapter First Chapter
     
     Contents of first chapter ...

   The full contents of `concept-index.texinfo' might be as simple as
this:

     @node Concept Index, , Second, Top
     @unnumbered Concept Index
     
     @printindex cp

   The outer Texinfo source file for `The GNU Emacs Lisp Reference
Manual' is named `elisp.texi'.  This outer file contains a master menu
with 417 entries and a list of 41 `@include' files.


File: texi.info,  Node: Include Files Evolution,  Prev: Sample Include File,  Up: Include Files

Evolution of Include Files
==========================

   When Info was first created, it was customary to create many small
Info files on one subject.  Each Info file was formatted from its own
Texinfo source file.  This custom meant that Emacs did not need to make
a large buffer to hold the whole of a large Info file when someone
wanted information; instead, Emacs allocated just enough memory for the
small Info file that contained the particular information sought.  This
way, Emacs could avoid wasting memory.

   References from one file to another were made by referring to the
file name as well as the node name. (*Note Referring to Other Info
Files: Other Info Files.  Also, see *Note `@xref' with Four and Five
Arguments: Four and Five Arguments.)

   Include files were designed primarily as a way to create a single,
large printed manual out of several smaller Info files.  In a printed
manual, all the references were within the same document, so TeX could
automatically determine the references' page numbers.  The Info
formatting commands used include files only for creating joint indices;
each of the individual Texinfo files had to be formatted for Info
individually.  (Each, therefore, required its own `@setfilename' line.)

   However, because large Info files are now split automatically, it is
no longer necessary to keep them small.

   Nowadays, multiple Texinfo files are used mostly for large documents,
such as `The GNU Emacs Lisp Reference Manual', and for projects in
which several different people write different sections of a document
simultaneously.

   In addition, the Info formatting commands have been extended to work
with the `@include' command so as to create a single large Info file
that is split into smaller files if necessary.  This means that you can
write menus and cross references without naming the different Texinfo
files.


File: texi.info,  Node: Headings,  Next: Catching Mistakes,  Prev: Include Files,  Up: Top

Page Headings
*************

   Most printed manuals contain headings along the top of every page
except the title and copyright pages.  Some manuals also contain
footings.  (Headings and footings have no meaning to Info, which is not
paginated.)

* Menu:

* Headings Introduced::         Conventions for using page headings.
* Heading Format::              Standard page heading formats.
* Heading Choice::              How to specify the type of page heading.
* Custom Headings::             How to create your own headings and footings.


File: texi.info,  Node: Headings Introduced,  Next: Heading Format,  Up: Headings

Headings Introduced
===================

   Texinfo provides standard page heading formats for manuals that are
printed on one side of each sheet of paper and for manuals that are
printed on both sides of the paper.  Usually, you will use one or other
of these formats, but you can specify your own format, if you wish.

   In addition, you can specify whether chapters should begin on a new
page, or merely continue the same page as the previous chapter; and if
chapters begin on new pages, you can specify whether they must be
odd-numbered pages.

   By convention, a book is printed on both sides of each sheet of
paper.  When you open a book, the right-hand page is odd-numbered, and
chapters begin on right-hand pages--a preceding left-hand page is left
blank if necessary.  Reports, however, are often printed on just one
side of paper, and chapters begin on a fresh page immediately following
the end of the preceding chapter.  In short or informal reports,
chapters often do not begin on a new page at all, but are separated
from the preceding text by a small amount of whitespace.

   The `@setchapternewpage' command controls whether chapters begin on
new pages, and whether one of the standard heading formats is used.  In
addition, Texinfo has several heading and footing commands that you can
use to generate your own heading and footing formats.

   In Texinfo, headings and footings are single lines at the tops and
bottoms of pages; you cannot create multiline headings or footings.
Each header or footer line is divided into three parts: a left part, a
middle part, and a right part.  Any part, or a whole line, may be left
blank.  Text for the left part of a header or footer line is set
flushleft; text for the middle part is centered; and, text for the
right part is set flushright.


File: texi.info,  Node: Heading Format,  Next: Heading Choice,  Prev: Headings Introduced,  Up: Headings

Standard Heading Formats
========================

   Texinfo provides two standard heading formats, one for manuals
printed on one side of each sheet of paper, and the other for manuals
printed on both sides of the paper.

   By default, nothing is specified for the footing of a Texinfo file,
so the footing remains blank.

   The standard format for single-sided printing consists of a header
line in which the left-hand part contains the name of the chapter, the
central part is blank, and the right-hand part contains the page number.

   A single-sided page looks like this:

        _______________________
       |                       |
       | chapter   page number |
       |                       |
       | Start of text ...     |
       | ...                   |
       |                       |

   The standard format for two-sided printing depends on whether the
page number is even or odd.  By convention, even-numbered pages are on
the left- and odd-numbered pages are on the right.  (TeX will adjust the
widths of the left- and right-hand margins.  Usually, widths are
correct, but during double-sided printing, it is wise to check that
pages will bind properly--sometimes a printer will produce output in
which the even-numbered pages have a larger right-hand margin than the
odd-numbered pages.)

   In the standard double-sided format, the left part of the left-hand
(even-numbered) page contains the page number, the central part is
blank, and the right part contains the title (specified by the
`@settitle' command).  The left part of the right-hand (odd-numbered)
page contains the name of the chapter, the central part is blank, and
the right part contains the page number.

   Two pages, side by side as in an open book, look like this:

        _______________________     _______________________
       |                       |   |                       |
       | page number     title |   | chapter   page number |
       |                       |   |                       |
       | Start of text ...     |   | More  text ...        |
       | ...                   |   | ...                   |
       |                       |   |                       |

The chapter name is preceded by the word `Chapter', the chapter number
and a colon.  This makes it easier to keep track of where you are in
the manual.


File: texi.info,  Node: Heading Choice,  Next: Custom Headings,  Prev: Heading Format,  Up: Headings

Specifying the Type of Heading
==============================

   TeX does not begin to generate page headings for a standard Texinfo
file until it reaches the `@end titlepage' command.  Thus, the title
and copyright pages are not numbered.  The `@end titlepage' command
causes TeX to begin to generate page headings according to a standard
format specified by the `@setchapternewpage' command that precedes the
`@titlepage' section.

   There are four possibilities:

No `@setchapternewpage' command
     Cause TeX to specify the single-sided heading format, with chapters
     on new pages. This is the same as `@setchapternewpage on'.

`@setchapternewpage on'
     Specify the single-sided heading format, with chapters on new
     pages.

`@setchapternewpage off'
     Cause TeX to start a new chapter on the same page as the last page
     of the preceding chapter, after skipping some vertical whitespace.
     Also cause TeX to typeset for single-sided printing.  (You can
     override the headers format with the `@headings double' command;
     see *Note The `@headings' Command: headings on off.)

`@setchapternewpage odd'
     Specify the double-sided heading format, with chapters on new
     pages.

Texinfo lacks an `@setchapternewpage even' command.


File: texi.info,  Node: Custom Headings,  Prev: Heading Choice,  Up: Headings

How to Make Your Own Headings
=============================

   You can use the standard headings provided with Texinfo or specify
your own.

   Texinfo provides six commands for specifying headings and footings.
The `@everyheading' command and `@everyfooting' command generate page
headers and footers that are the same for both even- and odd-numbered
pages.  The `@evenheading' command and `@evenfooting' command generate
headers and footers for even-numbered (left-hand) pages; and the
`@oddheading' command and `@oddfooting' command generate headers and
footers for odd-numbered (right-hand) pages.

   Write custom heading specifications in the Texinfo file immediately
after the `@end titlepage' command.  Enclose your specifications
between `@iftex' and `@end iftex' commands since the
`texinfo-format-buffer' command may not recognize them.  Also, you must
cancel the predefined heading commands with the `@headings off' command
before defining your own specifications.

   Here is how to tell TeX to place the chapter name at the left, the
page number in the center, and the date at the right of every header
for both even- and odd-numbered pages:

     @iftex
     @headings off
     @everyheading @thischapter @| @thispage @| @today{}
     @end iftex

You need to divide the left part from the central part and the central
part from the right had part by inserting `@|' between parts.
Otherwise, the specification command will not be able to tell where the
text for one part ends and the next part begins.

   Each part can contain text or @-commands.  The text is printed as if
the part were within an ordinary paragraph in the body of the page.
The @-commands replace themselves with the page number, date, chapter
name, or whatever.

   Here are the six heading and footing commands:

`@everyheading LEFT @| CENTER @| RIGHT'
`@everyfooting LEFT @| CENTER @| RIGHT'
     The `every' commands specify the format for both even- and
     odd-numbered pages.  These commands are for documents that are
     printed on one side of each sheet of paper, or for documents in
     which you want symmetrical headers or footers.

`@evenheading LEFT @| CENTER @| RIGHT'
`@oddheading  LEFT @| CENTER @| RIGHT'
`@evenfooting LEFT @| CENTER @| RIGHT'
`@oddfooting  LEFT @| CENTER @| RIGHT'
     The `even' and `odd' commands specify the format for even-numbered
     pages and odd-numbered pages.  These commands are for books and
     manuals that are printed on both sides of each sheet of paper.

   Use the `@this...' series of @-commands to provide the names of
chapters and sections and the page number.  You can use the `@this...'
commands in the left, center, or right portions of headers and footers,
or anywhere else in a Texinfo file so long as they are between `@iftex'
and `@end iftex' commands.

   Here are the `@this...' commands:

`@thispage'
     Expands to the current page number.

`@thischaptername'
     Expands to the name of the current chapter.

`@thischapter'
     Expands to the number and name of the current chapter, in the
     format `Chapter 1: Title'.

`@thistitle'
     Expands to the name of the document, as specified by the
     `@settitle' command.

`@thisfile'
     For `@include' files only: expands to the name of the current
     `@include' file.  If the current Texinfo source file is not an
     `@include' file, this command has no effect.  This command does
     *not* provide the name of the current Texinfo source file unless
     it is an `@include' file.  (*Note Include Files::, for more
     information about `@include' files.)

You can also use the `@today{}' command, which expands to the current
date, in `1 Jan 1900' format.

   Other @-commands and text are printed in a header or footer just as
if they were in the body of a page.  It is useful to incorporate text,
particularly when you are writing drafts:

     @iftex
     @headings off
     @everyheading @emph{Draft!} @| @thispage @| @thischapter
     @everyfooting @| @| Version: 0.27: @today{}
     @end iftex

   Beware of overlong titles: they may overlap another part of the
header or footer and blot it out.


File: texi.info,  Node: Catching Mistakes,  Next: Refilling Paragraphs,  Prev: Headings,  Up: Top

Formatting Mistakes
*******************

   Besides mistakes in the content of your documentation, there are two
kinds of mistake you can make with Texinfo:  you can make mistakes with
@-commands, and you can make mistakes with the structure of the nodes
and chapters.

   Emacs has two tools for catching the @-command mistakes and two for
catching structuring mistakes.

   For finding problems with @-commands, you can run TeX or a region
formatting command on the region that has a problem; indeed, you can
run these commands on each region as you write it.

   For finding problems with the structure of nodes and chapters, you
can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
command and you can use the `M-x Info-validate' command.

* Menu:

* makeinfo preferred::          `makeinfo' finds errors.
* Debugging with Info::         How to catch errors with Info formatting.
* Debugging with TeX::          How to catch errors with TeX formatting.
* Using texinfo-show-structure::  How to use `texinfo-show-structure'.
* Using occur::                 How to list all lines containing a pattern.
* Running Info-Validate::       How to find badly referenced nodes.


File: texi.info,  Node: makeinfo preferred,  Next: Debugging with Info,  Up: Catching Mistakes

`makeinfo' Find Errors
======================

   The `makeinfo' program does an excellent job of catching errors and
reporting them--far better than either the `texinfo-format-region' or
the `texinfo-format-buffer' command.  In addition, the various
functions for automatically creating and updating node pointers and
menus remove many opportunities for human error.

   If you can, use the updating commands to create and insert pointers
and menus.  These prevent many errors.  Then use `makeinfo' (or its
Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
to format your file and check for other errors.  This is the best way
to work with Texinfo.  But if you cannot use `makeinfo', or your
problem is very puzzling, then you may want to use the tools described
in this appendix.


File: texi.info,  Node: Debugging with Info,  Next: Debugging with TeX,  Prev: makeinfo preferred,  Up: Catching Mistakes

Catching Errors with Info Formatting
====================================

   After you have written part of a Texinfo file, you can use the
`texinfo-format-region' or the `makeinfo-region' command to see whether
the region formats properly.

   Most likely, however, you are reading this section because for some
reason you cannot use the `makeinfo-region' command; therefore, the
rest of this section presumes that you are using
`texinfo-format-region'.

   If you make a mistake with an @-command, `texinfo-format-region'
will stop processing at or after the error and display an error
message.  To see where in the buffer the error occurred, switch to the
`*Info Region*' buffer; the cursor will be in a position that is after
the location of the error.  Also, the text will not be formatted after
the place where the error occurred (or more precisely, where it was
detected).

   For example, if you accidentally end a menu with the command `@end
menus' with an `s' on the end, instead of with `@end menu', you will
see an error message that says:

     @end menus is not handled by texinfo

The cursor will stop at the point in the buffer where the error occurs,
or not long after it.  The buffer will look like this:

     ---------- Buffer: *Info Region* ----------
     * Menu:
     
     * Using texinfo-show-structure::  How to use
                                       `texinfo-show-structure'
                                       to catch mistakes.
     * Running Info-Validate::         How to check for
                                       unreferenced nodes.
     @end menus
     -!-
     ---------- Buffer: *Info Region* ----------

   The `texinfo-format-region' command sometimes provides slightly odd
error messages.  For example, the following cross reference fails to
format:

     (@xref{Catching Mistakes, for more info.)

In this case, `texinfo-format-region' detects the missing closing brace
but displays a message that says `Unbalanced parentheses' rather than
`Unbalanced braces'.  This is because the formatting command looks for
mismatches between braces as if they were parentheses.

   Sometimes `texinfo-format-region' fails to detect mistakes.  For
example, in the following, the closing brace is swapped with the
closing parenthesis:

     (@xref{Catching Mistakes), for more info.}

Formatting produces:
     (*Note for more info.: Catching Mistakes)

   The only way for you to detect this error is to realize that the
reference should have looked like this:

     (*Note Catching Mistakes::, for more info.)

   Incidentally, if you are reading this node in Info and type `f RET'
(`Info-follow-reference'), you will generate an error message that says:

     No such node: "Catching Mistakes) The only way ...

This is because Info perceives the example of the error as the first
cross reference in this node and if you type a RET immediately after
typing the Info `f' command, Info will attempt to go to the referenced
node.  If you type `f catch TAB RET', Info will complete the node name
of the correctly written example and take you to the `Catching
Mistakes' node.  (If you try this, you can return from the `Catching
Mistakes' node by typing `l' (`Info-last').)