1211 lines
46 KiB
Plaintext
1211 lines
46 KiB
Plaintext
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').)
|
||
|