+++ /dev/null
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
-
-INFO-DIR-SECTION Texinfo documentation system
-START-INFO-DIR-ENTRY
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
-* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
-END-INFO-DIR-ENTRY
-
- This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
-
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
-Foundation, Inc.
-
- This edition is for Texinfo version 3.12.
-
- 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.
-
-\1f
-File: texinfo.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.
-
- * 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 concept index
- entry, or else consistently use lower case. Terse entries often
- call for lower case; longer entries for capitalization. Whichever
- case convention you use, please use one or the other consistently!
- 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.
- Always use the appropriate case for case-sensitive names, such as
- those in C or Lisp.
-
- * 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 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:
-
- 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 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.
-
- 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 reader 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'.
-
-\1f
-File: texinfo.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)
- @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
-
-\1f
-File: texinfo.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:
-(xemacs)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.
-
-\1f
-File: texinfo.info, Node: Inserting Permissions, Next: ifinfo Permissions, Prev: Sample 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.
-
-\1f
-File: texinfo.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 1998 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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Prev: Include Files, 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.
-
-\1f
-File: texinfo.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 the `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 `@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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.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{} 1998 Free Software Foundation, Inc.
- @end titlepage
-
- @ifinfo
- @node Top, First, , (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 XEmacs Lisp Reference Manual'
-is named `elisp.texi'. This outer file contains a master menu with 417
-entries and a list of 41 `@include' files.
-
-\1f
-File: texinfo.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 XEmacs 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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.info, Node: Headings Introduced, Next: Heading Format, Prev: Headings, 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. Typically, you will use 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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.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. By default, Texinfo has no footers, so if you specify them,
-the available page size for the main text will be slightly reduced.
-
- 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 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.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.info, Node: makeinfo Preferred, Next: Debugging with Info, Prev: Catching Mistakes, Up: Catching Mistakes
-
-`makeinfo' Find Errors
-======================
-
- The `makeinfo' program does an excellent job of catching errors and
-reporting them--far better than `texinfo-format-region' or
-`texinfo-format-buffer'. 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.
-
-\1f
-File: texinfo.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 have made 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').)
-
projects / chise / xemacs-chise.git.1 / blobdiff