[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texinfo.txi
|
From: |
Karl Berry |
|
Subject: |
texinfo ChangeLog doc/texinfo.txi |
|
Date: |
Wed, 17 Mar 2010 15:40:24 +0000 |
CVSROOT: /sources/texinfo
Module name: texinfo
Changes by: Karl Berry <karl> 10/03/17 15:40:24
Modified files:
. : ChangeLog
doc : texinfo.txi
Log message:
move Include Files appendix to a chapter of the main document
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1031&r2=1.1032
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.248&r2=1.249
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1031
retrieving revision 1.1032
diff -u -b -r1.1031 -r1.1032
--- ChangeLog 10 Mar 2010 00:56:40 -0000 1.1031
+++ ChangeLog 17 Mar 2010 15:40:23 -0000 1.1032
@@ -1,6 +1,14 @@
+2010-03-17 Karl Berry <address@hidden>
+
+ * doc/texinfo.txi (Include Files): move to near the end of the
+ main manual, instead of being an appendix. These days, include
+ files are an important feature. Remove @refill's.
+ (Catching Mistakes): rename chapter name to
+ match node name, since it is clearer.
+
2010-03-09 Karl Berry <address@hidden>
- * doc/texinfo.txi (Menu Location): Clarify that having the menu
+ * doc/texinfo.txi (Menu Location): clarify that having the menu
at the end is a convention, not a requirement.
2010-03-07 Karl Berry <address@hidden>
Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.248
retrieving revision 1.249
diff -u -b -r1.248 -r1.249
--- doc/texinfo.txi 10 Mar 2010 00:56:40 -0000 1.248
+++ doc/texinfo.txi 17 Mar 2010 15:40:23 -0000 1.249
@@ -1,5 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.248 2010/03/10 00:56:40 karl Exp $
address@hidden $Id: texinfo.txi,v 1.249 2010/03/17 15:40:23 karl Exp $
@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi
@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
@@ -158,6 +158,7 @@
* Conditionals:: Specifying text for only some output cases.
* Internationalization:: Supporting languages other than English.
* Defining New Texinfo Commands:: User-defined macros and aliases.
+* Include Files:: How to incorporate other Texinfo files.
* Hardcopy:: Output for paper, with @TeX{}.
* Creating and Installing Info Files:: Details on Info output.
* Generating HTML:: Details on HTML output.
@@ -165,9 +166,8 @@
* Command List:: All the Texinfo @@-commands.
* Tips:: Hints on how to write a Texinfo document.
* Sample Texinfo Files:: Complete examples, including full texts.
-* Include Files:: How to incorporate other Texinfo files.
* Headings:: How to write page headings and footings.
-* Catching Mistakes:: How to find formatting mistakes.
+* Catching Mistakes:: How to find mistakes in formatting.
* GNU Free Documentation License::Copying this manual.
* Command and Variable Index:: A menu containing commands and variables.
* General Index:: A menu covering many topics.
@@ -566,6 +566,17 @@
* alias:: Command aliases.
* definfoenclose:: Customized highlighting.
+Include Files
+
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
+* Sample Include File:: A sample outer file with included files
+ within it; and a sample included file.
+* Include Files Evolution:: How use of the @code{@@include} command
+ has changed over time.
+
Formatting and Printing Hardcopy
* Use TeX:: Use @TeX{} to format for hardcopy.
@@ -641,19 +652,6 @@
* Verbatim Copying License::
* All-permissive Copying License::
-GNU Free Documentation License
-
-Include Files
-
-* Using Include Files:: How to use the @code{@@include} command.
-* texinfo-multiple-files-update:: How to create and update nodes and
- menus when using included files.
-* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
-* Sample Include File:: A sample outer file with included files
- within it; and a sample included file.
-* Include Files Evolution:: How use of the @code{@@include} command
- has changed over time.
-
Page Headings
* Headings Introduced:: Conventions for using page headings.
@@ -661,7 +659,7 @@
* Heading Choice:: How to specify the type of page heading.
* Custom Headings:: How to create your own headings and footings.
-Formatting Mistakes
+Catching Mistakes
* makeinfo Preferred:: @code{makeinfo} finds errors.
* Debugging with Info:: How to catch errors with Info formatting.
@@ -4646,7 +4644,7 @@
@cindex Include files, and section levels
You can use @code{@@lowersections} to include text written as an outer
or standalone Texinfo file in another Texinfo file as an inner,
-included file. Typical usage looks like this:
+included file (@pxref{Include Files}). Typical usage looks like this:
@example
@@lowersections
@@ -14457,170 +14455,457 @@
indirectly.
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
address@hidden texindex
address@hidden Include Files
address@hidden Include Files
address@hidden Include files
-There are three major shell commands for making a printed manual from a
-Texinfo file: one for converting the Texinfo file into a file that will be
-printed, a second for sorting indices, and a third for printing the
-formatted document. When you use the shell commands, you can either
-work directly in the operating system shell or work within a shell
-inside GNU Emacs.
+When @TeX{} or an Info formatting command sees an @code{@@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.
-If you are using GNU Emacs, you can use commands provided by Texinfo
-mode instead of shell commands. In addition to the three commands to
-format a file, sort the indices, and print the result, Texinfo mode
-offers key bindings for commands to recenter the output buffer, show the
-print queue, and delete a job from the print queue.
+Include files let you keep a single large document as a collection of
+conveniently small parts.
@menu
-* Use TeX:: Use @TeX{} to format for hardcopy.
-* Format with tex/texindex:: How to format with explicit shell commands.
-* Format with texi2dvi:: A simpler way to format.
-* Print with lpr:: How to print.
-* Within Emacs:: How to format and print from an Emacs shell.
-* Texinfo Mode Printing:: How to format and print in Texinfo mode.
-* Compile-Command:: How to print using Emacs's compile command.
-* Requirements Summary:: @TeX{} formatting requirements summary.
-* Preparing for TeX:: What to do before you use @TeX{}.
-* Overfull hboxes:: What are and what to do with overfull hboxes.
-* smallbook:: How to print small format books and manuals.
-* A4 Paper:: How to print on A4 or A5 paper.
-* pagesizes:: How to print with customized page sizes.
-* Cropmarks and Magnification:: How to print marks to indicate the size
- of pages and how to print scaled up output.
-* PDF Output:: Portable Document Format output.
-* Obtaining TeX:: How to Obtain @TeX{}.
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
+* Sample Include File:: A sample outer file with included files
+ within it; and a sample included file.
+* Include Files Evolution:: How use of the @code{@@include} command
+ has changed over time.
@end menu
address@hidden Use TeX
address@hidden Use @TeX{}
-
-The typesetting program called @TeX{} is used for formatting a Texinfo
-file. @TeX{} is a very powerful typesetting program and, if used correctly,
-does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
address@hidden, for information on how to obtain @TeX{}.)
address@hidden Using Include Files
address@hidden How to Use Include Files
address@hidden include
-The standalone @code{makeinfo} program and Emacs functions
address@hidden and @code{texinfo-format-buffer} commands
-read the very same @@-commands in the Texinfo file as does @TeX{}, but
-process them differently to make an Info file (@pxref{Creating an Info
-File}).
+To include another file within a Texinfo file, write the
address@hidden@@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:
address@hidden
+@@include buffers.texi
address@hidden example
address@hidden Format with tex/texindex
address@hidden Format with @code{tex} and @code{texindex}
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
+The name of the file is taken literally, with a single exception:
address@hidden@@address@hidden@address@hidden references are expanded. This
makes it
+possible to reliably include files in other directories in a
+distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
+an example.
-You can format the Texinfo file with the shell command @code{tex}
-followed by the name of the Texinfo file. For example:
+An included file should simply be a segment of text that you expect to
+be included as is into the overall or @dfn{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 @samp{\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 @code{@@bye} command; nothing after @code{@@bye} is
+formatted.
address@hidden
-tex foo.texi
address@hidden example
+In the past, you were required to write an @code{@@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 @code{@@setfilename} line exists
+in an included file, it is ignored.
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
-files containing information for indices, cross references, etc. The
-DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
-any device (see the following sections).
+Conventionally, an included file begins with an @code{@@node} line that
+is followed by an @code{@@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 @code{@@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, @code{texinfo-multiple-files-update}, that is
+designed for @code{@@include} files.
address@hidden texindex
-The @code{tex} formatting command itself does not sort the indices; it
-writes an output file of unsorted index data. To generate a printed
-index after running the @command{tex} command, you first need a sorted
-index to work from. The @command{texindex} command sorts indices.
-(The source file @file{texindex.c} comes as part of the standard
-Texinfo distribution, among other places.) (@command{texi2dvi} runs
address@hidden and @command{texindex} as necessary.)
+When an included file does not have any node lines in it, the
+multiple files update command does not try to create a menu entry
+for it. Consequently, you can include any file, such as a
+version or an update file without node lines, not just files that
+are chapters. Small includable files like this are created by
+Automake (@pxref{GNU Sample Texts}).
address@hidden Names of index files
address@hidden Index file names
-The @code{tex} formatting command outputs unsorted index files under
-names that obey a standard convention: the name of your main input file
-with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
-Web2c}) extension removed, followed by the two letter names of indices.
-For example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
address@hidden, @file{foo.pg} and @file{foo.ky}. Those are exactly the
-arguments to give to @code{texindex}.
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
-Instead of specifying all the unsorted index file names explicitly, you
-can use @samp{??} as shell wildcards and give the command in this
-form:
address@hidden texinfo-multiple-files-update
address@hidden @code{texinfo-multiple-files-update}
address@hidden texinfo-multiple-files-update
address@hidden
-texindex foo.??
address@hidden example
+GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
+command. 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 @code{@@node} line of the
+included files or all of them:
address@hidden
-This command will run @code{texindex} on all the unsorted index files,
-including any that you have defined yourself using @code{@@defindex}
-or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
-even if there are similarly named files with two letter extensions
-that are not index files, such as @samp{foo.el}. The @code{texindex}
-command reports but otherwise ignores such files.)
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
+Called without any arguments:
-For each file specified, @code{texindex} generates a sorted index file
-whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
-(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
-raw index output file.
address@hidden @minus
address@hidden
+Create or update the `Next', `Previous', and `Up' pointers of the
+first @code{@@node} line in each file included in an outer or overall
+Texinfo file.
-After you have sorted the indices, you need to rerun @code{tex} on the
-Texinfo file. This regenerates the DVI file, this time with
-up-to-date index entries.
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall file.
-Finally, you may need to run @code{tex} one more time, to get the page
-numbers in the cross-references correct.
address@hidden
+Create or update a main menu in the outer file.
address@hidden itemize
-To summarize, this is a five step process:
address@hidden C-u M-x texinfo-multiple-files-update
+Called with @kbd{C-u} as a prefix argument:
address@hidden
address@hidden @minus{}
@item
-Run @code{tex} on your Texinfo file. This generates a DVI file (with
-undefined cross-references and no indices), and the raw index files
-(with two letter extensions).
+Create or update pointers in the first @code{@@node} line in each
+included file.
@item
-Run @code{texindex} on the raw index files. This creates the
-corresponding sorted index files (with three letter extensions).
+Create or update the `Top' level node pointers of the outer file.
@item
-Run @code{tex} again on your Texinfo file. This regenerates the DVI
-file, this time with indices and defined cross-references, but with page
-numbers for the cross-references from last time, generally incorrect.
+Create and insert a master menu in the outer file. The master menu
+is made from all the menus in all the included files.
address@hidden itemize
+
address@hidden C-u 8 M-x texinfo-multiple-files-update
+Called with a numeric prefix argument, such as @kbd{C-u 8}:
address@hidden @minus
@item
-Sort the indices again, with @code{texindex}.
+Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+of all the included files.
@item
-Run @code{tex} one last time. This time the correct page numbers are
-written for the cross-references.
address@hidden enumerate
+Create or update @strong{all} the menus of all the included
+files.
address@hidden texi2dvi
-Alternatively, it's a one-step process: run @code{texi2dvi}
-(@pxref{Format with texi2dvi}).
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall file.
-You need not run @code{texindex} each time after you run @code{tex}. If
-you do not, on the next run, the @code{tex} formatting command will use
-whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
address@hidden
+And then create a master menu in the outer file. This is similar to
+invoking @code{texinfo-master-menu} with an argument when you are
+working with just one file.
address@hidden itemize
address@hidden table
address@hidden Auxiliary files, avoiding
+Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
+with a numeric prefix argument, such as @kbd{C-u 8}, the command
+updates @strong{every} pointer and menu in @strong{all} the files and then
inserts a
+master menu.
+
+
address@hidden Include Files Requirements
address@hidden Include Files Requirements
address@hidden Include files requirements
address@hidden Requirements for include files
+
+If you plan to use the @code{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 @code{@@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, @code{@@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 @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
+one, and only one, chapter or equivalent-level node.
+
+The outer file should contain only @emph{one} node, the `Top' node. It
+should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
+them.
+
+
address@hidden Sample Include File
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
+
+Here is an example of an outer Texinfo file with @code{@@include} files
+within it before running @code{texinfo-multiple-files-update}, which
+would insert a main or master menu:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
+@@setfilename include-example.info
+@@settitle Include Example
address@hidden %**end of header
address@hidden group
+
+... @xref{Sample Texinfo Files}, for
+examples of the rest of the frontmatter ...
+
address@hidden
+@@ifnottex
+@@node Top
+@@top Include Example
+@@end ifnottex
address@hidden group
+
address@hidden
+@@include foo.texinfo
+@@include bar.texinfo
+@@include concept-index.texinfo
+@@bye
address@hidden group
address@hidden example
+
+An included file, such as @file{foo.texinfo}, might look like this:
+
address@hidden
address@hidden
+@@node First
+@@chapter First Chapter
+
+Contents of first chapter @dots{}
address@hidden group
address@hidden example
+
+The full contents of @file{concept-index.texinfo} might be as simple as this:
+
address@hidden
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden example
+
+The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
+Manual} is named @file{elisp.texi}. This outer file contains a master
+menu with 417 entries and a list of 41 @code{@@include}
+files.
+
+
address@hidden Include Files Evolution
address@hidden 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. (@xref{Other Info Files, , Referring to
+Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with 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
address@hidden@@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 @cite{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 @code{@@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.
+
+
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
address@hidden texindex
+
+There are three major shell commands for making a printed manual from a
+Texinfo file: one for converting the Texinfo file into a file that will be
+printed, a second for sorting indices, and a third for printing the
+formatted document. When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside GNU Emacs.
+
+If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands. In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
address@hidden
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with lpr:: How to print.
+* Within Emacs:: How to format and print from an Emacs shell.
+* Texinfo Mode Printing:: How to format and print in Texinfo mode.
+* Compile-Command:: How to print using Emacs's compile command.
+* Requirements Summary:: @TeX{} formatting requirements summary.
+* Preparing for TeX:: What to do before you use @TeX{}.
+* Overfull hboxes:: What are and what to do with overfull hboxes.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* pagesizes:: How to print with customized page sizes.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
+* PDF Output:: Portable Document Format output.
+* Obtaining TeX:: How to Obtain @TeX{}.
address@hidden menu
+
address@hidden Use TeX
address@hidden Use @TeX{}
+
+The typesetting program called @TeX{} is used for formatting a Texinfo
+file. @TeX{} is a very powerful typesetting program and, if used correctly,
+does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
address@hidden, for information on how to obtain @TeX{}.)
+
+The standalone @code{makeinfo} program and Emacs functions
address@hidden and @code{texinfo-format-buffer} commands
+read the very same @@-commands in the Texinfo file as does @TeX{}, but
+process them differently to make an Info file (@pxref{Creating an Info
+File}).
+
+
address@hidden Format with tex/texindex
address@hidden Format with @code{tex} and @code{texindex}
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
+
+You can format the Texinfo file with the shell command @code{tex}
+followed by the name of the Texinfo file. For example:
+
address@hidden
+tex foo.texi
address@hidden example
+
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+files containing information for indices, cross references, etc. The
+DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
+any device (see the following sections).
+
address@hidden texindex
+The @code{tex} formatting command itself does not sort the indices; it
+writes an output file of unsorted index data. To generate a printed
+index after running the @command{tex} command, you first need a sorted
+index to work from. The @command{texindex} command sorts indices.
+(The source file @file{texindex.c} comes as part of the standard
+Texinfo distribution, among other places.) (@command{texi2dvi} runs
address@hidden and @command{texindex} as necessary.)
+
address@hidden Names of index files
address@hidden Index file names
+The @code{tex} formatting command outputs unsorted index files under
+names that obey a standard convention: the name of your main input file
+with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
+Web2c}) extension removed, followed by the two letter names of indices.
+For example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
address@hidden, @file{foo.pg} and @file{foo.ky}. Those are exactly the
+arguments to give to @code{texindex}.
+
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
+Instead of specifying all the unsorted index file names explicitly, you
+can use @samp{??} as shell wildcards and give the command in this
+form:
+
address@hidden
+texindex foo.??
address@hidden example
+
address@hidden
+This command will run @code{texindex} on all the unsorted index files,
+including any that you have defined yourself using @code{@@defindex}
+or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
+even if there are similarly named files with two letter extensions
+that are not index files, such as @samp{foo.el}. The @code{texindex}
+command reports but otherwise ignores such files.)
+
+For each file specified, @code{texindex} generates a sorted index file
+whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
+(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
+raw index output file.
+
+After you have sorted the indices, you need to rerun @code{tex} on the
+Texinfo file. This regenerates the DVI file, this time with
+up-to-date index entries.
+
+Finally, you may need to run @code{tex} one more time, to get the page
+numbers in the cross-references correct.
+
+To summarize, this is a five step process:
+
address@hidden
address@hidden
+Run @code{tex} on your Texinfo file. This generates a DVI file (with
+undefined cross-references and no indices), and the raw index files
+(with two letter extensions).
+
address@hidden
+Run @code{texindex} on the raw index files. This creates the
+corresponding sorted index files (with three letter extensions).
+
address@hidden
+Run @code{tex} again on your Texinfo file. This regenerates the DVI
+file, this time with indices and defined cross-references, but with page
+numbers for the cross-references from last time, generally incorrect.
+
address@hidden
+Sort the indices again, with @code{texindex}.
+
address@hidden
+Run @code{tex} one last time. This time the correct page numbers are
+written for the cross-references.
address@hidden enumerate
+
address@hidden texi2dvi
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with texi2dvi}).
+
+You need not run @code{texindex} each time after you run @code{tex}. If
+you do not, on the next run, the @code{tex} formatting command will use
+whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
+
address@hidden Auxiliary files, avoiding
@findex novalidate
@cindex Pointer validation, suppressing
@cindex Chapters, formatting one at a time
@@ -19041,792 +19326,505 @@
hyphens to two.
@end itemize
address@hidden Periods Outside of Quotes
-
-Place periods and other punctuation marks @emph{outside} of quotations,
-unless the punctuation is part of the quotation. This practice goes
-against publishing conventions in the United States, 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:
-
address@hidden
-Evidently, @samp{au} is an abbreviation for ``author''.
address@hidden example
-
address@hidden
-since @samp{au} does @emph{not} serve as an abbreviation for
address@hidden (with a period following the word).
-
address@hidden Introducing New Terms
-
address@hidden @bullet
address@hidden
-Introduce new terms so that a reader 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.
-
address@hidden
-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.
address@hidden quotation
-
address@hidden
-Use the @code{@@dfn} command around a word being introduced, to indicate
-that the reader should not expect to know the meaning already, and
-should expect to learn the meaning from this passage.
address@hidden itemize
-
address@hidden @@pxref
-
address@hidden !!! maybe include this in the tips on pxref
address@hidden
-By the way, it is okay to use pxref with something else in front of
-it within the parens, as long as the pxref is followed by the close
-paren, and the material inside the parens is not part of a larger
-sentence. Also, you can use xref inside parens as part of a complete
-sentence so long as you terminate the cross reference with punctuation.
address@hidden ignore
-Absolutely never use @code{@@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.
-
address@hidden Invoking from a Shell
-
-You can invoke programs such as Emacs, GCC, and @code{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, they are difficult for users to find.
-
-So, there is a convention to name such sections with a phrase beginning
-with the word `Invoking', as in `Invoking Emacs'; this way, users can
-find the section easily.
-
-
address@hidden ANSI C Syntax
-
-When you use @code{@@example} to describe a C function's calling
-conventions, use the ANSI C syntax, like this:@refill
-
address@hidden
-void dld_init (char *@@address@hidden@});
address@hidden example
-
address@hidden
-And in the subsequent discussion, refer to the argument values by
-writing the same argument names, again highlighted with
address@hidden@@address@hidden
-
address@hidden 800
-Avoid the obsolete style that looks like this:@refill
-
address@hidden
-#include <dld.h>
-
-dld_init (path)
-char *path;
address@hidden example
-
-Also, it is best to avoid writing @code{#include} above the
-declaration just to indicate that the function is declared in a
-header file. The practice may give the misimpression that the
address@hidden 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 address@hidden
-
address@hidden Bad Examples
-
-Here are several examples of bad writing to avoid:
-
-In this example, say, `` @dots{} you must @code{@@address@hidden
address@hidden the new version.'' That flows better.
-
address@hidden
-When you are done editing the file, you must perform a
address@hidden@@address@hidden address@hidden
address@hidden quotation
-
-In the following example, say, address@hidden makes a unified interface such
as VC
-mode possible.''
-
address@hidden
-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).
address@hidden quotation
-
-And in this example, you should specify what `it' refers to:
-
address@hidden
-If you are working with other people, it assists in coordinating
-everyone's changes so they do not step on each other.
address@hidden quotation
-
address@hidden And Finally @dots{}
-
address@hidden @bullet
address@hidden
-Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
-sound in the name `Bach'. But pronounce Texinfo as in `speck':
-``teckinfo''.
-
address@hidden
-Write notes for yourself at the very end of a Texinfo file after the
address@hidden@@bye}. None of the formatters process text after the
address@hidden@@bye}; it is as if the text were within @code{@@ignore} @dots{}
address@hidden@@end ignore}.
address@hidden itemize
-
-
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo files
-
-The first example is from the first chapter (@pxref{Short Sample}),
-given here in its entirety, without commentary. The second
-includes the full texts to be used in GNU manuals.
-
address@hidden
-* Short Sample Texinfo File::
-* GNU Sample Texts::
-* Verbatim Copying License::
-* All-permissive Copying License::
address@hidden menu
-
-
address@hidden Short Sample Texinfo File
address@hidden Short Sample
address@hidden Sample Texinfo file, no comments
-
-Here is a complete, short sample Texinfo file, without any commentary.
-You can see this file, with comments, in the first chapter. @xref{Short
-Sample}.
-
-In a nutshell: The @command{makeinfo} program transforms a Texinfo
-source file such as this into an Info file or HTML; and @TeX{} typesets
-it for a printed manual.
-
-
address@hidden 1
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename sample.info
-@@settitle Sample Manual 1.0
-@@c %**end of header
-
-@@copying
-This is a short example of a complete Texinfo file.
-
-Copyright @@address@hidden@} 2009 Free Software Foundation, Inc.
-@@end copying
-
-@@titlepage
-@@title Sample Title
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
-@@end titlepage
-
-@@c Output the table of the contents at the beginning.
-@@contents
-
-@@ifnottex
-@@node Top
-@@top GNU Sample
-
-@@insertcopying
-@@end ifnottex
-
-@@menu
-* First Chapter:: The first chapter is the
- only chapter in this sample.
-* Index:: Complete index.
-@@end menu
-
-
-@@node First Chapter
-@@chapter First Chapter
-
-@@cindex chapter, first
-
-This is the first chapter.
-@@cindex index entry, another
-
-Here is a numbered list.
-
-@@enumerate
-@@item
-This is the first item.
-
-@@item
-This is the second item.
-@@end enumerate
-
-
-@@node Index
-@@unnumbered Index
-
-@@printindex cp
-
-@@bye
address@hidden example
-
-
address@hidden GNU Sample Texts
address@hidden GNU Sample Texts
address@hidden Periods Outside of Quotes
address@hidden GNU sample texts
address@hidden Sample texts, GNU
address@hidden Full texts, GNU
+Place periods and other punctuation marks @emph{outside} of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
-Following is a sample Texinfo document with the full texts that should
-be used (adapted as necessary) in GNU manuals.
+For example, you should write the following sentence with the period
+outside the end quotation marks:
-As well as the legal texts, it also serves as a practical example of how
-many elements in a GNU system can affect the manual. If you're not
-familiar with all these different elements, don't worry. They're not
-required and a perfectly good manual can be written without them.
-They're included here nonetheless because many manuals do (or could)
-benefit from them.
address@hidden
+Evidently, @samp{au} is an abbreviation for ``author''.
address@hidden example
address@hidden Sample}, for a minimal example of a Texinfo file.
address@hidden a File}, for a full explanation of that minimal
-example.
address@hidden
+since @samp{au} does @emph{not} serve as an abbreviation for
address@hidden (with a period following the word).
-Here are some notes on the example:
address@hidden Introducing New Terms
@itemize @bullet
@item
address@hidden $Id
address@hidden CVS $Id
address@hidden RCS $Id
address@hidden Documentation identification
address@hidden Identification of documentation
-The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
-Concurrent Versions System}) or RCS
-(@url{http://www.gnu.org/software/rcs}) version control systems, which
-expand it into a string such as:
address@hidden
-$Id: texinfo.txi,v 1.248 2010/03/10 00:56:40 karl Exp $
address@hidden example
-(This is useful in all sources that use version control, not just manuals.)
-You may wish to include the @samp{$Id:} comment in the @code{@@copying}
-text, if you want a completely unambiguous reference to the
-documentation version.
+Introduce new terms so that a reader who does not know them can
+understand them from context; or write a definition for the term.
-If you want to literally write @address@hidden, use @code{@@w}:
address@hidden@@address@hidden@}Id$}. Unfortunately, this technique does not
work in
-plain text output, where it's not clear what should be done.
+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.
address@hidden
address@hidden address@hidden, and version info}
address@hidden UPDATED @r{Automake variable}
address@hidden VERSION @r{Automake variable}
address@hidden time-stamp.el
-The @file{version.texi} in the @code{@@include} command is maintained
-automatically by Automake (@pxref{Top,, Introduction, automake, GNU
-Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
-elsewhere. If your distribution doesn't use Automake, but you do use
-Emacs, you may find the time-stamp.el package helpful (@pxref{Time
-Stamps,,,emacs,The GNU Emacs Manual}).
address@hidden
+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.
address@hidden quotation
@item
-The @code{@@syncodeindex} command reflects the recommendation to use
-only one index where possible, to make it easier for readers to look up
-index entries.
+Use the @code{@@dfn} command around a word being introduced, to indicate
+that the reader should not expect to know the meaning already, and
+should expect to learn the meaning from this passage.
address@hidden itemize
address@hidden
-The @code{@@dircategory} is for constructing the Info directory.
address@hidden Dir Entries}, which includes a variety of recommended
-category names.
address@hidden @@pxref
address@hidden
-The `Invoking' node is a GNU standard to help users find the basic
-information about command-line usage of a given program. @xref{Manual
-Structure Details,,,standards, GNU Coding Standards}.
address@hidden !!! maybe include this in the tips on pxref
address@hidden
+By the way, it is okay to use pxref with something else in front of
+it within the parens, as long as the pxref is followed by the close
+paren, and the material inside the parens is not part of a larger
+sentence. Also, you can use xref inside parens as part of a complete
+sentence so long as you terminate the cross reference with punctuation.
address@hidden ignore
+Absolutely never use @code{@@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.
address@hidden
address@hidden GNU Free Documentation License, including entire
address@hidden Free Documentation License, including entire
-It is best to include the entire GNU Free Documentation License in a GNU
-manual, unless the manual is only a few pages long. Of course this
-sample is even shorter than that, but it includes the FDL anyway in
-order to show one conventional way to do so. The @file{fdl.texi} file
-is available on the GNU machines and in the Texinfo and other GNU
-source distributions.
address@hidden Invoking from a Shell
-The FDL provides for omitting itself under certain conditions, but in
-that case the sample texts given here have to be modified. @xref{GNU
-Free Documentation License}.
+You can invoke programs such as Emacs, GCC, and @code{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, they are difficult for users to find.
address@hidden
-If the FSF is not the copyright holder, then use the appropriate name.
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking Emacs'; this way, users can
+find the section easily.
address@hidden
-If your manual is not published on paper by the FSF, then definitely
-omit the last sentence in the Back-Cover Text that talks about copies
-from GNU Press.
address@hidden
-GNU packages can entirely omit both cover texts if it is not published
-on paper by the FSF, at the package maintainer's discretion.
address@hidden ANSI C Syntax
address@hidden
-If your manual has Invariant Sections (again, see the license itself
-for details), then change the text here accordingly.
+When you use @code{@@example} to describe a C function's calling
+conventions, use the ANSI C syntax, like this:@refill
address@hidden
-For documents that express your personal views, feelings or experiences,
-it is more appropriate to use a license permitting only verbatim
-copying, rather than the FDL. @xref{Verbatim Copying License}.
address@hidden
+void dld_init (char *@@address@hidden@});
address@hidden example
address@hidden itemize
address@hidden
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with
address@hidden@@address@hidden
-Here is the sample document:
address@hidden 800
+Avoid the obsolete style that looks like this:@refill
address@hidden
-\input texinfo @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.248 2010/03/10 00:56:40 karl Exp $
address@hidden %**start of header
address@hidden sample.info
address@hidden version.texi
address@hidden GNU Sample @value{VERSION}
address@hidden pg cp
address@hidden %**end of header
address@hidden
-This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
-which is an example in the Texinfo documentation.
address@hidden
+#include <dld.h>
-Copyright @copyright{} 2009 Free Software Foundation, Inc.
+dld_init (path)
+char *path;
address@hidden example
address@hidden
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License.''
+Also, it is best to avoid writing @code{#include} above the
+declaration just to indicate that the function is declared in a
+header file. The practice may give the misimpression that the
address@hidden 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 address@hidden
-(a) The FSF's Back-Cover Text is: ``You have the freedom to
-copy and modify this GNU manual. Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
address@hidden Bad Examples
+
+Here are several examples of bad writing to avoid:
+
+In this example, say, `` @dots{} you must @code{@@address@hidden
address@hidden the new version.'' That flows better.
+
address@hidden
+When you are done editing the file, you must perform a
address@hidden@@address@hidden address@hidden
@end quotation
address@hidden copying
address@hidden Texinfo documentation system
address@hidden
-* sample: (sample)Invoking sample.
address@hidden direntry
+In the following example, say, address@hidden makes a unified interface such
as VC
+mode possible.''
address@hidden
address@hidden GNU Sample
address@hidden for version @value{VERSION}, @value{UPDATED}
address@hidden A.U. Thor (@email{bug-texinfo@@gnu.org})
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
address@hidden
+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).
address@hidden quotation
address@hidden
+And in this example, you should specify what `it' refers to:
address@hidden
address@hidden Top
address@hidden GNU Sample
address@hidden
+If you are working with other people, it assists in coordinating
+everyone's changes so they do not step on each other.
address@hidden quotation
-This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
address@hidden ifnottex
address@hidden And Finally @dots{}
address@hidden
-* Invoking sample::
-* Copying This Manual::
-* Index::
address@hidden menu
address@hidden @bullet
address@hidden
+Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
+sound in the name `Bach'. But pronounce Texinfo as in `speck':
+``teckinfo''.
address@hidden
+Write notes for yourself at the very end of a Texinfo file after the
address@hidden@@bye}. None of the formatters process text after the
address@hidden@@bye}; it is as if the text were within @code{@@ignore} @dots{}
address@hidden@@end ignore}.
address@hidden itemize
address@hidden Invoking sample
address@hidden Invoking sample
address@hidden sample
address@hidden invoking @command{sample}
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo files
-This is a sample manual. There is no sample program to
-invoke, but if there was, you could see its basic usage
-and command line options here.
+The first example is from the first chapter (@pxref{Short Sample}),
+given here in its entirety, without commentary. The second
+includes the full texts to be used in GNU manuals.
address@hidden
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
address@hidden menu
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden fdl.texi
address@hidden Short Sample Texinfo File
address@hidden Short Sample
address@hidden Sample Texinfo file, no comments
+Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter. @xref{Short
+Sample}.
address@hidden Index
address@hidden Index
+In a nutshell: The @command{makeinfo} program transforms a Texinfo
+source file such as this into an Info file or HTML; and @TeX{} typesets
+it for a printed manual.
address@hidden cp
address@hidden
address@hidden verbatim
address@hidden 1
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+@@copying
+This is a short example of a complete Texinfo file.
address@hidden Verbatim Copying License
address@hidden Verbatim Copying License
+Copyright @@address@hidden@} 2009 Free Software Foundation, Inc.
+@@end copying
address@hidden Verbatim copying license
address@hidden License for verbatim copying
+@@titlepage
+@@title Sample Title
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
-For software manuals and other documentation, it is important to use a
-license permitting free redistribution and updating, so that when a free
-program is changed, the documentation can be updated as well.
+@@c Output the table of the contents at the beginning.
+@@contents
-On the other hand, for documents that express your personal views,
-feelings or experiences, it is more appropriate to use a license
-permitting only verbatim copying.
+@@ifnottex
+@@node Top
+@@top GNU Sample
-Here is sample text for such a license permitting verbatim copying only.
-This is just the license text itself. For a complete sample document,
-see the previous sections.
+@@insertcopying
+@@end ifnottex
address@hidden
address@hidden
-This document is a sample for allowing verbatim copying only.
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
-Copyright @copyright{} 2009 Free Software Foundation, Inc.
address@hidden
-Permission is granted to make and distribute verbatim copies
-of this entire document without royalty provided the
-copyright notice and this permission notice are preserved.
address@hidden quotation
address@hidden copying
address@hidden verbatim
+@@node First Chapter
+@@chapter First Chapter
+@@cindex chapter, first
address@hidden All-permissive Copying License
address@hidden All-permissive Copying License
+This is the first chapter.
+@@cindex index entry, another
address@hidden All-permissive copying license
address@hidden License for all-permissive copying
+Here is a numbered list.
-For software manuals and other documentation, it is important to use a
-license permitting free redistribution and updating, so that when a free
-program is changed, the documentation can be updated as well.
+@@enumerate
+@@item
+This is the first item.
-On the other hand, for small supporting files, short manuals (under 300
-lines long) and rough documentation (README files, INSTALL files, etc.),
-the full FDL would be overkill. They can use a simple all-permissive
-license.
+@@item
+This is the second item.
+@@end enumerate
-Here is sample text for such an all-permissive license. This is just
-the license text itself. For a complete sample document, see the
-previous sections.
address@hidden
-Copyright @@address@hidden@} 2009 Free Software Foundation, Inc.
+@@node Index
+@@unnumbered Index
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
+@@printindex cp
+
+@@bye
@end example
address@hidden Include Files
address@hidden Include Files
address@hidden Include files
address@hidden GNU Sample Texts
address@hidden GNU Sample Texts
-When @TeX{} or an Info formatting command sees an @code{@@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.
address@hidden GNU sample texts
address@hidden Sample texts, GNU
address@hidden Full texts, GNU
-Include files let you keep a single large document as a collection of
-conveniently small parts.
+Following is a sample Texinfo document with the full texts that should
+be used (adapted as necessary) in GNU manuals.
address@hidden
-* Using Include Files:: How to use the @code{@@include} command.
-* texinfo-multiple-files-update:: How to create and update nodes and
- menus when using included files.
-* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
-* Sample Include File:: A sample outer file with included files
- within it; and a sample included file.
-* Include Files Evolution:: How use of the @code{@@include} command
- has changed over time.
address@hidden menu
+As well as the legal texts, it also serves as a practical example of how
+many elements in a GNU system can affect the manual. If you're not
+familiar with all these different elements, don't worry. They're not
+required and a perfectly good manual can be written without them.
+They're included here nonetheless because many manuals do (or could)
+benefit from them.
address@hidden Using Include Files
address@hidden How to Use Include Files
address@hidden include
address@hidden Sample}, for a minimal example of a Texinfo file.
address@hidden a File}, for a full explanation of that minimal
+example.
-To include another file within a Texinfo file, write the
address@hidden@@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:
+Here are some notes on the example:
address@hidden @bullet
address@hidden
address@hidden $Id
address@hidden CVS $Id
address@hidden RCS $Id
address@hidden Documentation identification
address@hidden Identification of documentation
+The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
+Concurrent Versions System}) or RCS
+(@url{http://www.gnu.org/software/rcs}) version control systems, which
+expand it into a string such as:
@example
-@@include buffers.texi
+$Id: texinfo.txi,v 1.249 2010/03/17 15:40:23 karl Exp $
@end example
+(This is useful in all sources that use version control, not just manuals.)
+You may wish to include the @samp{$Id:} comment in the @code{@@copying}
+text, if you want a completely unambiguous reference to the
+documentation version.
-The name of the file is taken literally, with a single exception:
address@hidden@@address@hidden@address@hidden references are expanded. This
makes it
-possible to reliably include files in other directories in a
-distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
-an example.
-
-An included file should simply be a segment of text that you expect to
-be included as is into the overall or @dfn{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 @samp{\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 @code{@@bye} command; nothing after @code{@@bye} is
-formatted.
-
-In the past, you were required to write an @code{@@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 @code{@@setfilename} line exists
-in an included file, it is address@hidden
+If you want to literally write @address@hidden, use @code{@@w}:
address@hidden@@address@hidden@}Id$}. Unfortunately, this technique does not
work in
+plain text output, where it's not clear what should be done.
-Conventionally, an included file begins with an @code{@@node} line that
-is followed by an @code{@@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 @code{@@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, @code{texinfo-multiple-files-update}, that is
-designed for @code{@@include} address@hidden
address@hidden
address@hidden address@hidden, and version info}
address@hidden UPDATED @r{Automake variable}
address@hidden VERSION @r{Automake variable}
address@hidden time-stamp.el
+The @file{version.texi} in the @code{@@include} command is maintained
+automatically by Automake (@pxref{Top,, Introduction, automake, GNU
+Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
+elsewhere. If your distribution doesn't use Automake, but you do use
+Emacs, you may find the time-stamp.el package helpful (@pxref{Time
+Stamps,,,emacs,The GNU Emacs Manual}).
-When an included file does not have any node lines in it, the
-multiple files update command does not try to create a menu entry
-for it. Consequently, you can include any file, such as a
-version or an update file without node lines, not just files that
-are chapters. Small includable files like this are created by
-Automake (@pxref{GNU Sample Texts}).
address@hidden
+The @code{@@syncodeindex} command reflects the recommendation to use
+only one index where possible, to make it easier for readers to look up
+index entries.
address@hidden
+The @code{@@dircategory} is for constructing the Info directory.
address@hidden Dir Entries}, which includes a variety of recommended
+category names.
address@hidden texinfo-multiple-files-update
address@hidden @code{texinfo-multiple-files-update}
address@hidden texinfo-multiple-files-update
address@hidden
+The `Invoking' node is a GNU standard to help users find the basic
+information about command-line usage of a given program. @xref{Manual
+Structure Details,,,standards, GNU Coding Standards}.
-GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
-command. 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 @code{@@node} line of the
-included files or all of them:@refill
address@hidden
address@hidden GNU Free Documentation License, including entire
address@hidden Free Documentation License, including entire
+It is best to include the entire GNU Free Documentation License in a GNU
+manual, unless the manual is only a few pages long. Of course this
+sample is even shorter than that, but it includes the FDL anyway in
+order to show one conventional way to do so. The @file{fdl.texi} file
+is available on the GNU machines and in the Texinfo and other GNU
+source distributions.
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
-Called without any arguments:@refill
+The FDL provides for omitting itself under certain conditions, but in
+that case the sample texts given here have to be modified. @xref{GNU
+Free Documentation License}.
address@hidden @minus
@item
-Create or update the `Next', `Previous', and `Up' pointers of the
-first @code{@@node} line in each file included in an outer or overall
-Texinfo address@hidden
+If the FSF is not the copyright holder, then use the appropriate name.
@item
-Create or update the `Top' level node pointers of the outer or
-overall address@hidden
+If your manual is not published on paper by the FSF, then definitely
+omit the last sentence in the Back-Cover Text that talks about copies
+from GNU Press.
@item
-Create or update a main menu in the outer address@hidden
address@hidden itemize
-
address@hidden C-u M-x texinfo-multiple-files-update
-Called with @kbd{C-u} as a prefix argument:
+GNU packages can entirely omit both cover texts if it is not published
+on paper by the FSF, at the package maintainer's discretion.
address@hidden @minus{}
@item
-Create or update pointers in the first @code{@@node} line in each
-included file.
+If your manual has Invariant Sections (again, see the license itself
+for details), then change the text here accordingly.
@item
-Create or update the `Top' level node pointers of the outer file.
+For documents that express your personal views, feelings or experiences,
+it is more appropriate to use a license permitting only verbatim
+copying, rather than the FDL. @xref{Verbatim Copying License}.
address@hidden
-Create and insert a master menu in the outer file. The master menu
-is made from all the menus in all the included address@hidden
@end itemize
address@hidden C-u 8 M-x texinfo-multiple-files-update
-Called with a numeric prefix argument, such as @kbd{C-u 8}:
+Here is the sample document:
address@hidden @minus
address@hidden
-Create or update @strong{all} the `Next', `Previous', and `Up' pointers
-of all the included address@hidden
address@hidden
+\input texinfo @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.249 2010/03/17 15:40:23 karl Exp $
address@hidden %**start of header
address@hidden sample.info
address@hidden version.texi
address@hidden GNU Sample @value{VERSION}
address@hidden pg cp
address@hidden %**end of header
address@hidden
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
+which is an example in the Texinfo documentation.
address@hidden
-Create or update @strong{all} the menus of all the included
address@hidden
+Copyright @copyright{} 2009 Free Software Foundation, Inc.
address@hidden
-Create or update the `Top' level node pointers of the outer or
-overall address@hidden
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
address@hidden
-And then create a master menu in the outer file. This is similar to
-invoking @code{texinfo-master-menu} with an argument when you are
-working with just one address@hidden
address@hidden itemize
address@hidden table
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual. Buying copies from the FSF
+supports it in developing GNU and promoting software freedom.''
address@hidden quotation
address@hidden copying
-Note the use of the prefix argument in interactive use: with a regular
-prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
-with a numeric prefix argument, such as @kbd{C-u 8}, the command
-updates @strong{every} pointer and menu in @strong{all} the files and then
inserts a
-master address@hidden
address@hidden Texinfo documentation system
address@hidden
+* sample: (sample)Invoking sample.
address@hidden direntry
address@hidden
address@hidden GNU Sample
address@hidden for version @value{VERSION}, @value{UPDATED}
address@hidden A.U. Thor (@email{bug-texinfo@@gnu.org})
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
address@hidden Include Files Requirements
address@hidden Include Files Requirements
address@hidden Include files requirements
address@hidden Requirements for include files
address@hidden
-If you plan to use the @code{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 @code{@@include} commands listing the included files. It
-should not even include indices, which should be listed in an included
-file of their address@hidden
address@hidden
address@hidden Top
address@hidden GNU Sample
-Moreover, each of the included files must contain exactly one highest
-level node (conventionally, @code{@@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 @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
-one, and only one, chapter or equivalent-level address@hidden
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
address@hidden ifnottex
-The outer file should contain only @emph{one} node, the `Top' node. It
-should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
address@hidden
address@hidden
+* Invoking sample::
+* Copying This Manual::
+* Index::
address@hidden menu
address@hidden Sample Include File
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
address@hidden Invoking sample
address@hidden Invoking sample
-Here is an example of an outer Texinfo file with @code{@@include} files
-within it before running @code{texinfo-multiple-files-update}, which
-would insert a main or master menu:
address@hidden sample
address@hidden invoking @command{sample}
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
-@@setfilename include-example.info
-@@settitle Include Example
address@hidden %**end of header
address@hidden group
+This is a sample manual. There is no sample program to
+invoke, but if there was, you could see its basic usage
+and command line options here.
-... @xref{Sample Texinfo Files}, for
-examples of the rest of the frontmatter ...
address@hidden
-@@ifnottex
-@@node Top
-@@top Include Example
-@@end ifnottex
address@hidden group
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden
-@@include foo.texinfo
-@@include bar.texinfo
-@@include concept-index.texinfo
-@@bye
address@hidden group
address@hidden example
address@hidden fdl.texi
-An included file, such as @file{foo.texinfo}, might look like this:
address@hidden
address@hidden
-@@node First
-@@chapter First Chapter
address@hidden Index
address@hidden Index
-Contents of first chapter @dots{}
address@hidden group
address@hidden example
address@hidden cp
-The full contents of @file{concept-index.texinfo} might be as simple as this:
address@hidden
address@hidden verbatim
address@hidden
address@hidden
-@@node Concept Index
-@@unnumbered Concept Index
-@@printindex cp
address@hidden group
address@hidden example
address@hidden Verbatim Copying License
address@hidden Verbatim Copying License
-The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
-Manual} is named @file{elisp.texi}. This outer file contains a master
-menu with 417 entries and a list of 41 @code{@@include}
-files.
address@hidden Verbatim copying license
address@hidden License for verbatim copying
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
address@hidden Include Files Evolution
address@hidden Evolution of Include Files
+On the other hand, for documents that express your personal views,
+feelings or experiences, it is more appropriate to use a license
+permitting only verbatim copying.
-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 address@hidden
+Here is sample text for such a license permitting verbatim copying only.
+This is just the license text itself. For a complete sample document,
+see the previous sections.
-References from one file to another were made by referring to the file
-name as well as the node name. (@xref{Other Info Files, , Referring to
-Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with Four and Five Arguments}.)@refill
address@hidden
address@hidden
+This document is a sample for allowing verbatim copying only.
-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
address@hidden@@setfilename} line.)@refill
+Copyright @copyright{} 2009 Free Software Foundation, Inc.
-However, because large Info files are now split automatically, it is
-no longer necessary to keep them address@hidden
address@hidden
+Permission is granted to make and distribute verbatim copies
+of this entire document without royalty provided the
+copyright notice and this permission notice are preserved.
address@hidden quotation
address@hidden copying
address@hidden verbatim
-Nowadays, multiple Texinfo files are used mostly for large documents,
-such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
-in which several different people write different sections of a
-document address@hidden
-In addition, the Info formatting commands have been extended to work
-with the @code{@@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 address@hidden
address@hidden All-permissive Copying License
address@hidden All-permissive Copying License
+
address@hidden All-permissive copying license
address@hidden License for all-permissive copying
+
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+On the other hand, for small supporting files, short manuals (under 300
+lines long) and rough documentation (README files, INSTALL files, etc.),
+the full FDL would be overkill. They can use a simple all-permissive
+license.
+
+Here is sample text for such an all-permissive license. This is just
+the license text itself. For a complete sample document, see the
+previous sections.
+
address@hidden
+Copyright @@address@hidden@} 2009 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
address@hidden example
@node Headings
@@ -20182,7 +20180,7 @@
@node Catching Mistakes
address@hidden Formatting Mistakes
address@hidden Catching Mistakes
@cindex Structure, catching mistakes in
@cindex Nodes, catching mistakes
@cindex Catching mistakes