diff options
Diffstat (limited to 'gnu/usr.bin/texinfo/info-files/texi.info-9')
| -rw-r--r-- | gnu/usr.bin/texinfo/info-files/texi.info-9 | 1210 |
1 files changed, 1210 insertions, 0 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-9 b/gnu/usr.bin/texinfo/info-files/texi.info-9 new file mode 100644 index 0000000..b128db5 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-9 @@ -0,0 +1,1210 @@ +This is Info file texi.info, produced by Makeinfo-1.55 from the input +file texi.texi. + + This file documents Texinfo, a documentation system that uses a +single source file to produce both on-line information and a printed +manual. + + Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, +Inc. + + This is the second edition of the Texinfo documentation, +and is consistent with version 2 of `texinfo.tex'. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + + +File: texi.info, Node: Tips, Next: Sample Texinfo File, Prev: Command List, Up: Top + +Tips and Hints +************** + + Here are some tips for writing Texinfo documentation: + + * Write in the present tense, not in the past or the future. + + * Write actively! For example, write "We recommend that ..." rather + than "It is recommended that ...". + + * Use 70 or 72 as your fill column. Longer lines are hard to read. + + * Include a copyright notice and copying permissions. + +Index, index, index! +.................... + + Write many index entries, in different ways. Readers like indices; +they are helpful and convenient. + + Although it is easiest to write index entries as you write the body +of the text, some people prefer to write entries afterwards. In either +case, write an entry before the paragraph to which it applies. This +way, an index entry points to the first page of a paragraph that is +split across pages. + + Here are more hints we have found valuable: + + * Write each index entry differently, so each entry refers to a + different place in the document. The index of an Info file lists + only one location for each entry. + + * Write index entries only where a topic is discussed significantly. + For example, it is not useful to index "debugging information" in + a chapter on reporting bugs. Someone who wants to know about + debugging information will certainly not find it in that chapter. + + * Consistently capitalize the first word of every index entry, or + else use lower case. According to convention, you should + capitalize the first word of an index entry. However, this + practice may make an index look crowded. Some writers prefer + lower case. Regardless of which you prefer, choose one style and + stick to it. Mixing the two styles looks bad. + + * Always capitalize or use upper case for those words in an index for + which this is proper, such as names of countries or acronyms. + + * Write the indexing commands that refer to a whole section + immediately after the section command, and write the indexing + commands that refer to the paragraph before the paragraph. + + In the example that follows, a blank line comes after the index + entry for "Leaping": + + @section The Dog and the Fox + @cindex Jumping, in general + @cindex Leaping + + @cindex Dog, lazy, jumped over + @cindex Lazy dog jumped over + @cindex Fox, jumps over dog + @cindex Quick fox jumps over dog + The quick brown fox jumps over the lazy dog. + + (Note that the example shows entries for the same concept that are + written in different ways--`Lazy dog', and `Dog, lazy'--so readers + can look up the concept in different ways.) + +Blank lines +........... + + * Insert a blank line between a sectioning command and the first + following sentence or paragraph, or between the indexing commands + associated with the sectioning command and the first following + sentence or paragraph, as shown in the tip on indexing. + Otherwise, a formatter may fold title and paragraph together. + + * Always insert a blank line before an `@table' command and after an + `@end table' command; but never insert a blank line after an + `@table' command or before an `@end table' command. + + For example, + + Types of fox: + + @table @samp + @item Quick + Jump over lazy dogs. + + @item Brown + Also jump over lazy dogs. + @end table + @noindent + On the other hand, ... + + Insert blank lines before and after `@itemize' ... `@end itemize' + and `@enumerate' ... `@end enumerate' in the same way. + +Complete phrases +................ + + Complete phrases are easier to read than ... + + * Write entries in an itemized list as complete sentences; or at + least, as complete phrases. Incomplete expressions ... awkward + ... like this. + + * Write the prefatory sentence or phrase for a multi-item list or + table as a complete expression. Do not write "You can set:"; + instead, write "You can set these variables:". The former + expression sounds cut off. + +Editions, dates and versions +............................ + + Write the edition and version numbers and date in three places in +every manual: + + 1. In the first `@ifinfo' section, for people reading the Texinfo + file. + + 2. In the `@titlepage' section, for people reading the printed manual. + + 3. In the `Top' node, for people reading the Info file. + +Also, it helps to write a note before the first `@ifinfo' section to +explain what you are doing. + +For example: + + @c ===> NOTE! <== + @c Specify the edition and version numbers and date + @c in *three* places: + @c 1. First ifinfo section 2. title page 3. top node + @c To find the locations, search for !!set + + @ifinfo + @c !!set edition, date, version + This is Edition 4.03, January 1992, + of the @cite{GDB Manual} for GDB Version 4.3. + ... + +--or use `@set' and `@value' (*note `@value' Example: value Example.). + +Definition Commands +................... + + Definition commands are `@deffn', `@defun', `@defmac', and the like, +and enable you to write descriptions in a uniform format. + + * Write just one definition command for each entity you define with a + definition command. The automatic indexing feature creates an + index entry that leads the reader to the definition. + + * Use `@table' ... `@end table' in an appendix that contains a + summary of functions, not `@deffn' or other definition commands. + +Capitalization +.............. + + * Capitalize `Texinfo'; it is a name. Do not write the `x' or `i' + in upper case. + + * Capitalize `Info'; it is a name. + + * Write TeX using the `@TeX{}' command. Note the uppercase `T' and + `X'. This command causes the formatters to typeset the name + according to the wishes of Donald Knuth, who wrote TeX. + +Spaces +...... + + Do not use spaces to format a Texinfo file, except inside of +`@example' ... `@end example' and similar commands. + + For example, TeX fills the following: + + @kbd{C-x v} + @kbd{M-x vc-next-action} + Perform the next logical operation + on the version-controlled file + corresponding to the current buffer. + +so it looks like this: + + `C-x v' `M-x vc-next-action' Perform the next logical operation on + the version-controlled file corresponding to the current buffer. + +In this case, the text should be formatted with `@table', `@item', and +`@itemx', to create a table. + +@code, @samp, @var, and `---' +............................. + + * Use `@code' around Lisp symbols, including command names. For + example, + + The main function is @code{vc-next-action}, ... + + * Avoid putting letters such as `s' immediately after an `@code'. + Such letters look bad. + + * Use `@var' around meta-variables. Do not write angle brackets + around them. + + * Use three hyphens in a row, `---', to indicate a long dash. TeX + typesets these as a long dash and the Info formatters reduce three + hyphens to two. + +Periods Outside of Quotes +......................... + + Place periods and other punctuation marks *outside* of quotations, +unless the punctuation is part of the quotation. This practice goes +against convention, but enables the reader to distinguish between the +contents of the quotation and the whole passage. + + For example, you should write the following sentence with the period +outside the end quotation marks: + + Evidently, `au' is an abbreviation for ``author''. + +since `au' does *not* serve as an abbreviation for `author.' (with a +period following the word). + +Introducing New Terms +..................... + + * Introduce new terms so that a user who does not know them can + understand them from context; or write a definition for the term. + + For example, in the following, the terms "check in", "register" and + "delta" are all appearing for the first time; the example sentence + should be rewritten so they are understandable. + + The major function assists you in checking in a file to your + version control system and registering successive sets of + changes to it as deltas. + + * Use the `@dfn' command around a word being introduced, to indicate + that the user should not expect to know the meaning already, and + should expect to learn the meaning from this passage. + +@pxref +...... + + Absolutely never use `@pxref' except in the special context for +which it is designed: inside parentheses, with the closing parenthesis +following immediately after the closing brace. One formatter +automatically inserts closing punctuation and the other does not. This +means that the output looks right both in printed output and in an Info +file, but only when the command is used inside parentheses. + +Invoking from a Shell +..................... + + You can invoke programs such as Emacs, GCC, and GAWK from a shell. +The documentation for each program should contain a section that +describes this. Unfortunately, if the node names and titles for these +sections are all different, readers find it hard to search for the +section. + + Name such sections with a phrase beginning with the word +`Invoking ...', as in `Invoking Emacs'; this way users can find the +section easily. + +ANSI C Syntax +............. + + When you use `@example' to describe a C function's calling +conventions, use the ANSI C syntax, like this: + + void dld_init (char *@var{path}); + +And in the subsequent discussion, refer to the argument values by +writing the same argument names, again highlighted with `@var'. + + Avoid the obsolete style that looks like this: + + #include <dld.h> + + dld_init (path) + char *path; + + Also, it is best to avoid writing `#include' above the declaration +just to indicate that the function is declared in a header file. The +practice may give the misimpression that the `#include' belongs near +the declaration of the function. Either state explicitly which header +file holds the declaration or, better yet, name the header file used +for a group of functions at the beginning of the section that describes +the functions. + +Bad Examples +............ + + Here are several examples of bad writing to avoid: + + In this example, say, " ... you must `@dfn'{check in} the new +version." That flows better. + + When you are done editing the file, you must perform a + `@dfn'{check in}. + + In the following example, say, "... makes a unified interface such +as VC mode possible." + + SCCS, RCS and other version-control systems all perform similar + functions in broadly similar ways (it is this resemblance which + makes a unified control mode like this possible). + + And in this example, you should specify what `it' refers to: + + If you are working with other people, it assists in coordinating + everyone's changes so they do not step on each other. + +And Finally ... +............... + + * Pronounce TeX as if the `X' were a Greek `chi', as the last sound + in the name `Bach'. But pronounce Texinfo as in `speck': + `teckinfo'. + + * Write notes for yourself at the very end of a Texinfo file after + the `@bye'. None of the formatters process text after the `@bye'; + it is as if the text were within `@ignore' ... `@end ignore'. + + +File: texi.info, Node: Sample Texinfo File, Next: Sample Permissions, Prev: Tips, Up: Top + +A Sample Texinfo File +********************* + + Here is a complete, short sample Texinfo file, without any +commentary. You can see this file, with comments, in the first chapter. +*Note A Short Sample Texinfo File: Short Sample. + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Document + @c %**end of header + + @setchapternewpage odd + + @ifinfo + This is a short example of a complete Texinfo file. + + Copyright 1990 Free Software Foundation, Inc. + @end ifinfo + + @titlepage + @sp 10 + @comment The title is printed in a large font. + @center @titlefont{Sample Title} + + @c The following two commands start the copyright page. + @page + @vskip 0pt plus 1filll + Copyright @copyright{} 1990 Free Software Foundation, Inc. + @end titlepage + + @node Top, First Chapter, (dir), (dir) + @comment node-name, next, previous, up + + @menu + * First Chapter:: The first chapter is the + only chapter in this sample. + * Concept Index:: This index has two entries. + @end menu + + @node First Chapter, Concept Index, Top, Top + @comment node-name, next, previous, up + @chapter First Chapter + @cindex Sample index entry + + This is the contents of the first chapter. + @cindex Another sample index entry + + Here is a numbered list. + + @enumerate + @item + This is the first item. + + @item + This is the second item. + @end enumerate + + The @code{makeinfo} and @code{texinfo-format-buffer} + commands transform a Texinfo file such as this into + an Info file; and @TeX{} typesets it for a printed + manual. + + @node Concept Index, , First Chapter, Top + @comment node-name, next, previous, up + @unnumbered Concept Index + + @printindex cp + + @contents + @bye + + +File: texi.info, Node: Sample Permissions, Next: Include Files, Prev: Sample Texinfo File, Up: Top + +Sample Permissions +****************** + + Texinfo files should contain sections that tell the readers that they +have the right to copy and distribute the Texinfo file, the Info file, +and the printed manual. + + Also, if you are writing a manual about software, you should explain +that the software is free and either include the GNU General Public +License (GPL) or provide a reference to it. *Note Distribution: +(emacs)Distrib, for an example of the text that could be used in the +software "Distribution", "General Public License", and "NO WARRANTY" +sections of a document. *Note Texinfo Copying Conditions: Copying, for +an example of a brief explanation of how the copying conditions provide +you with rights. + +* Menu: + +* Inserting Permissions:: How to put permissions in your document. +* ifinfo Permissions:: Sample `ifinfo' copying permissions. +* Titlepage Permissions:: Sample Titlepage copying permissions. + + +File: texi.info, Node: Inserting Permissions, Next: ifinfo Permissions, Up: Sample Permissions + +Inserting Permissions +===================== + + In a Texinfo file, the first `@ifinfo' section usually begins with a +line that says what the file documents. This is what a person reading +the unprocessed Texinfo file or using the advanced Info command `g *' +sees first. *note Advanced Info commands: (info)Expert, for more +information. (A reader using the regular Info commands usually starts +reading at the first node and skips this first section, which is not in +a node.) + + In the `@ifinfo' section, the summary sentence is followed by a +copyright notice and then by the copying permission notice. One of the +copying permission paragraphs is enclosed in `@ignore' and `@end +ignore' commands. This paragraph states that the Texinfo file can be +processed through TeX and printed, provided the printed manual carries +the proper copying permission notice. This paragraph is not made part +of the Info file since it is not relevant to the Info file; but it is a +mandatory part of the Texinfo file since it permits people to process +the Texinfo file in TeX and print the results. + + In the printed manual, the Free Software Foundation copying +permission notice follows the copyright notice and publishing +information and is located within the region delineated by the +`@titlepage' and `@end titlepage' commands. The copying permission +notice is exactly the same as the notice in the `@ifinfo' section +except that the paragraph enclosed in `@ignore' and `@end ignore' +commands is not part of the notice. + + To make it simple to insert a permission notice into each section of +the Texinfo file, sample permission notices for each section are +reproduced in full below. + + Note that you may need to specify the correct name of a section +mentioned in the permission notice. For example, in `The GDB Manual', +the name of the section referring to the General Public License is +called the "GDB General Public License", but in the sample shown below, +that section is referred to generically as the "GNU General Public +License". If the Texinfo file does not carry a copy of the General +Public License, leave out the reference to it, but be sure to include +the rest of the sentence. + + +File: texi.info, Node: ifinfo Permissions, Next: Titlepage Permissions, Prev: Inserting Permissions, Up: Sample Permissions + +`ifinfo' Copying Permissions +============================ + + In the `@ifinfo' section of a Texinfo file, the standard Free +Software Foundation permission notice reads as follows: + + This file documents ... + + Copyright 1992 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim + copies of this manual provided the copyright notice and + this permission notice are preserved on all copies. + + @ignore + Permission is granted to process this file through TeX + and print the results, provided the printed document + carries a copying permission notice identical to this + one except for the removal of this paragraph (this + paragraph not being relevant to the printed manual). + + @end ignore + Permission is granted to copy and distribute modified + versions of this manual under the conditions for + verbatim copying, provided also that the sections + entitled ``Copying'' and ``GNU General Public License'' + are included exactly as in the original, and provided + that the entire resulting derived work is distributed + under the terms of a permission notice identical to this + one. + + Permission is granted to copy and distribute + translations of this manual into another language, + under the above conditions for modified versions, + except that this permission notice may be stated in a + translation approved by the Free Software Foundation. + + +File: texi.info, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions + +Titlepage Copying Permissions +============================= + + In the `@titlepage' section of a Texinfo file, the standard Free +Software Foundation copying permission notice follows the copyright +notice and publishing information. The standard phrasing is as follows: + + Permission is granted to make and distribute verbatim + copies of this manual provided the copyright notice and + this permission notice are preserved on all copies. + + Permission is granted to copy and distribute modified + versions of this manual under the conditions for + verbatim copying, provided also that the sections + entitled ``Copying'' and ``GNU General Public License'' + are included exactly as in the original, and provided + that the entire resulting derived work is distributed + under the terms of a permission notice identical to this + one. + + Permission is granted to copy and distribute + translations of this manual into another language, + under the above conditions for modified versions, + except that this permission notice may be stated in a + translation approved by the Free Software Foundation. + + +File: texi.info, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top + +Include Files +************* + + When TeX or an Info formatting command sees an `@include' command in +a Texinfo file, it processes the contents of the file named by the +command and incorporates them into the DVI or Info file being created. +Index entries from the included file are incorporated into the indices +of the output file. + + Include files let you keep a single large document as a collection of +conveniently small parts. + +* Menu: + +* Using Include Files:: How to use the `@include' command. +* texinfo-multiple-files-update:: How to create and update nodes and + menus when using included files. +* Include File Requirements:: What `texinfo-multiple-files-update' expects. +* Sample Include File:: A sample outer file with included files + within it; and a sample included file. +* Include Files Evolution:: How use of the `@include' command + has changed over time. + + +File: texi.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Up: Include Files + +How to Use Include Files +======================== + + To include another file within a Texinfo file, write the `@include' +command at the beginning of a line and follow it on the same line by +the name of a file to be included. For example: + + @include buffers.texi + + An included file should simply be a segment of text that you expect +to be included as is into the overall or "outer" Texinfo file; it +should not contain the standard beginning and end parts of a Texinfo +file. In particular, you should not start an included file with a line +saying `\input texinfo'; if you do, that phrase is inserted into the +output file as is. Likewise, you should not end an included file with +an `@bye' command; nothing after `@bye' is formatted. + + In the past, you were required to write an `@setfilename' line at the +beginning of an included file, but no longer. Now, it does not matter +whether you write such a line. If an `@setfilename' line exists in an +included file, it is ignored. + + Conventionally, an included file begins with an `@node' line that is +followed by an `@chapter' line. Each included file is one chapter. +This makes it easy to use the regular node and menu creating and +updating commands to create the node pointers and menus within the +included file. However, the simple Emacs node and menu creating and +updating commands do not work with multiple Texinfo files. Thus you +cannot use these commands to fill in the `Next', `Previous', and `Up' +pointers of the `@node' line that begins the included file. Also, you +cannot use the regular commands to create a master menu for the whole +file. Either you must insert the menus and the `Next', `Previous', and +`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode +command, `texinfo-multiple-files-update', that is designed for +`@include' files. + + +File: texi.info, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files + +`texinfo-multiple-files-update' +=============================== + + GNU Emacs Texinfo mode provides a command to handle included files +called `texinfo-multiple-files-update'. This command creates or +updates `Next', `Previous', and `Up' pointers of included files as well +as those in the outer or overall Texinfo file, and it creates or +updates a main menu in the outer file. Depending whether you call it +with optional arguments, the command updates only the pointers in the +first `@node' line of the included files or all of them: + +`M-x texinfo-multiple-files-update' + Called without any arguments: + + - Create or update the `Next', `Previous', and `Up' pointers of + the first `@node' line in each file included in an outer or + overall Texinfo file. + + - Create or update the `Top' level node pointers of the outer or + overall file. + + - Create or update a main menu in the outer file. + +`C-u M-x texinfo-multiple-files-update' + Called with `C-u' as a prefix argument: + + - Create or update pointers in the first `@node' line in each + included file. + + - Create or update the `Top' level node pointers of the outer + file. + + - Create and insert a master menu in the outer file. The + master menu is made from all the menus in all the included + files. + +`C-u 8 M-x texinfo-multiple-files-update' + Called with a numeric prefix argument, such as `C-u 8': + + - Create or update *all* the `Next', `Previous', and `Up' + pointers of all the included files. + + - Create or update *all* the menus of all the included files. + + - Create or update the `Top' level node pointers of the outer or + overall file. + + - And then create a master menu in the outer file. This is + similar to invoking `texinfo-master-menu' with an argument + when you are working with just one file. + + Note the use of the prefix argument in interactive use: with a +regular prefix argument, just `C-u', the +`texinfo-multiple-files-update' command inserts a master menu; with a +numeric prefix argument, such as `C-u 8', the command updates *every* +pointer and menu in *all* the files and then inserts a master menu. + + +File: texi.info, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files + +Include File Requirements +========================= + + If you plan to use the `texinfo-multiple-files-update' command, the +outer Texinfo file that lists included files within it should contain +nothing but the beginning and end parts of a Texinfo file, and a number +of `@include' commands listing the included files. It should not even +include indices, which should be listed in an included file of their +own. + + Moreover, each of the included files must contain exactly one highest +level node (conventionally, `@chapter' or equivalent), and this node +must be the first node in the included file. Furthermore, each of +these highest level nodes in each included file must be at the same +hierarchical level in the file structure. Usually, each is an +`@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally, +each included file contains one, and only one, chapter or +equivalent-level node. + + The outer file should contain only *one* node, the `Top' node. It +should *not* contain any nodes besides the single `Top' node. The +`texinfo-multiple-files-update' command will not process them. + + +File: texi.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files + +Sample File with `@include' +=========================== + + Here is an example of a complete outer Texinfo file with `@include' +files within it before running `texinfo-multiple-files-update', which +would insert a main or master menu: + + \input texinfo @c -*-texinfo-*- + @setfilename include-example.info + @settitle Include Example + + @setchapternewpage odd + @titlepage + @sp 12 + @center @titlefont{Include Example} + @sp 2 + @center by Whom Ever + + @page + @vskip 0pt plus 1filll + Copyright @copyright{} 1990 Free Software Foundation, Inc. + @end titlepage + + @ifinfo + @node Top, First, (dir), (dir) + @top Master Menu + @end ifinfo + + @include foo.texinfo + @include bar.texinfo + @include concept-index.texinfo + + @summarycontents + @contents + + @bye + + An included file, such as `foo.texinfo', might look like this: + + @node First, Second, , Top + @chapter First Chapter + + Contents of first chapter ... + + The full contents of `concept-index.texinfo' might be as simple as +this: + + @node Concept Index, , Second, Top + @unnumbered Concept Index + + @printindex cp + + The outer Texinfo source file for `The GNU Emacs Lisp Reference +Manual' is named `elisp.texi'. This outer file contains a master menu +with 417 entries and a list of 41 `@include' files. + + +File: texi.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files + +Evolution of Include Files +========================== + + When Info was first created, it was customary to create many small +Info files on one subject. Each Info file was formatted from its own +Texinfo source file. This custom meant that Emacs did not need to make +a large buffer to hold the whole of a large Info file when someone +wanted information; instead, Emacs allocated just enough memory for the +small Info file that contained the particular information sought. This +way, Emacs could avoid wasting memory. + + References from one file to another were made by referring to the +file name as well as the node name. (*Note Referring to Other Info +Files: Other Info Files. Also, see *Note `@xref' with Four and Five +Arguments: Four and Five Arguments.) + + Include files were designed primarily as a way to create a single, +large printed manual out of several smaller Info files. In a printed +manual, all the references were within the same document, so TeX could +automatically determine the references' page numbers. The Info +formatting commands used include files only for creating joint indices; +each of the individual Texinfo files had to be formatted for Info +individually. (Each, therefore, required its own `@setfilename' line.) + + However, because large Info files are now split automatically, it is +no longer necessary to keep them small. + + Nowadays, multiple Texinfo files are used mostly for large documents, +such as `The GNU Emacs Lisp Reference Manual', and for projects in +which several different people write different sections of a document +simultaneously. + + In addition, the Info formatting commands have been extended to work +with the `@include' command so as to create a single large Info file +that is split into smaller files if necessary. This means that you can +write menus and cross references without naming the different Texinfo +files. + + +File: texi.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top + +Page Headings +************* + + Most printed manuals contain headings along the top of every page +except the title and copyright pages. Some manuals also contain +footings. (Headings and footings have no meaning to Info, which is not +paginated.) + +* Menu: + +* Headings Introduced:: Conventions for using page headings. +* Heading Format:: Standard page heading formats. +* Heading Choice:: How to specify the type of page heading. +* Custom Headings:: How to create your own headings and footings. + + +File: texi.info, Node: Headings Introduced, Next: Heading Format, Up: Headings + +Headings Introduced +=================== + + Texinfo provides standard page heading formats for manuals that are +printed on one side of each sheet of paper and for manuals that are +printed on both sides of the paper. Usually, you will use one or other +of these formats, but you can specify your own format, if you wish. + + In addition, you can specify whether chapters should begin on a new +page, or merely continue the same page as the previous chapter; and if +chapters begin on new pages, you can specify whether they must be +odd-numbered pages. + + By convention, a book is printed on both sides of each sheet of +paper. When you open a book, the right-hand page is odd-numbered, and +chapters begin on right-hand pages--a preceding left-hand page is left +blank if necessary. Reports, however, are often printed on just one +side of paper, and chapters begin on a fresh page immediately following +the end of the preceding chapter. In short or informal reports, +chapters often do not begin on a new page at all, but are separated +from the preceding text by a small amount of whitespace. + + The `@setchapternewpage' command controls whether chapters begin on +new pages, and whether one of the standard heading formats is used. In +addition, Texinfo has several heading and footing commands that you can +use to generate your own heading and footing formats. + + In Texinfo, headings and footings are single lines at the tops and +bottoms of pages; you cannot create multiline headings or footings. +Each header or footer line is divided into three parts: a left part, a +middle part, and a right part. Any part, or a whole line, may be left +blank. Text for the left part of a header or footer line is set +flushleft; text for the middle part is centered; and, text for the +right part is set flushright. + + +File: texi.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings + +Standard Heading Formats +======================== + + Texinfo provides two standard heading formats, one for manuals +printed on one side of each sheet of paper, and the other for manuals +printed on both sides of the paper. + + By default, nothing is specified for the footing of a Texinfo file, +so the footing remains blank. + + The standard format for single-sided printing consists of a header +line in which the left-hand part contains the name of the chapter, the +central part is blank, and the right-hand part contains the page number. + + A single-sided page looks like this: + + _______________________ + | | + | chapter page number | + | | + | Start of text ... | + | ... | + | | + + The standard format for two-sided printing depends on whether the +page number is even or odd. By convention, even-numbered pages are on +the left- and odd-numbered pages are on the right. (TeX will adjust the +widths of the left- and right-hand margins. Usually, widths are +correct, but during double-sided printing, it is wise to check that +pages will bind properly--sometimes a printer will produce output in +which the even-numbered pages have a larger right-hand margin than the +odd-numbered pages.) + + In the standard double-sided format, the left part of the left-hand +(even-numbered) page contains the page number, the central part is +blank, and the right part contains the title (specified by the +`@settitle' command). The left part of the right-hand (odd-numbered) +page contains the name of the chapter, the central part is blank, and +the right part contains the page number. + + Two pages, side by side as in an open book, look like this: + + _______________________ _______________________ + | | | | + | page number title | | chapter page number | + | | | | + | Start of text ... | | More text ... | + | ... | | ... | + | | | | + +The chapter name is preceded by the word `Chapter', the chapter number +and a colon. This makes it easier to keep track of where you are in +the manual. + + +File: texi.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings + +Specifying the Type of Heading +============================== + + TeX does not begin to generate page headings for a standard Texinfo +file until it reaches the `@end titlepage' command. Thus, the title +and copyright pages are not numbered. The `@end titlepage' command +causes TeX to begin to generate page headings according to a standard +format specified by the `@setchapternewpage' command that precedes the +`@titlepage' section. + + There are four possibilities: + +No `@setchapternewpage' command + Cause TeX to specify the single-sided heading format, with chapters + on new pages. This is the same as `@setchapternewpage on'. + +`@setchapternewpage on' + Specify the single-sided heading format, with chapters on new + pages. + +`@setchapternewpage off' + Cause TeX to start a new chapter on the same page as the last page + of the preceding chapter, after skipping some vertical whitespace. + Also cause TeX to typeset for single-sided printing. (You can + override the headers format with the `@headings double' command; + see *Note The `@headings' Command: headings on off.) + +`@setchapternewpage odd' + Specify the double-sided heading format, with chapters on new + pages. + +Texinfo lacks an `@setchapternewpage even' command. + + +File: texi.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings + +How to Make Your Own Headings +============================= + + You can use the standard headings provided with Texinfo or specify +your own. + + Texinfo provides six commands for specifying headings and footings. +The `@everyheading' command and `@everyfooting' command generate page +headers and footers that are the same for both even- and odd-numbered +pages. The `@evenheading' command and `@evenfooting' command generate +headers and footers for even-numbered (left-hand) pages; and the +`@oddheading' command and `@oddfooting' command generate headers and +footers for odd-numbered (right-hand) pages. + + Write custom heading specifications in the Texinfo file immediately +after the `@end titlepage' command. Enclose your specifications +between `@iftex' and `@end iftex' commands since the +`texinfo-format-buffer' command may not recognize them. Also, you must +cancel the predefined heading commands with the `@headings off' command +before defining your own specifications. + + Here is how to tell TeX to place the chapter name at the left, the +page number in the center, and the date at the right of every header +for both even- and odd-numbered pages: + + @iftex + @headings off + @everyheading @thischapter @| @thispage @| @today{} + @end iftex + +You need to divide the left part from the central part and the central +part from the right had part by inserting `@|' between parts. +Otherwise, the specification command will not be able to tell where the +text for one part ends and the next part begins. + + Each part can contain text or @-commands. The text is printed as if +the part were within an ordinary paragraph in the body of the page. +The @-commands replace themselves with the page number, date, chapter +name, or whatever. + + Here are the six heading and footing commands: + +`@everyheading LEFT @| CENTER @| RIGHT' +`@everyfooting LEFT @| CENTER @| RIGHT' + The `every' commands specify the format for both even- and + odd-numbered pages. These commands are for documents that are + printed on one side of each sheet of paper, or for documents in + which you want symmetrical headers or footers. + +`@evenheading LEFT @| CENTER @| RIGHT' +`@oddheading LEFT @| CENTER @| RIGHT' +`@evenfooting LEFT @| CENTER @| RIGHT' +`@oddfooting LEFT @| CENTER @| RIGHT' + The `even' and `odd' commands specify the format for even-numbered + pages and odd-numbered pages. These commands are for books and + manuals that are printed on both sides of each sheet of paper. + + Use the `@this...' series of @-commands to provide the names of +chapters and sections and the page number. You can use the `@this...' +commands in the left, center, or right portions of headers and footers, +or anywhere else in a Texinfo file so long as they are between `@iftex' +and `@end iftex' commands. + + Here are the `@this...' commands: + +`@thispage' + Expands to the current page number. + +`@thischaptername' + Expands to the name of the current chapter. + +`@thischapter' + Expands to the number and name of the current chapter, in the + format `Chapter 1: Title'. + +`@thistitle' + Expands to the name of the document, as specified by the + `@settitle' command. + +`@thisfile' + For `@include' files only: expands to the name of the current + `@include' file. If the current Texinfo source file is not an + `@include' file, this command has no effect. This command does + *not* provide the name of the current Texinfo source file unless + it is an `@include' file. (*Note Include Files::, for more + information about `@include' files.) + +You can also use the `@today{}' command, which expands to the current +date, in `1 Jan 1900' format. + + Other @-commands and text are printed in a header or footer just as +if they were in the body of a page. It is useful to incorporate text, +particularly when you are writing drafts: + + @iftex + @headings off + @everyheading @emph{Draft!} @| @thispage @| @thischapter + @everyfooting @| @| Version: 0.27: @today{} + @end iftex + + Beware of overlong titles: they may overlap another part of the +header or footer and blot it out. + + +File: texi.info, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top + +Formatting Mistakes +******************* + + Besides mistakes in the content of your documentation, there are two +kinds of mistake you can make with Texinfo: you can make mistakes with +@-commands, and you can make mistakes with the structure of the nodes +and chapters. + + Emacs has two tools for catching the @-command mistakes and two for +catching structuring mistakes. + + For finding problems with @-commands, you can run TeX or a region +formatting command on the region that has a problem; indeed, you can +run these commands on each region as you write it. + + For finding problems with the structure of nodes and chapters, you +can use `C-c C-s' (`texinfo-show-structure') and the related `occur' +command and you can use the `M-x Info-validate' command. + +* Menu: + +* makeinfo preferred:: `makeinfo' finds errors. +* Debugging with Info:: How to catch errors with Info formatting. +* Debugging with TeX:: How to catch errors with TeX formatting. +* Using texinfo-show-structure:: How to use `texinfo-show-structure'. +* Using occur:: How to list all lines containing a pattern. +* Running Info-Validate:: How to find badly referenced nodes. + + +File: texi.info, Node: makeinfo preferred, Next: Debugging with Info, Up: Catching Mistakes + +`makeinfo' Find Errors +====================== + + The `makeinfo' program does an excellent job of catching errors and +reporting them--far better than either the `texinfo-format-region' or +the `texinfo-format-buffer' command. In addition, the various +functions for automatically creating and updating node pointers and +menus remove many opportunities for human error. + + If you can, use the updating commands to create and insert pointers +and menus. These prevent many errors. Then use `makeinfo' (or its +Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer') +to format your file and check for other errors. This is the best way +to work with Texinfo. But if you cannot use `makeinfo', or your +problem is very puzzling, then you may want to use the tools described +in this appendix. + + +File: texi.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo preferred, Up: Catching Mistakes + +Catching Errors with Info Formatting +==================================== + + After you have written part of a Texinfo file, you can use the +`texinfo-format-region' or the `makeinfo-region' command to see whether +the region formats properly. + + Most likely, however, you are reading this section because for some +reason you cannot use the `makeinfo-region' command; therefore, the +rest of this section presumes that you are using +`texinfo-format-region'. + + If you make a mistake with an @-command, `texinfo-format-region' +will stop processing at or after the error and display an error +message. To see where in the buffer the error occurred, switch to the +`*Info Region*' buffer; the cursor will be in a position that is after +the location of the error. Also, the text will not be formatted after +the place where the error occurred (or more precisely, where it was +detected). + + For example, if you accidentally end a menu with the command `@end +menus' with an `s' on the end, instead of with `@end menu', you will +see an error message that says: + + @end menus is not handled by texinfo + +The cursor will stop at the point in the buffer where the error occurs, +or not long after it. The buffer will look like this: + + ---------- Buffer: *Info Region* ---------- + * Menu: + + * Using texinfo-show-structure:: How to use + `texinfo-show-structure' + to catch mistakes. + * Running Info-Validate:: How to check for + unreferenced nodes. + @end menus + -!- + ---------- Buffer: *Info Region* ---------- + + The `texinfo-format-region' command sometimes provides slightly odd +error messages. For example, the following cross reference fails to +format: + + (@xref{Catching Mistakes, for more info.) + +In this case, `texinfo-format-region' detects the missing closing brace +but displays a message that says `Unbalanced parentheses' rather than +`Unbalanced braces'. This is because the formatting command looks for +mismatches between braces as if they were parentheses. + + Sometimes `texinfo-format-region' fails to detect mistakes. For +example, in the following, the closing brace is swapped with the +closing parenthesis: + + (@xref{Catching Mistakes), for more info.} + +Formatting produces: + (*Note for more info.: Catching Mistakes) + + The only way for you to detect this error is to realize that the +reference should have looked like this: + + (*Note Catching Mistakes::, for more info.) + + Incidentally, if you are reading this node in Info and type `f RET' +(`Info-follow-reference'), you will generate an error message that says: + + No such node: "Catching Mistakes) The only way ... + +This is because Info perceives the example of the error as the first +cross reference in this node and if you type a RET immediately after +typing the Info `f' command, Info will attempt to go to the referenced +node. If you type `f catch TAB RET', Info will complete the node name +of the correctly written example and take you to the `Catching +Mistakes' node. (If you try this, you can return from the `Catching +Mistakes' node by typing `l' (`Info-last').) + |
