| \input texinfo.tex @c -*-texinfo-*- |
| @comment %**start of header |
| @setfilename texinfo |
| @settitle Texinfo @value{edition} |
| @c Define a new index for options. |
| @defcodeindex op |
| @c Put everything except function (command, in this case) names in one |
| index (arbitrarily chosen to be the concept index). |
| @syncodeindex op cp |
| @syncodeindex vr cp |
| @syncodeindex pg cp |
| @footnotestyle separate |
| @paragraphindent 2 |
| @finalout |
| @comment %**end of header |
| @comment $Id: texinfo.texi,v 1.1 1997/08/21 22:57:54 jason Exp $ |
| |
| @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a |
| @c prefix arg). This updates the node pointers, which texinfmt.el needs. |
| |
| @dircategory Texinfo documentation system |
| @direntry |
| * 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. |
| @end direntry |
| |
| @c Set smallbook if printing in smallbook format so the example of the |
| @c smallbook font is actually written using smallbook; in bigbook, a kludge |
| @c is used for TeX output. |
| @smallbook |
| @set smallbook |
| @c @@clear smallbook |
| |
| @set edition 2.23 |
| @set update-month October 1996 |
| @set update-date 1 @value{update-month} |
| |
| @c Currently undocumented command, 5 December 1993: |
| @c |
| @c nwnode (Same as node, but no warnings; for `makeinfo'.) |
| |
| @ifinfo |
| 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, 1996 Free Software Foundation, Inc. |
| |
| This is the second edition of the Texinfo documentation,@* |
| and is consistent with version 2 of @file{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. |
| |
| @ignore |
| Permission is granted to process this file through TeX and print the |
| results, provided the printed document carries 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 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. |
| @end ifinfo |
| |
| @setchapternewpage odd |
| |
| @shorttitlepage Texinfo |
| |
| @titlepage |
| @c use the new format for titles |
| @title Texinfo |
| @subtitle The GNU Documentation Format |
| @subtitle Edition @value{edition}, for Texinfo Version Three |
| @subtitle @value{update-month} |
| |
| @author Robert J.@: Chassell |
| @author Richard M.@: Stallman |
| |
| @c Include the Distribution inside the titlepage so |
| @c that headings are turned off. |
| |
| @page |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996 Free Software Foundation, Inc. |
| |
| @sp 2 |
| This is the second edition of the Texinfo documentation,@* |
| and is consistent with version 2 of @file{texinfo.tex}. |
| @sp 2 |
| |
| Published by the Free Software Foundation @* |
| 59 Temple Place Suite 330, @* |
| Boston, MA 02111-1307 USA @* |
| Printed copies are available for $15 each.@* |
| ISBN 1-882114-64-7 |
| @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 |
| @c ISBN 1-882114-64-7 is for edition 2.23 of 1 October 1996. |
| |
| 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. |
| @sp 2 |
| Cover art by Etienne Suvasa. |
| @end titlepage |
| |
| @ifinfo |
| @node Top, Copying, (dir), (dir) |
| @top Texinfo |
| |
| Texinfo is a documentation system that uses a single source file to |
| produce both on-line information and printed output.@refill |
| |
| The first part of this master menu lists the major nodes in this Info |
| document, including the @@-command and concept indices. The rest of |
| the menu lists all the lower level nodes in the document.@refill |
| |
| This is Edition @value{edition} of the Texinfo documentation, |
| @w{@value{update-date},} for Texinfo Version Three. |
| @end ifinfo |
| |
| @c Here is a spare copy of the chapter menu entry descriptions, |
| @c in case they are accidently deleted |
| @ignore |
| Your rights. |
| Texinfo in brief. |
| How to use Texinfo mode. |
| What is at the beginning of a Texinfo file? |
| What is at the end of a Texinfo file? |
| How to create chapters, sections, subsections, |
| appendices, and other parts. |
| How to provide structure for a document. |
| How to write nodes. |
| How to write menus. |
| How to write cross references. |
| How to mark words and phrases as code, |
| keyboard input, meta-syntactic |
| variables, and the like. |
| How to write quotations, examples, etc. |
| How to write lists and tables. |
| How to create indices. |
| How to insert @@-signs, braces, etc. |
| How to indicate results of evaluation, |
| expansion of macros, errors, etc. |
| How to force and prevent line and page breaks. |
| How to describe functions and the like in a uniform manner. |
| How to write footnotes. |
| How to specify text for either @TeX{} or Info. |
| How to print hardcopy. |
| How to create an Info file. |
| How to install an Info file |
| A list of all the Texinfo @@-commands. |
| Hints on how to write a Texinfo document. |
| A sample Texinfo file to look at. |
| Tell readers they have the right to copy |
| and distribute. |
| How to incorporate other Texinfo files. |
| How to write page headings and footings. |
| How to find formatting mistakes. |
| All about paragraph refilling. |
| A description of @@-Command syntax. |
| Texinfo second edition features. |
| A menu containing commands and variables. |
| A menu covering many topics. |
| @end ignore |
| |
| @menu |
| * Copying:: Your rights. |
| * Overview:: Texinfo in brief. |
| * Texinfo Mode:: How to use Texinfo mode. |
| * Beginning a File:: What is at the beginning of a Texinfo file? |
| * Ending a File:: What is at the end of a Texinfo file? |
| * Structuring:: How to create chapters, sections, subsections, |
| appendices, and other parts. |
| * Nodes:: How to write nodes. |
| * Menus:: How to write menus. |
| * Cross References:: How to write cross references. |
| * Marking Text:: How to mark words and phrases as code, |
| keyboard input, meta-syntactic |
| variables, and the like. |
| * Quotations and Examples:: How to write quotations, examples, etc. |
| * Lists and Tables:: How to write lists and tables. |
| * Indices:: How to create indices. |
| * Insertions:: How to insert @@-signs, braces, etc. |
| * Glyphs:: How to indicate results of evaluation, |
| expansion of macros, errors, etc. |
| * Breaks:: How to force and prevent line and page breaks. |
| * Definition Commands:: How to describe functions and the like |
| in a uniform manner. |
| * Footnotes:: How to write footnotes. |
| * Conditionals:: How to specify text for either @TeX{} or Info. |
| * Macros:: Defining new Texinfo commands. |
| * Format/Print Hardcopy:: How to convert a Texinfo file to a file |
| for printing and how to print that file. |
| * Create an Info File:: Convert a Texinfo file into an Info file. |
| * Install an Info File:: Make an Info file accessible to users. |
| * Command List:: All the Texinfo @@-commands. |
| * Tips:: Hints on how to write a Texinfo document. |
| * Sample Texinfo File:: A sample Texinfo file to look at. |
| * Sample Permissions:: Tell readers they have the right to copy |
| and distribute. |
| * Include Files:: How to incorporate other Texinfo files. |
| * Headings:: How to write page headings and footings. |
| * Catching Mistakes:: How to find formatting mistakes. |
| * Refilling Paragraphs:: All about paragraph refilling. |
| * Command Syntax:: A description of @@-Command syntax. |
| * Obtaining TeX:: How to Obtain @TeX{}. |
| * New Features:: Texinfo second edition features. |
| * Command and Variable Index:: A menu containing commands and variables. |
| * Concept Index:: A menu covering many topics. |
| |
| @detailmenu |
| |
| --- The Detailed Node Listing --- |
| |
| Overview of Texinfo |
| |
| * Using Texinfo:: Create a conventional printed book |
| or an Info file. |
| * Info Files:: What is an Info file? |
| * Printed Books:: Characteristics of a printed book or manual. |
| * Formatting Commands:: @@-commands are used for formatting. |
| * Conventions:: General rules for writing a Texinfo file. |
| * Comments:: How to write comments and mark regions that |
| the formatting commands will ignore. |
| * Minimum:: What a Texinfo file must have. |
| * Six Parts:: Usually, a Texinfo file has six parts. |
| * Short Sample:: A short sample Texinfo file. |
| * Acknowledgements:: |
| |
| Using Texinfo Mode |
| |
| * Texinfo Mode Overview:: How Texinfo mode can help you. |
| * Emacs Editing:: Texinfo mode adds to GNU Emacs' general |
| purpose editing features. |
| * Inserting:: How to insert frequently used @@-commands. |
| * Showing the Structure:: How to show the structure of a file. |
| * Updating Nodes and Menus:: How to update or create new nodes and menus. |
| * Info Formatting:: How to format for Info. |
| * Printing:: How to format and print part or all of a file. |
| * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. |
| |
| Updating Nodes and Menus |
| |
| * Updating Commands:: Five major updating commands. |
| * Updating Requirements:: How to structure a Texinfo file for |
| using the updating command. |
| * Other Updating Commands:: How to indent descriptions, insert |
| missing nodes lines, and update |
| nodes in sequence. |
| |
| Beginning a Texinfo File |
| |
| * Four Parts:: Four parts begin a Texinfo file. |
| * Sample Beginning:: Here is a sample beginning for a Texinfo file. |
| * Header:: The very beginning of a Texinfo file. |
| * Info Summary and Permissions:: Summary and copying permissions for Info. |
| * Titlepage & Copyright Page:: Creating the title and copyright pages. |
| * The Top Node:: Creating the `Top' node and master menu. |
| * Software Copying Permissions:: Ensure that you and others continue to |
| have the right to use and share software. |
| |
| The Texinfo File Header |
| |
| * First Line:: The first line of a Texinfo file. |
| * Start of Header:: Formatting a region requires this. |
| * setfilename:: Tell Info the name of the Info file. |
| * settitle:: Create a title for the printed work. |
| * setchapternewpage:: Start chapters on right-hand pages. |
| * paragraphindent:: An option to specify paragraph indentation. |
| * End of Header:: Formatting a region requires this. |
| |
| The Title and Copyright Pages |
| |
| * titlepage:: Create a title for the printed document. |
| * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, |
| and @code{@@sp} commands. |
| * title subtitle author:: The @code{@@title}, @code{@@subtitle}, |
| and @code{@@author} commands. |
| * Copyright & Permissions:: How to write the copyright notice and |
| include copying permissions. |
| * end titlepage:: Turn on page headings after the title and |
| copyright pages. |
| * headings on off:: An option for turning headings on and off |
| and double or single sided printing. |
| |
| The `Top' Node and Master Menu |
| |
| * Title of Top Node:: Sketch what the file is about. |
| * Master Menu Parts:: A master menu has three or more parts. |
| |
| Ending a Texinfo File |
| |
| * Printing Indices & Menus:: How to print an index in hardcopy and |
| generate index menus in Info. |
| * Contents:: How to create a table of contents. |
| * File End:: How to mark the end of a file. |
| |
| Chapter Structuring |
| |
| * Tree Structuring:: A manual is like an upside down tree @dots{} |
| * Structuring Command Types:: How to divide a manual into parts. |
| * makeinfo top:: The @code{@@top} command, part of the `Top' node. |
| * chapter:: |
| * unnumbered & appendix:: |
| * majorheading & chapheading:: |
| * section:: |
| * unnumberedsec appendixsec heading:: |
| * subsection:: |
| * unnumberedsubsec appendixsubsec subheading:: |
| * subsubsection:: Commands for the lowest level sections. |
| * Raise/lower sections:: How to change commands' hierarchical level. |
| |
| Nodes |
| |
| * Two Paths:: Different commands to structure |
| Info output and printed output. |
| * Node Menu Illustration:: A diagram, and sample nodes and menus. |
| * node:: How to write a node, in detail. |
| * makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. |
| |
| The @code{@@node} Command |
| |
| * Node Names:: How to choose node and pointer names. |
| * Writing a Node:: How to write an @code{@@node} line. |
| * Node Line Tips:: Keep names short. |
| * Node Line Requirements:: Keep names unique, without @@-commands. |
| * First Node:: How to write a `Top' node. |
| * makeinfo top command:: How to use the @code{@@top} command. |
| * Top Node Summary:: Write a brief description for readers. |
| |
| Menus |
| |
| * Menu Location:: Put a menu in a short node. |
| * Writing a Menu:: What is a menu? |
| * Menu Parts:: A menu entry has three parts. |
| * Less Cluttered Menu Entry:: Two part menu entry. |
| * Menu Example:: Two and three part menu entries. |
| * Other Info Files:: How to refer to a different Info file. |
| |
| Cross References |
| |
| * References:: What cross references are for. |
| * Cross Reference Commands:: A summary of the different commands. |
| * Cross Reference Parts:: A cross reference has several parts. |
| * xref:: Begin a reference with `See' @dots{} |
| * Top Node Naming:: How to refer to the beginning of another file. |
| * ref:: A reference for the last part of a sentence. |
| * pxref:: How to write a parenthetical cross reference. |
| * inforef:: How to refer to an Info-only file. |
| |
| @code{@@xref} |
| |
| * Reference Syntax:: What a reference looks like and requires. |
| * One Argument:: @code{@@xref} with one argument. |
| * Two Arguments:: @code{@@xref} with two arguments. |
| * Three Arguments:: @code{@@xref} with three arguments. |
| * Four and Five Arguments:: @code{@@xref} with four and five arguments. |
| |
| Marking Words and Phrases |
| |
| * Indicating:: How to indicate definitions, files, etc. |
| * Emphasis:: How to emphasize text. |
| |
| Indicating Definitions, Commands, etc. |
| |
| * Useful Highlighting:: Highlighting provides useful information. |
| * code:: How to indicate code. |
| * kbd:: How to show keyboard input. |
| * key:: How to specify keys. |
| * samp:: How to show a literal sequence of characters. |
| * var:: How to indicate a metasyntactic variable. |
| * file:: How to indicate the name of a file. |
| * dfn:: How to specify a definition. |
| * cite:: How to refer to a book that is not in Info. |
| * url:: How to indicate a world wide web reference. |
| * email:: How to indicate an electronic mail address. |
| |
| Emphasizing Text |
| |
| * emph & strong:: How to emphasize text in Texinfo. |
| * Smallcaps:: How to use the small caps font. |
| * Fonts:: Various font commands for printed output. |
| * Customized Highlighting:: How to define highlighting commands. |
| |
| Quotations and Examples |
| |
| * Block Enclosing Commands:: Use different constructs for |
| different purposes. |
| * quotation:: How to write a quotation. |
| * example:: How to write an example in a fixed-width font. |
| * noindent:: How to prevent paragraph indentation. |
| * Lisp Example:: How to illustrate Lisp code. |
| * smallexample & smalllisp:: Forms for the @code{@@smallbook} option. |
| * display:: How to write an example in the current font. |
| * format:: How to write an example that does not narrow |
| the margins. |
| * exdent:: How to undo the indentation of a line. |
| * flushleft & flushright:: How to push text flushleft or flushright. |
| * cartouche:: How to draw cartouches around examples. |
| |
| Making Lists and Tables |
| |
| * Introducing Lists:: Texinfo formats lists for you. |
| * itemize:: How to construct a simple list. |
| * enumerate:: How to construct a numbered list. |
| * Two-column Tables:: How to construct a two-column table. |
| * Multi-column Tables:: How to construct generalized tables. |
| |
| Making a Two-column Table |
| |
| * table:: How to construct a two-column table. |
| * ftable vtable:: How to construct a two-column table |
| with automatic indexing. |
| * itemx:: How to put more entries in the first column. |
| |
| Multi-column Tables |
| |
| * Multitable Column Widths:: Defining multitable column widths. |
| * Multitable Rows:: Defining multitable rows, with examples. |
| |
| Creating Indices |
| |
| * Index Entries:: Choose different words for index entries. |
| * Predefined Indices:: Use different indices for different kinds |
| of entry. |
| * Indexing Commands:: How to make an index entry. |
| * Combining Indices:: How to combine indices. |
| * New Indices:: How to define your own indices. |
| |
| Combining Indices |
| |
| * syncodeindex:: How to merge two indices, using @code{@@code} |
| font for the merged-from index. |
| * synindex:: How to merge two indices, using the |
| default font of the merged-to index. |
| |
| Special Insertions |
| |
| * Braces Atsigns:: How to insert braces, @samp{@@}. |
| * Inserting Space:: How to insert the right amount of space |
| within a sentence. |
| * Inserting Accents:: How to insert accents and special characters. |
| * Dots Bullets:: How to insert dots and bullets. |
| * TeX and copyright:: How to insert the @TeX{} logo |
| and the copyright symbol. |
| * pounds:: How to insert the pounds currency symbol. |
| * minus:: How to insert a minus sign. |
| * math:: How to format a mathematical expression. |
| |
| Inserting @@ and Braces |
| |
| * Inserting An Atsign:: How to insert @samp{@@}. |
| * Inserting Braces:: How to insert @samp{@{} and @samp{@}}. |
| |
| Inserting Space |
| |
| * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. |
| * Ending a Sentence:: Sometimes it does. |
| * Multiple Spaces:: Inserting multiple spaces. |
| * dmn:: How to format a dimension. |
| |
| Inserting Ellipsis, Dots, and Bullets |
| |
| * dots:: How to insert dots @dots{} |
| * bullet:: How to insert a bullet. |
| |
| Inserting @TeX{} and the Copyright Symbol |
| |
| * tex:: How to insert the @TeX{} logo. |
| * copyright symbol:: How to use @code{@@copyright}@{@}. |
| |
| Glyphs for Examples |
| |
| * Glyphs Summary:: |
| * result:: How to show the result of expression. |
| * expansion:: How to indicate an expansion. |
| * Print Glyph:: How to indicate printed output. |
| * Error Glyph:: How to indicate an error message. |
| * Equivalence:: How to indicate equivalence. |
| * Point Glyph:: How to indicate the location of point. |
| |
| Making and Preventing Breaks |
| |
| * Break Commands:: Cause and prevent splits. |
| * Line Breaks:: How to force a single line to use two lines. |
| * - and hyphenation:: How to tell TeX about hyphenation points. |
| * w:: How to prevent unwanted line breaks. |
| * sp:: How to insert blank lines. |
| * page:: How to force the start of a new page. |
| * group:: How to prevent unwanted page breaks. |
| * need:: Another way to prevent unwanted page breaks. |
| |
| Definition Commands |
| |
| * Def Cmd Template:: How to structure a description using a |
| definition command. |
| * Optional Arguments:: How to handle optional and repeated arguments. |
| * deffnx:: How to group two or more `first' lines. |
| * Def Cmds in Detail:: All the definition commands. |
| * Def Cmd Conventions:: Conventions for writing definitions. |
| * Sample Function Definition:: |
| |
| The Definition Commands |
| |
| * Functions Commands:: Commands for functions and similar entities. |
| * Variables Commands:: Commands for variables and similar entities. |
| * Typed Functions:: Commands for functions in typed languages. |
| * Typed Variables:: Commands for variables in typed languages. |
| * Abstract Objects:: Commands for object-oriented programming. |
| * Data Types:: The definition command for data types. |
| |
| Footnotes |
| |
| * Footnote Commands:: How to write a footnote in Texinfo. |
| * Footnote Styles:: Controlling how footnotes appear in Info. |
| |
| Conditionally Visible Text |
| |
| * Conditional Commands:: How to specify text for HTML, Info, or @TeX{}. |
| * Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. |
| * set clear value:: How to designate which text to format (for |
| both Info and @TeX{}); and how to set a |
| flag to a string that you can insert. |
| |
| @code{@@set}, @code{@@clear}, and @code{@@value} |
| |
| * ifset ifclear:: Format a region if a flag is set. |
| * value:: Replace a flag with a string. |
| * value Example:: An easy way to update edition information. |
| |
| Macros: Defining New Texinfo Commands |
| |
| * Defining Macros:: Both defining and undefining new commands. |
| * Invoking Macros:: Using a macro, once you've defined it. |
| |
| Format and Print Hardcopy |
| |
| * Use TeX:: Use @TeX{} to format for hardcopy. |
| * Format with tex/texindex:: How to format in a shell. |
| * Format with texi2dvi:: A simpler way to use the shell. |
| * 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 you need to do to 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 European A4 paper. |
| * Cropmarks and Magnification:: How to print marks to indicate the size |
| of pages and how to print scaled up output. |
| |
| Creating an Info File |
| |
| * makeinfo advantages:: @code{makeinfo} provides better error checking. |
| * Invoking makeinfo:: How to run @code{makeinfo} from a shell. |
| * makeinfo options:: Specify fill-column and other options. |
| * Pointer Validation:: How to check that pointers point somewhere. |
| * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. |
| * texinfo-format commands:: Two Info formatting commands written |
| in Emacs Lisp are an alternative |
| to @code{makeinfo}. |
| * Batch Formatting:: How to format for Info in Emacs Batch mode. |
| * Tag and Split Files:: How tagged and split files help Info |
| to run better. |
| |
| Installing an Info File |
| |
| * Directory file:: The top level menu for all Info files. |
| * New Info File:: Listing a new info file. |
| * Other Info Directories:: How to specify Info files that are |
| located in other directories. |
| * Installing Dir Entries:: How to specify what menu entry to add |
| to the Info directory. |
| * Invoking install-info:: @code{install-info} options. |
| |
| Sample Permissions |
| |
| * Inserting Permissions:: How to put permissions in your document. |
| * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. |
| * Titlepage Permissions:: Sample Titlepage copying permissions. |
| |
| 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 File Requirements:: What @code{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 @code{@@include} command |
| has changed over time. |
| |
| Page Headings |
| |
| * 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. |
| |
| Formatting Mistakes |
| |
| * makeinfo preferred:: @code{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 @code{texinfo-show-structure}. |
| * Using occur:: How to list all lines containing a pattern. |
| * Running Info-Validate:: How to find badly referenced nodes. |
| |
| Finding Badly Referenced Nodes |
| |
| * Using Info-validate:: How to run @code{Info-validate}. |
| * Unsplit:: How to create an unsplit file. |
| * Tagifying:: How to tagify a file. |
| * Splitting:: How to split a file manually. |
| |
| Second Edition Features |
| |
| * New Texinfo Mode Commands:: The updating commands are especially useful. |
| * New Commands:: Many newly described @@-commands. |
| @end detailmenu |
| @end menu |
| |
| @node Copying, Overview, Top, Top |
| @comment node-name, next, previous, up |
| @unnumbered Texinfo Copying Conditions |
| @cindex Copying conditions |
| @cindex Conditions for copying Texinfo |
| |
| The programs currently being distributed that relate to Texinfo include |
| portions of GNU Emacs, plus other separate programs (including |
| @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). |
| These programs are @dfn{free}; this means that everyone is free to use |
| them and free to redistribute them on a free basis. The Texinfo-related |
| programs are not in the public domain; they are copyrighted and there |
| are restrictions on their distribution, but these restrictions are |
| designed to permit everything that a good cooperating citizen would want |
| to do. What is not allowed is to try to prevent others from further |
| sharing any version of these programs that they might get from |
| you.@refill |
| |
| Specifically, we want to make sure that you have the right to give |
| away copies of the programs that relate to Texinfo, that you receive |
| source code or else can get it if you want it, that you can change these |
| programs or use pieces of them in new free programs, and that you know |
| you can do these things.@refill |
| |
| To make sure that everyone has such rights, we have to forbid you to |
| deprive anyone else of these rights. For example, if you distribute |
| copies of the Texinfo related programs, you must give the recipients all |
| the rights that you have. You must make sure that they, too, receive or |
| can get the source code. And you must tell them their rights.@refill |
| |
| Also, for our own protection, we must make certain that everyone finds |
| out that there is no warranty for the programs that relate to Texinfo. |
| If these programs are modified by someone else and passed on, we want |
| their recipients to know that what they have is not what we distributed, |
| so that any problems introduced by others will not reflect on our |
| reputation.@refill |
| |
| The precise conditions of the licenses for the programs currently |
| being distributed that relate to Texinfo are found in the General Public |
| Licenses that accompany them.@refill |
| |
| @node Overview, Texinfo Mode, Copying, Top |
| @comment node-name, next, previous, up |
| @chapter Overview of Texinfo |
| @cindex Overview of Texinfo |
| @cindex Texinfo overview |
| |
| @dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is |
| pronounced like ``speck'', not ``hex''. This odd pronunciation is |
| derived from, but is not the same as, the pronunciation of @TeX{}. In |
| the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' |
| rather than the English letter ``ex''. Pronounce @TeX{} as if the |
| @samp{X} were the last sound in the name `Bach'; but pronounce Texinfo |
| as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' |
| and write the other letters in lower case.} |
| is a documentation system that uses a single source file to produce both |
| on-line information and printed output. This means that instead of |
| writing two different documents, one for the on-line help or other on-line |
| information and the other for a typeset manual or other printed work, you |
| need write only one document. When the work is revised, you need revise |
| only one document. (You can read the on-line information, known as an |
| @dfn{Info file}, with an Info documentation-reading program.)@refill |
| |
| @menu |
| * Using Texinfo:: Create a conventional printed book |
| or an Info file. |
| * Info Files:: What is an Info file? |
| * Printed Books:: Characteristics of a printed book or manual. |
| * Formatting Commands:: @@-commands are used for formatting. |
| * Conventions:: General rules for writing a Texinfo file. |
| * Comments:: How to write comments and mark regions that |
| the formatting commands will ignore. |
| * Minimum:: What a Texinfo file must have. |
| * Six Parts:: Usually, a Texinfo file has six parts. |
| * Short Sample:: A short sample Texinfo file. |
| * Acknowledgements:: |
| @end menu |
| |
| @node Using Texinfo, Info Files, Overview, Overview |
| @ifinfo |
| @heading Using Texinfo |
| @end ifinfo |
| |
| Using Texinfo, you can create a printed document with the normal |
| features of a book, including chapters, sections, cross references, |
| and indices. From the same Texinfo source file, you can create a |
| menu-driven, on-line Info file with nodes, menus, cross references, |
| and indices. You can, if you wish, make the chapters and sections of |
| the printed document correspond to the nodes of the on-line |
| information; and you use the same cross references and indices for |
| both the Info file and the printed work. @cite{The GNU |
| Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill |
| |
| To make a printed document, you process a Texinfo source file with the |
| @TeX{} typesetting program. This creates a @sc{dvi} file that you can |
| typeset and print as a book or report. (Note that the Texinfo language |
| is completely different from @TeX{}'s usual language, plain @TeX{}.) If |
| you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you |
| can use the @code{texi2roff} program instead.@refill |
| |
| To make an Info file, you process a Texinfo source file with the |
| @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; |
| this creates an Info file that you can install on-line.@refill |
| |
| @TeX{} and @code{texi2roff} work with many types of printer; similarly, |
| Info works with almost every type of computer terminal. This power |
| makes Texinfo a general purpose system, but brings with it a constraint, |
| which is that a Texinfo file may contain only the customary |
| ``typewriter'' characters (letters, numbers, spaces, and punctuation |
| marks) but no special graphics.@refill |
| |
| A Texinfo file is a plain @sc{ascii} file containing text and |
| @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the |
| typesetting and formatting programs what to do. You may edit a |
| Texinfo file with any text editor; but it is especially convenient to |
| use GNU Emacs since that editor has a special mode, called Texinfo |
| mode, that provides various Texinfo-related features. (@xref{Texinfo |
| Mode}.)@refill |
| |
| Before writing a Texinfo source file, you should become familiar with |
| the Info documentation reading program and learn about nodes, |
| menus, cross references, and the rest. (@inforef{Top, info, info}, |
| for more information.)@refill |
| |
| You can use Texinfo to create both on-line help and printed manuals; |
| moreover, Texinfo is freely redistributable. For these reasons, Texinfo |
| is the format in which documentation for GNU utilities and libraries is |
| written.@refill |
| |
| @node Info Files, Printed Books, Using Texinfo, Overview |
| @comment node-name, next, previous, up |
| @section Info files |
| @cindex Info files |
| |
| An Info file is a Texinfo file formatted so that the Info documentation |
| reading program can operate on it. (@code{makeinfo} |
| and @code{texinfo-format-buffer} are two commands that convert a Texinfo file |
| into an Info file.)@refill |
| |
| Info files are divided into pieces called @dfn{nodes}, each of which |
| contains the discussion of one topic. Each node has a name, and |
| contains both text for the user to read and pointers to other nodes, |
| which are identified by their names. The Info program displays one node |
| at a time, and provides commands with which the user can move to other |
| related nodes.@refill |
| |
| @ifinfo |
| @inforef{Top, info, info}, for more information about using Info.@refill |
| @end ifinfo |
| |
| Each node of an Info file may have any number of child nodes that |
| describe subtopics of the node's topic. The names of child |
| nodes are listed in a @dfn{menu} within the parent node; this |
| allows you to use certain Info commands to move to one of the child |
| nodes. Generally, an Info file is organized like a book. If a node |
| is at the logical level of a chapter, its child nodes are at the level |
| of sections; likewise, the child nodes of sections are at the level |
| of subsections.@refill |
| |
| All the children of any one parent are linked together in a |
| bidirectional chain of `Next' and `Previous' pointers. The `Next' |
| pointer provides a link to the next section, and the `Previous' pointer |
| provides a link to the previous section. This means that all the nodes |
| that are at the level of sections within a chapter are linked together. |
| Normally the order in this chain is the same as the order of the |
| children in the parent's menu. Each child node records the parent node |
| name as its `Up' pointer. The last child has no `Next' pointer, and the |
| first child has the parent both as its `Previous' and as its `Up' |
| pointer.@footnote{In some documents, the first child has no `Previous' |
| pointer. Occasionally, the last child has the node name of the next |
| following higher level node as its `Next' pointer.}@refill |
| |
| The book-like structuring of an Info file into nodes that correspond |
| to chapters, sections, and the like is a matter of convention, not a |
| requirement. The `Up', `Previous', and `Next' pointers of a node can |
| point to any other nodes, and a menu can contain any other nodes. |
| Thus, the node structure can be any directed graph. But it is usually |
| more comprehensible to follow a structure that corresponds to the |
| structure of chapters and sections in a printed book or report.@refill |
| |
| In addition to menus and to `Next', `Previous', and `Up' pointers, Info |
| provides pointers of another kind, called references, that can be |
| sprinkled throughout the text. This is usually the best way to |
| represent links that do not fit a hierarchical structure.@refill |
| |
| Usually, you will design a document so that its nodes match the |
| structure of chapters and sections in the printed output. But there |
| are times when this is not right for the material being discussed. |
| Therefore, Texinfo uses separate commands to specify the node |
| structure for the Info file and the section structure for the printed |
| output.@refill |
| |
| Generally, you enter an Info file through a node that by convention is |
| called @samp{Top}. This node normally contains just a brief summary |
| of the file's purpose, and a large menu through which the rest of the |
| file is reached. From this node, you can either traverse the file |
| systematically by going from node to node, or you can go to a specific |
| node listed in the main menu, or you can search the index menus and |
| then go directly to the node that has the information you want.@refill |
| @c !!! With the standalone Info system you may go to specific nodes |
| @c directly.. |
| |
| If you want to read through an Info file in sequence, as if it were a |
| printed manual, you can get the whole file with the advanced Info |
| command @kbd{g* @key{RET}}. (@inforef{Expert, Advanced Info commands, |
| info}.)@refill |
| |
| @c !!! dir file may be located in one of many places: |
| @c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH |
| @c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH |
| @c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH |
| @c /usr/local/info |
| @c /usr/local/lib/info |
| The @file{dir} file in the @file{info} directory serves as the |
| departure point for the whole Info system. From it, you can reach the |
| `Top' nodes of each of the documents in a complete Info system.@refill |
| |
| @node Printed Books, Formatting Commands, Info Files, Overview |
| @comment node-name, next, previous, up |
| @section Printed Books |
| @cindex Printed book and manual characteristics |
| @cindex Manual characteristics, printed |
| @cindex Book characteristics, printed |
| @cindex Texinfo printed book characteristics |
| @cindex Characteristics, printed books or manuals |
| |
| @cindex Knuth, Donald |
| A Texinfo file can be formatted and typeset as a printed book or manual. |
| To do this, you need @TeX{}, a powerful, sophisticated typesetting |
| program written by Donald Knuth.@footnote{You can also use the |
| @code{texi2roff} program if you do not have @TeX{}; since Texinfo is |
| designed for use with @TeX{}, @code{texi2roff} is not described here. |
| @code{texi2roff} is part of the standard GNU distribution.}@refill |
| |
| A Texinfo-based book is similar to any other typeset, printed work: it |
| can have a title page, copyright page, table of contents, and preface, |
| as well as chapters, numbered or unnumbered sections and subsections, |
| page headers, cross references, footnotes, and indices.@refill |
| |
| You can use Texinfo to write a book without ever having the intention |
| of converting it into on-line information. You can use Texinfo for |
| writing a printed novel, and even to write a printed memo, although |
| this latter application is not recommended since electronic mail is so |
| much easier.@refill |
| |
| @TeX{} is a general purpose typesetting program. Texinfo provides a |
| file called @file{texinfo.tex} that contains information (definitions or |
| @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. |
| (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands |
| to @TeX{} commands, which @TeX{} can then process to create the typeset |
| document.) @file{texinfo.tex} contains the specifications for printing |
| a document.@refill |
| |
| Most often, documents are printed on 8.5 inch by 11 inch |
| pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you |
| can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by |
| 235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper |
| (@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}. |
| Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill |
| |
| By changing the parameters in @file{texinfo.tex}, you can change the |
| size of the printed document. In addition, you can change the style in |
| which the printed document is formatted; for example, you can change the |
| sizes and fonts used, the amount of indentation for each paragraph, the |
| degree to which words are hyphenated, and the like. By changing the |
| specifications, you can make a book look dignified, old and serious, or |
| light-hearted, young and cheery.@refill |
| |
| @TeX{} is freely distributable. It is written in a dialect of Pascal |
| called WEB and can be compiled either in Pascal or (by using a |
| conversion program that comes with the @TeX{} distribution) in C. |
| (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information |
| about @TeX{}.)@refill |
| |
| @TeX{} is very powerful and has a great many features. Because a |
| Texinfo file must be able to present information both on a |
| character-only terminal in Info form and in a typeset book, the |
| formatting commands that Texinfo supports are necessarily |
| limited.@refill |
| |
| @xref{Obtaining TeX, , How to Obtain @TeX{}}. |
| |
| |
| @node Formatting Commands, Conventions, Printed Books, Overview |
| @comment node-name, next, previous, up |
| @section @@-commands |
| @cindex @@-commands |
| @cindex Formatting commands |
| |
| In a Texinfo file, the commands that tell @TeX{} how to typeset the |
| printed manual and tell @code{makeinfo} and |
| @code{texinfo-format-buffer} how to create an Info file are preceded |
| by @samp{@@}; they are called @dfn{@@-commands}. For example, |
| @code{@@node} is the command to indicate a node and @code{@@chapter} |
| is the command to indicate the start of a chapter.@refill |
| |
| @quotation |
| @strong{Please note:} All the @@-commands, with the exception of the |
| @code{@@TeX@{@}} command, must be written entirely in lower |
| case.@refill |
| @end quotation |
| |
| The Texinfo @@-commands are a strictly limited set of constructs. The |
| strict limits make it possible for Texinfo files to be understood both |
| by @TeX{} and by the code that converts them into Info files. You can |
| display Info files on any terminal that displays alphabetic and |
| numeric characters. Similarly, you can print the output generated by |
| @TeX{} on a wide variety of printers.@refill |
| |
| Depending on what they do or what arguments@footnote{The word |
| @dfn{argument} comes from the way it is used in mathematics and does |
| not refer to a disputation between two people; it refers to the |
| information presented to the command. According to the @cite{Oxford |
| English Dictionary}, the word derives from the Latin for @dfn{to make |
| clear, prove}; thus it came to mean `the evidence offered as proof', |
| which is to say, `the information offered', which led to its |
| mathematical meaning. In its other thread of derivation, the word |
| came to mean `to assert in a manner against which others may make |
| counter assertions', which led to the meaning of `argument' as a |
| disputation.} they take, you need to write @@-commands on lines of |
| their own or as part of sentences:@refill |
| |
| @itemize @bullet |
| @item |
| Write a command such as @code{@@noindent} at the beginning of a line as |
| the only text on the line. (@code{@@noindent} prevents the beginning of |
| the next line from being indented as the beginning of a |
| paragraph.)@refill |
| |
| @item |
| Write a command such as @code{@@chapter} at the beginning of a line |
| followed by the command's arguments, in this case the chapter title, on |
| the rest of the line. (@code{@@chapter} creates chapter titles.)@refill |
| |
| @item |
| Write a command such as @code{@@dots@{@}} wherever you wish but usually |
| within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill |
| |
| @item |
| Write a command such as @code{@@code@{@var{sample-code}@}} wherever you |
| wish (but usually within a sentence) with its argument, |
| @var{sample-code} in this example, between the braces. (@code{@@code} |
| marks text as being code.)@refill |
| |
| @item |
| Write a command such as @code{@@example} at the beginning of a line of |
| its own; write the body-text on following lines; and write the matching |
| @code{@@end} command, @code{@@end example} in this case, at the |
| beginning of a line of its own after the body-text. (@code{@@example} |
| @dots{} @code{@@end example} indents and typesets body-text as an |
| example.)@refill |
| @end itemize |
| |
| @noindent |
| @cindex Braces, when to use |
| As a general rule, a command requires braces if it mingles among other |
| text; but it does not need braces if it starts a line of its own. The |
| non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; |
| they do not need braces.@refill |
| |
| As you gain experience with Texinfo, you will rapidly learn how to |
| write the different commands: the different ways to write commands |
| make it easier to write and read Texinfo files than if all commands |
| followed exactly the same syntax. (For details about @@-command |
| syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill |
| |
| @node Conventions, Comments, Formatting Commands, Overview |
| @comment node-name, next, previous, up |
| @section General Syntactic Conventions |
| @cindex General syntactic conventions |
| @cindex Syntactic conventions |
| @cindex Conventions, syntactic |
| |
| All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and |
| @samp{@}} can appear in a Texinfo file and stand for themselves. |
| @samp{@@} is the escape character which introduces commands. |
| @samp{@{} and @samp{@}} should be used only to surround arguments to |
| certain commands. To put one of these special characters into the |
| document, put an @samp{@@} character in front of it, like this: |
| @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill |
| |
| @ifinfo |
| It is customary in @TeX{} to use doubled single-quote characters to |
| begin and end quotations: ` ` and ' ' (but without a space between the |
| two single-quote characters). This convention should be followed in |
| Texinfo files. @TeX{} converts doubled single-quote characters to |
| left- and right-hand doubled quotation marks and Info converts doubled |
| single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill |
| @end ifinfo |
| @iftex |
| It is customary in @TeX{} to use doubled single-quote characters to |
| begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This |
| convention should be followed in Texinfo files. @TeX{} converts |
| doubled single-quote characters to left- and right-hand doubled |
| quotation marks, ``like this'', and Info converts doubled single-quote |
| characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and |
| @w{@tt{ '' }} to @w{@tt{ " }}.@refill |
| @end iftex |
| |
| Use three hyphens in a row, @samp{---}, for a dash---like this. In |
| @TeX{}, a single or even a double hyphen produces a printed dash that |
| is shorter than the usual typeset dash. Info reduces three hyphens to two for |
| display on the screen.@refill |
| |
| To prevent a paragraph from being indented in the printed manual, put |
| the command @code{@@noindent} on a line by itself before the |
| paragraph.@refill |
| |
| If you mark off a region of the Texinfo file with the @code{@@iftex} |
| and @w{@code{@@end iftex}} commands, that region will appear only in |
| the printed copy; in that region, you can use certain commands |
| borrowed from plain @TeX{} that you cannot use in Info. Likewise, if |
| you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo} |
| commands, that region will appear only in the Info file; in that |
| region, you can use Info commands that you cannot use in @TeX{}. |
| Similarly for @code{@@ifhtml} and @code{@@end ifhtml}. |
| @xref{Conditionals}. |
| |
| @cindex Tabs; don't use! |
| @quotation |
| @strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses |
| variable-width fonts, which means that it cannot predefine a tab to work |
| in all circumstances. Consequently, @TeX{} treats tabs like single |
| spaces, and that is not what they look like.@refill |
| |
| @noindent |
| To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple |
| spaces when you press the @key{TAB} key.@refill |
| |
| @noindent |
| Also, you can run @code{untabify} in Emacs to convert tabs in a region |
| to multiple spaces.@refill |
| @end quotation |
| |
| @node Comments, Minimum, Conventions, Overview |
| @comment node-name, next, previous, up |
| @section Comments |
| |
| You can write comments in a Texinfo file that will not appear in |
| either the Info file or the printed manual by using the |
| @code{@@comment} command (which may be abbreviated to @code{@@c}). |
| Such comments are for the person who reads the Texinfo file. All the |
| text on a line that follows either @code{@@comment} or @code{@@c} is a |
| comment; the rest of the line does not appear in either the Info file |
| or the printed manual. (Often, you can write the @code{@@comment} or |
| @code{@@c} in the middle of a line, and only the text that follows after |
| the @code{@@comment} or @code{@@c} command does not appear; but some |
| commands, such as @code{@@settitle} and @code{@@setfilename}, work on a |
| whole line. You cannot use @code{@@comment} or @code{@@c} in a line |
| beginning with such a command.)@refill |
| @cindex Comments |
| @findex comment |
| @findex c @r{(comment)} |
| |
| You can write long stretches of text that will not appear in either |
| the Info file or the printed manual by using the @code{@@ignore} and |
| @code{@@end ignore} commands. Write each of these commands on a line |
| of its own, starting each command at the beginning of the line. Text |
| between these two commands does not appear in the processed output. |
| You can use @code{@@ignore} and @code{@@end ignore} for writing |
| comments. Often, @code{@@ignore} and @code{@@end ignore} is used |
| to enclose a part of the copying permissions that applies to the |
| Texinfo source file of a document, but not to the Info or printed |
| version of the document.@refill |
| @cindex Ignored text |
| @cindex Unprocessed text |
| @findex ignore |
| @c !!! Perhaps include this comment about ignore and ifset: |
| @ignore |
| Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or |
| @code{@@ifclear} conditions is ignored in the sense that it will not |
| contribute to the formatted output. However, TeX and makeinfo must |
| still parse the ignored text, in order to understand when to |
| @emph{stop} ignoring text from the source file; that means that you |
| will still get error messages if you have invalid Texinfo markup |
| within ignored text. |
| @end ignore |
| |
| @node Minimum, Six Parts, Comments, Overview |
| @comment node-name, next, previous, up |
| @section What a Texinfo File Must Have |
| @cindex Minimal Texinfo file (requirements) |
| @cindex Must have in Texinfo file |
| @cindex Required in Texinfo file |
| @cindex Texinfo file minimum |
| |
| By convention, the names of Texinfo files end with one of the |
| extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer |
| extension is preferred since it describes more clearly to a human |
| reader the nature of the file. The shorter extensions are for |
| operating systems that cannot handle long file names.@refill |
| |
| In order to be made into a printed manual and an Info file, a Texinfo |
| file @strong{must} begin with lines like this:@refill |
| |
| @example |
| @group |
| \input texinfo |
| @@setfilename @var{info-file-name} |
| @@settitle @var{name-of-manual} |
| @end group |
| @end example |
| |
| @noindent |
| The contents of the file follow this beginning, and then you @strong{must} end |
| a Texinfo file with a line like this:@refill |
| |
| @example |
| @@bye |
| @end example |
| |
| @findex input @r{(@TeX{} command)} |
| @noindent |
| The @samp{\input texinfo} line tells @TeX{} to use the |
| @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo |
| @@-commands into @TeX{} typesetting commands. (Note the use of the |
| backslash, @samp{\}; this is correct for @TeX{}.) The |
| @samp{@@setfilename} line provides a name for the Info file and tells |
| @TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a |
| title for the page headers (or footers) of the printed manual.@refill |
| |
| The @code{@@bye} line at the end of the file on a line of its own tells |
| the formatters that the file is ended and to stop formatting.@refill |
| |
| Usually, you will not use quite such a spare format, but will include |
| mode setting and start-of-header and end-of-header lines at the |
| beginning of a Texinfo file, like this:@refill |
| |
| @example |
| @group |
| \input texinfo @@c -*-texinfo-*- |
| @@c %**start of header |
| @@setfilename @var{info-file-name} |
| @@settitle @var{name-of-manual} |
| @@c %**end of header |
| @end group |
| @end example |
| |
| @noindent |
| In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into |
| Texinfo mode when you edit the file. |
| |
| The @code{@@c} lines which surround the @samp{@@setfilename} and |
| @samp{@@settitle} lines are optional, but you need them in order to |
| run @TeX{} or Info on just part of the file. (@xref{Start of Header}, |
| for more information.)@refill |
| |
| Furthermore, you will usually provide a Texinfo file with a title |
| page, indices, and the like. But the minimum, which can be useful |
| for short documents, is just the three lines at the beginning and the |
| one line at the end.@refill |
| |
| @node Six Parts, Short Sample, Minimum, Overview |
| @comment node-name, next, previous, up |
| @section Six Parts of a Texinfo File |
| |
| Generally, a Texinfo file contains more than the minimal |
| beginning and end---it usually contains six parts:@refill |
| |
| @table @r |
| @item 1. Header |
| The @dfn{Header} names the file, tells @TeX{} which definitions' file to |
| use, and performs other ``housekeeping'' tasks.@refill |
| |
| @item 2. Summary Description and Copyright |
| The @dfn{Summary Description and Copyright} segment describes the document |
| and contains the copyright notice and copying permissions for the Info |
| file. The segment must be enclosed between @code{@@ifinfo} and |
| @code{@@end ifinfo} commands so that the formatters place it only in the Info |
| file.@refill |
| |
| @item 3. Title and Copyright |
| The @dfn{Title and Copyright} segment contains the title and copyright pages |
| and copying permissions for the printed manual. The segment must be |
| enclosed between @code{@@titlepage} and @code{@@end titlepage} commands. |
| The title and copyright page appear only in the printed @w{manual}.@refill |
| |
| @item 4. `Top' Node and Master Menu |
| The @dfn{Master Menu} contains a complete menu of all the nodes in the whole |
| Info file. It appears only in the Info file, in the `Top' node.@refill |
| |
| @item 5. Body |
| The @dfn{Body} of the document may be structured like a traditional book or |
| encyclopedia or it may be free form.@refill |
| |
| @item 6. End |
| The @dfn{End} contains commands for printing indices and generating |
| the table of contents, and the @code{@@bye} command on a line of its |
| own.@refill |
| @end table |
| |
| @node Short Sample, Acknowledgements, Six Parts, Overview |
| @comment node-name, next, previous, up |
| @section A Short Sample Texinfo File |
| @cindex Sample Texinfo file |
| |
| Here is a complete but very short Texinfo file, in 6 parts. The first |
| three parts of the file, from @samp{\input texinfo} through to |
| @samp{@@end titlepage}, look more intimidating than they are. Most of |
| the material is standard boilerplate; when you write a manual, simply |
| insert the names for your own manual in this segment. (@xref{Beginning a |
| File}.)@refill |
| |
| @noindent |
| In the following, the sample text is @emph{indented}; comments on it are |
| not. The complete file, without any comments, is shown in |
| @ref{Sample Texinfo File}. |
| |
| @subheading Part 1: Header |
| |
| @noindent |
| The header does not appear in either the Info file or the@* |
| printed output. It sets various parameters, including the@* |
| name of the Info file and the title used in the header. |
| |
| @example |
| @group |
| \input texinfo @@c -*-texinfo-*- |
| @@c %**start of header |
| @@setfilename sample.info |
| @@settitle Sample Document |
| @@c %**end of header |
| |
| @@setchapternewpage odd |
| @end group |
| @end example |
| |
| @subheading Part 2: Summary Description and Copyright |
| |
| @noindent |
| The summary description and copyright segment does not@* |
| appear in the printed document. |
| |
| @example |
| @group |
| @@ifinfo |
| This is a short example of a complete Texinfo file. |
| |
| Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. |
| @@end ifinfo |
| @end group |
| @end example |
| |
| @subheading Part 3: Titlepage and Copyright |
| |
| @noindent |
| The titlepage segment does not appear in the Info file. |
| |
| @example |
| @group |
| @@titlepage |
| @@sp 10 |
| @@comment The title is printed in a large font. |
| @@center @@titlefont@{Sample Title@} |
| @end group |
| |
| @group |
| @@c The following two commands start the copyright page. |
| @@page |
| @@vskip 0pt plus 1filll |
| Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. |
| @@end titlepage |
| @end group |
| @end example |
| |
| @subheading Part 4: `Top' Node and Master Menu |
| |
| @noindent |
| The `Top' node contains the master menu for the Info file.@* |
| Since a printed manual uses a table of contents rather than@* |
| a menu, the master menu appears only in the Info file. |
| |
| @example |
| @group |
| @@node Top, First Chapter, (dir), (dir) |
| @@comment node-name, next, previous, up |
| @end group |
| @end example |
| |
| @example |
| @group |
| @@menu |
| * First Chapter:: The first chapter is the |
| only chapter in this sample. |
| * Concept Index:: This index has two entries. |
| @@end menu |
| @end group |
| @end example |
| |
| @subheading Part 5: The Body of the Document |
| |
| @noindent |
| The body segment contains all the text of the document, but not the |
| indices or table of contents. This example illustrates a node and a |
| chapter containing an enumerated list.@refill |
| |
| @example |
| @group |
| @@node First Chapter, Concept Index, Top, Top |
| @@comment node-name, next, previous, up |
| @@chapter First Chapter |
| @@cindex Sample index entry |
| @end group |
| |
| @group |
| This is the contents of the first chapter. |
| @@cindex Another sample index entry |
| @end group |
| |
| @group |
| Here is a numbered list. |
| |
| @@enumerate |
| @@item |
| This is the first item. |
| |
| @@item |
| This is the second item. |
| @@end enumerate |
| @end group |
| |
| @group |
| 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. |
| @end group |
| @end example |
| |
| @subheading Part 6: The End of the Document |
| |
| @noindent |
| The end segment contains commands both for generating an index in a node |
| and unnumbered chapter of its own and for generating the table of |
| contents; and it contains the @code{@@bye} command that marks the end of |
| the document.@refill |
| |
| @example |
| @group |
| @@node Concept Index, , First Chapter, Top |
| @@comment node-name, next, previous, up |
| @@unnumbered Concept Index |
| @end group |
| |
| @group |
| @@printindex cp |
| |
| @@contents |
| @@bye |
| @end group |
| @end example |
| |
| @subheading The Results |
| |
| Here is what the contents of the first chapter of the sample look like: |
| |
| @sp 1 |
| @need 700 |
| @quotation |
| This is the contents of the first chapter. |
| |
| 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. |
| @end quotation |
| |
| @node Acknowledgements, , Short Sample, Overview |
| @comment node-name, next, previous, up |
| @section Acknowledgements |
| |
| @cindex Stallman, Richard M. |
| @cindex Chassell, Robert J. |
| @cindex Berry, Karl |
| Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@: |
| Chassell} revised and extended it, starting with Edition 1.1. Karl |
| Berry made updates for the Texinfo 3.8 and subsequent releases, starting |
| with Edition 2.22. |
| |
| @cindex Pinard, Fran@,{c}ois |
| @cindex Zuhn, David D. |
| @cindex Weisshaus, Melissa |
| Our thanks go out to all who helped improve this work, particularly to |
| Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and |
| reported mistakes and obscurities; our special thanks go to Melissa |
| Weisshaus for her frequent and often tedious reviews of nearly similar |
| editions. Our mistakes are our own. |
| |
| Please send suggestions and corrections to: |
| |
| @example |
| @group |
| @r{Internet address:} |
| bug-texinfo@@prep.ai.mit.edu |
| @end group |
| @end example |
| |
| @noindent |
| Please include the manual's edition number and update date in your messages. |
| |
| @node Texinfo Mode, Beginning a File, Overview, Top |
| @comment node-name, next, previous, up |
| @chapter Using Texinfo Mode |
| @cindex Texinfo mode |
| @cindex Mode, using Texinfo |
| @cindex GNU Emacs |
| @cindex Emacs |
| |
| You may edit a Texinfo file with any text editor you choose. A Texinfo |
| file is no different from any other @sc{ascii} file. However, GNU Emacs |
| comes with a special mode, called Texinfo |
| mode, that provides Emacs commands and tools to help ease your work.@refill |
| |
| This chapter describes features of GNU Emacs' Texinfo mode but not any |
| features of the Texinfo formatting language. If you are reading this |
| manual straight through from the beginning, you may want to skim through |
| this chapter briefly and come back to it after reading succeeding |
| chapters which describe the Texinfo formatting language in |
| detail.@refill |
| |
| @menu |
| * Texinfo Mode Overview:: How Texinfo mode can help you. |
| * Emacs Editing:: Texinfo mode adds to GNU Emacs' general |
| purpose editing features. |
| * Inserting:: How to insert frequently used @@-commands. |
| * Showing the Structure:: How to show the structure of a file. |
| * Updating Nodes and Menus:: How to update or create new nodes and menus. |
| * Info Formatting:: How to format for Info. |
| * Printing:: How to format and print part or all of a file. |
| * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. |
| @end menu |
| |
| @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode |
| @ifinfo |
| @heading Texinfo Mode Overview |
| @end ifinfo |
| |
| Texinfo mode provides special features for working with Texinfo |
| files:@refill |
| |
| @itemize @bullet |
| @item |
| Insert frequently used @@-commands. @refill |
| |
| @item |
| Automatically create @code{@@node} lines. |
| |
| @item |
| Show the structure of a Texinfo source file.@refill |
| |
| @item |
| Automatically create or update the `Next',@* |
| `Previous', and `Up' pointers of a node. |
| |
| @item |
| Automatically create or update menus.@refill |
| |
| @item |
| Automatically create a master menu.@refill |
| |
| @item |
| Format a part or all of a file for Info.@refill |
| |
| @item |
| Typeset and print part or all of a file.@refill |
| @end itemize |
| |
| Perhaps the two most helpful features are those for inserting frequently |
| used @@-commands and for creating node pointers and menus.@refill |
| |
| @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode |
| @section The Usual GNU Emacs Editing Commands |
| |
| In most cases, the usual Text mode commands work the same in Texinfo |
| mode as they do in Text mode. Texinfo mode adds new editing commands |
| and tools to GNU Emacs' general purpose editing features. The major |
| difference concerns filling. In Texinfo mode, the paragraph |
| separation variable and syntax table are redefined so that Texinfo |
| commands that should be on lines of their own are not inadvertently |
| included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) |
| command will refill a paragraph but not mix an indexing command on a |
| line adjacent to it into the paragraph.@refill |
| |
| In addition, Texinfo mode sets the @code{page-delimiter} variable to |
| the value of @code{texinfo-chapter-level-regexp}; by default, this is |
| a regular expression matching the commands for chapters and their |
| equivalents, such as appendices. With this value for the page |
| delimiter, you can jump from chapter title to chapter title with the |
| @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} |
| (@code{backward-page}) commands and narrow to a chapter with the |
| @kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, |
| The GNU Emacs Manual}, for details about the page commands.)@refill |
| |
| You may name a Texinfo file however you wish, but the convention is to |
| end a Texinfo file name with one of the three extensions |
| @file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is |
| preferred, since it is explicit, but a shorter extension may be |
| necessary for operating systems that limit the length of file names. |
| GNU Emacs automatically enters Texinfo mode when you visit a file with |
| a @file{.texinfo} or @file{.texi} |
| extension. Also, Emacs switches to Texinfo mode |
| when you visit a |
| file that has @samp{-*-texinfo-*-} in its first line. If ever you are |
| in another mode and wish to switch to Texinfo mode, type @code{M-x |
| texinfo-mode}.@refill |
| |
| Like all other Emacs features, you can customize or enhance Texinfo |
| mode as you wish. In particular, the keybindings are very easy to |
| change. The keybindings described here are the default or standard |
| ones.@refill |
| |
| @node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode |
| @comment node-name, next, previous, up |
| @section Inserting Frequently Used Commands |
| @cindex Inserting frequently used commands |
| @cindex Frequently used commands, inserting |
| @cindex Commands, inserting them |
| |
| Texinfo mode provides commands to insert various frequently used |
| @@-commands into the buffer. You can use these commands to save |
| keystrokes.@refill |
| |
| The insert commands are invoked by typing @kbd{C-c} twice and then the |
| first letter of the @@-command:@refill |
| |
| @table @kbd |
| @item C-c C-c c |
| @itemx M-x texinfo-insert-@@code |
| @findex texinfo-insert-@@code |
| Insert @code{@@code@{@}} and put the |
| cursor between the braces.@refill |
| |
| @item C-c C-c d |
| @itemx M-x texinfo-insert-@@dfn |
| @findex texinfo-insert-@@dfn |
| Insert @code{@@dfn@{@}} and put the |
| cursor between the braces.@refill |
| |
| @item C-c C-c e |
| @itemx M-x texinfo-insert-@@end |
| @findex texinfo-insert-@@end |
| Insert @code{@@end} and attempt to insert the correct following word, |
| such as @samp{example} or @samp{table}. (This command does not handle |
| nested lists correctly, but inserts the word appropriate to the |
| immediately preceding list.)@refill |
| |
| @item C-c C-c i |
| @itemx M-x texinfo-insert-@@item |
| @findex texinfo-insert-@@item |
| Insert @code{@@item} and put the |
| cursor at the beginning of the next line.@refill |
| |
| @item C-c C-c k |
| @itemx M-x texinfo-insert-@@kbd |
| @findex texinfo-insert-@@kbd |
| Insert @code{@@kbd@{@}} and put the |
| cursor between the braces.@refill |
| |
| @item C-c C-c n |
| @itemx M-x texinfo-insert-@@node |
| @findex texinfo-insert-@@node |
| Insert @code{@@node} and a comment line |
| listing the sequence for the `Next', |
| `Previous', and `Up' nodes. |
| Leave point after the @code{@@node}.@refill |
| |
| @item C-c C-c o |
| @itemx M-x texinfo-insert-@@noindent |
| @findex texinfo-insert-@@noindent |
| Insert @code{@@noindent} and put the |
| cursor at the beginning of the next line.@refill |
| |
| @item C-c C-c s |
| @itemx M-x texinfo-insert-@@samp |
| @findex texinfo-insert-@@samp |
| Insert @code{@@samp@{@}} and put the |
| cursor between the braces.@refill |
| |
| @item C-c C-c t |
| @itemx M-x texinfo-insert-@@table |
| @findex texinfo-insert-@@table |
| Insert @code{@@table} followed by a @key{SPC} |
| and leave the cursor after the @key{SPC}.@refill |
| |
| @item C-c C-c v |
| @itemx M-x texinfo-insert-@@var |
| @findex texinfo-insert-@@var |
| Insert @code{@@var@{@}} and put the |
| cursor between the braces.@refill |
| |
| @item C-c C-c x |
| @itemx M-x texinfo-insert-@@example |
| @findex texinfo-insert-@@example |
| Insert @code{@@example} and put the |
| cursor at the beginning of the next line.@refill |
| |
| @c M-@{ was the binding for texinfo-insert-braces; |
| @c in Emacs 19, backward-paragraph will take this binding. |
| @item C-c C-c @{ |
| @itemx M-x texinfo-insert-braces |
| @findex texinfo-insert-braces |
| Insert @code{@{@}} and put the cursor between the braces.@refill |
| |
| @item C-c C-c @} |
| @itemx C-c C-c ] |
| @itemx M-x up-list |
| @findex up-list |
| Move from between a pair of braces forward past the closing brace. |
| Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which |
| is, however, more mnemonic; hence the two keybindings. (Also, you can |
| move out from between braces by typing @kbd{C-f}.)@refill |
| @end table |
| |
| To put a command such as @w{@code{@@code@{@dots{}@}}} around an |
| @emph{existing} word, position the cursor in front of the word and type |
| @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. |
| The value of the prefix argument tells Emacs how many words following |
| point to include between braces---1 for one word, 2 for two words, and |
| so on. Use a negative argument to enclose the previous word or words. |
| If you do not specify a prefix argument, Emacs inserts the @@-command |
| string and positions the cursor between the braces. This feature works |
| only for those @@-commands that operate on a word or words within one |
| line, such as @code{@@kbd} and @code{@@var}.@refill |
| |
| This set of insert commands was created after analyzing the frequency |
| with which different @@-commands are used in the @cite{GNU Emacs |
| Manual} and the @cite{GDB Manual}. If you wish to add your own insert |
| commands, you can bind a keyboard macro to a key, use abbreviations, |
| or extend the code in @file{texinfo.el}.@refill |
| |
| @findex texinfo-start-menu-description |
| @cindex Menu description, start |
| @cindex Description for menu, start |
| @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert |
| command that works differently from the other insert commands. It |
| inserts a node's section or chapter title in the space for the |
| description in a menu entry line. (A menu entry has three parts, the |
| entry name, the node name, and the description. Only the node name is |
| required, but a description helps explain what the node is about. |
| @xref{Menu Parts, , The Parts of a Menu}.)@refill |
| |
| To use @code{texinfo-start-menu-description}, position point in a menu |
| entry line and type @kbd{C-c C-c C-d}. The command looks for and copies |
| the title that goes with the node name, and inserts the title as a |
| description; it positions point at beginning of the inserted text so you |
| can edit it. The function does not insert the title if the menu entry |
| line already contains a description.@refill |
| |
| This command is only an aid to writing descriptions; it does not do the |
| whole job. You must edit the inserted text since a title tends to use |
| the same words as a node name but a useful description uses different |
| words.@refill |
| |
| @node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode |
| @comment node-name, next, previous, up |
| @section Showing the Section Structure of a File |
| @cindex Showing the section structure of a file |
| @cindex Section structure of a file, showing it |
| @cindex Structure of a file, showing it |
| @cindex Outline of file structure, showing it |
| @cindex Contents-like outline of file structure |
| @cindex File section structure, showing it |
| @cindex Texinfo file section structure, showing it |
| |
| You can show the section structure of a Texinfo file by using the |
| @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command |
| shows the section structure of a Texinfo file by listing the lines |
| that begin with the @@-commands for @code{@@chapter}, |
| @code{@@section}, and the like. It constructs what amounts |
| to a table of contents. These lines are displayed in another buffer |
| called the @samp{*Occur*} buffer. In that buffer, you can position |
| the cursor over one of the lines and use the @kbd{C-c C-c} command |
| (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot |
| in the Texinfo file.@refill |
| |
| @table @kbd |
| @item C-c C-s |
| @itemx M-x texinfo-show-structure |
| @findex texinfo-show-structure |
| Show the @code{@@chapter}, @code{@@section}, and such lines of a |
| Texinfo file.@refill |
| |
| @item C-c C-c |
| @itemx M-x occur-mode-goto-occurrence |
| @findex occur-mode-goto-occurrence |
| Go to the line in the Texinfo file corresponding to the line under the |
| cursor in the @file{*Occur*} buffer.@refill |
| @end table |
| |
| If you call @code{texinfo-show-structure} with a prefix argument by |
| typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the |
| @@-commands for @code{@@chapter}, @code{@@section}, and the like, |
| but also the @code{@@node} lines. (This is how the |
| @code{texinfo-show-structure} command worked without an argument in |
| the first version of Texinfo. It was changed because @code{@@node} |
| lines clutter up the @samp{*Occur*} buffer and are usually not |
| needed.) You can use @code{texinfo-show-structure} with a prefix |
| argument to check whether the `Next', `Previous', and `Up' pointers of |
| an @code{@@node} line are correct.@refill |
| |
| Often, when you are working on a manual, you will be interested only |
| in the structure of the current chapter. In this case, you can mark |
| off the region of the buffer that you are interested in by using the |
| @kbd{C-x n n} (@code{narrow-to-region}) command and |
| @code{texinfo-show-structure} will work on only that region. To see |
| the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). |
| (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more |
| information about the narrowing commands.)@refill |
| |
| @vindex page-delimiter |
| @cindex Page delimiter in Texinfo mode |
| In addition to providing the @code{texinfo-show-structure} command, |
| Texinfo mode sets the value of the page delimiter variable to match |
| the chapter-level @@-commands. This enables you to use the @kbd{C-x |
| ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) |
| commands to move forward and backward by chapter, and to use the |
| @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter. |
| @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information |
| about the page commands.@refill |
| |
| @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode |
| @comment node-name, next, previous, up |
| @section Updating Nodes and Menus |
| @cindex Updating nodes and menus |
| @cindex Create nodes, menus automatically |
| @cindex Insert nodes, menus automatically |
| @cindex Automatically insert nodes, menus |
| |
| Texinfo mode provides commands for automatically creating or updating |
| menus and node pointers. The commands are called ``update'' commands |
| because their most frequent use is for updating a Texinfo file after |
| you have worked on it; but you can use them to insert the `Next', |
| `Previous', and `Up' pointers into an @code{@@node} line that has none and to |
| create menus in a file that has none.@refill |
| |
| If you do not use the updating commands, you need to write menus and |
| node pointers by hand, which is a tedious task.@refill |
| |
| @menu |
| * Updating Commands:: Five major updating commands. |
| * Updating Requirements:: How to structure a Texinfo file for |
| using the updating command. |
| * Other Updating Commands:: How to indent descriptions, insert |
| missing nodes lines, and update |
| nodes in sequence. |
| @end menu |
| |
| @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus |
| @ifinfo |
| @subheading The Updating Commands |
| @end ifinfo |
| |
| You can use the updating commands@refill |
| |
| @itemize @bullet |
| @item |
| to insert or update the `Next', `Previous', and `Up' pointers of a |
| node,@refill |
| |
| @item |
| to insert or update the menu for a section, and@refill |
| |
| @item |
| to create a master menu for a Texinfo source file.@refill |
| @end itemize |
| |
| You can also use the commands to update all the nodes and menus in a |
| region or in a whole Texinfo file.@refill |
| |
| The updating commands work only with conventional Texinfo files, which |
| are structured hierarchically like books. In such files, a structuring |
| command line must follow closely after each @code{@@node} line, except |
| for the `Top' @code{@@node} line. (A @dfn{structuring command line} is |
| a line beginning with @code{@@chapter}, @code{@@section}, or other |
| similar command.) |
| |
| You can write the structuring command line on the line that follows |
| immediately after an @code{@@node} line or else on the line that |
| follows after a single @code{@@comment} line or a single |
| @code{@@ifinfo} line. You cannot interpose more than one line between |
| the @code{@@node} line and the structuring command line; and you may |
| interpose only an @code{@@comment} line or an @code{@@ifinfo} line. |
| |
| Commands which work on a whole buffer require that the `Top' node be |
| followed by a node with an @code{@@chapter} or equivalent-level command. |
| Note that the menu updating commands will not create a main or master |
| menu for a Texinfo file that has only @code{@@chapter}-level nodes! The |
| menu updating commands only create menus @emph{within} nodes for lower level |
| nodes. To create a menu of chapters, you must provide a `Top' |
| node.@refill |
| |
| The menu updating commands remove menu entries that refer to other Info |
| files since they do not refer to nodes within the current buffer. This |
| is a deficiency. Rather than use menu entries, you can use cross |
| references to refer to other Info files. None of the updating commands |
| affect cross references.@refill |
| |
| Texinfo mode has five updating commands that are used most often: two |
| are for updating the node pointers or menu of a single node (or a |
| region); two are for updating every node pointer and menu in a file; |
| and one, the @code{texinfo-master-menu} command, is for creating a |
| master menu for a complete file, and optionally, for updating every |
| node and menu in the whole Texinfo file.@refill |
| |
| The @code{texinfo-master-menu} command is the primary command:@refill |
| |
| @table @kbd |
| @item C-c C-u m |
| @itemx M-x texinfo-master-menu |
| @findex texinfo-master-menu |
| Create or update a master menu that includes all the other menus |
| (incorporating the descriptions from pre-existing menus, if |
| any).@refill |
| |
| With an argument (prefix argument, @kbd{C-u,} if interactive), first create or |
| update all the nodes and all the regular menus in the buffer before |
| constructing the master menu. (@xref{The Top Node, , The Top Node and |
| Master Menu}, for more about a master menu.)@refill |
| |
| For @code{texinfo-master-menu} to work, the Texinfo file must have a |
| `Top' node and at least one subsequent node.@refill |
| |
| After extensively editing a Texinfo file, you can type the following: |
| |
| @example |
| C-u M-x texinfo-master-menu |
| @exdent or |
| C-u C-c C-u m |
| @end example |
| |
| @noindent |
| This updates all the nodes and menus completely and all at once.@refill |
| @end table |
| |
| The other major updating commands do smaller jobs and are designed for |
| the person who updates nodes and menus as he or she writes a Texinfo |
| file.@refill |
| |
| @need 1000 |
| The commands are:@refill |
| |
| @table @kbd |
| @item C-c C-u C-n |
| @itemx M-x texinfo-update-node |
| @findex texinfo-update-node |
| Insert the `Next', `Previous', and `Up' pointers for the node that point is |
| within (i.e., for the @code{@@node} line preceding point). If the |
| @code{@@node} line has pre-existing `Next', `Previous', or `Up' |
| pointers in it, the old pointers are removed and new ones inserted. |
| With an argument (prefix argument, @kbd{C-u}, if interactive), this command |
| updates all @code{@@node} lines in the region (which is the text |
| between point and mark).@refill |
| |
| @item C-c C-u C-m |
| @itemx M-x texinfo-make-menu |
| @findex texinfo-make-menu |
| Create or update the menu in the node that point is within. |
| With an argument (@kbd{C-u} as prefix argument, if |
| interactive), the command makes or updates menus for the |
| nodes which are either within or a part of the |
| region.@refill |
| |
| Whenever @code{texinfo-make-menu} updates an existing menu, the |
| descriptions from that menu are incorporated into the new menu. This |
| is done by copying descriptions from the existing menu to the entries |
| in the new menu that have the same node names. If the node names are |
| different, the descriptions are not copied to the new menu.@refill |
| |
| @item C-c C-u C-e |
| @itemx M-x texinfo-every-node-update |
| @findex texinfo-every-node-update |
| Insert or update the `Next', `Previous', and `Up' pointers for every |
| node in the buffer.@refill |
| |
| @item C-c C-u C-a |
| @itemx M-x texinfo-all-menus-update |
| @findex texinfo-all-menus-update |
| Create or update all the menus in the buffer. With an argument |
| (@kbd{C-u} as prefix argument, if interactive), first insert |
| or update all the node |
| pointers before working on the menus.@refill |
| |
| If a master menu exists, the @code{texinfo-all-menus-update} command |
| updates it; but the command does not create a new master menu if none |
| already exists. (Use the @code{texinfo-master-menu} command for |
| that.)@refill |
| |
| When working on a document that does not merit a master menu, you can |
| type the following: |
| |
| @example |
| C-u C-c C-u C-a |
| @exdent or |
| C-u M-x texinfo-all-menus-update |
| @end example |
| |
| @noindent |
| This updates all the nodes and menus.@refill |
| @end table |
| |
| The @code{texinfo-column-for-description} variable specifies the |
| column to which menu descriptions are indented. By default, the value |
| is 32 although it is often useful to reduce it to as low as 24. You |
| can set the variable with the @kbd{M-x edit-options} command |
| (@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs |
| Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, |
| , Examining and Setting Variables, emacs, The GNU Emacs |
| Manual}).@refill |
| |
| Also, the @code{texinfo-indent-menu-description} command may be used to |
| indent existing menu descriptions to a specified column. Finally, if |
| you wish, you can use the @code{texinfo-insert-node-lines} command to |
| insert missing @code{@@node} lines into a file. (@xref{Other Updating |
| Commands}, for more information.)@refill |
| |
| @node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus |
| @comment node-name, next, previous, up |
| @subsection Updating Requirements |
| @cindex Updating requirements |
| @cindex Requirements for updating commands |
| |
| To use the updating commands, you must organize the Texinfo file |
| hierarchically with chapters, sections, subsections, and the like. |
| When you construct the hierarchy of the manual, do not `jump down' |
| more than one level at a time: you can follow the `Top' node with a |
| chapter, but not with a section; you can follow a chapter with a |
| section, but not with a subsection. However, you may `jump up' any |
| number of levels at one time---for example, from a subsection to a |
| chapter.@refill |
| |
| Each @code{@@node} line, with the exception of the line for the `Top' |
| node, must be followed by a line with a structuring command such as |
| @code{@@chapter}, @code{@@section}, or |
| @code{@@unnumberedsubsec}.@refill |
| |
| Each @code{@@node} line/structuring-command line combination |
| must look either like this:@refill |
| |
| @example |
| @group |
| @@node Comments, Minimum, Conventions, Overview |
| @@comment node-name, next, previous, up |
| @@section Comments |
| @end group |
| @end example |
| |
| or like this (without the @code{@@comment} line): |
| |
| @example |
| @group |
| @@node Comments, Minimum, Conventions, Overview |
| @@section Comments |
| @end group |
| @end example |
| |
| @noindent |
| In this example, `Comments' is the name of both the node and the |
| section. The next node is called `Minimum' and the previous node is |
| called `Conventions'. The `Comments' section is within the `Overview' |
| node, which is specified by the `Up' pointer. (Instead of an |
| @code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill |
| |
| If a file has a `Top' node, it must be called @samp{top} or @samp{Top} |
| and be the first node in the file.@refill |
| |
| The menu updating commands create a menu of sections within a chapter, |
| a menu of subsections within a section, and so on. This means that |
| you must have a `Top' node if you want a menu of chapters.@refill |
| |
| Incidentally, the @code{makeinfo} command will create an Info file for |
| a hierarchically organized Texinfo file that lacks `Next', `Previous' |
| and `Up' pointers. Thus, if you can be sure that your Texinfo file |
| will be formatted with @code{makeinfo}, you have no need for the |
| `update node' commands. (@xref{Create an Info File, , Creating an |
| Info File}, for more information about @code{makeinfo}.) However, |
| both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands |
| require that you insert menus in the file.@refill |
| |
| @node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus |
| @comment node-name, next, previous, up |
| @subsection Other Updating Commands |
| |
| In addition to the five major updating commands, Texinfo mode |
| possesses several less frequently used updating commands:@refill |
| |
| @table @kbd |
| @item M-x texinfo-insert-node-lines |
| @findex texinfo-insert-node-lines |
| Insert @code{@@node} lines before the @code{@@chapter}, |
| @code{@@section}, and other sectioning commands wherever they are |
| missing throughout a region in a Texinfo file.@refill |
| |
| With an argument (@kbd{C-u} as prefix argument, if interactive), the |
| @code{texinfo-insert-node-lines} command not only inserts |
| @code{@@node} lines but also inserts the chapter or section titles as |
| the names of the corresponding nodes. In addition, it inserts the |
| titles as node names in pre-existing @code{@@node} lines that lack |
| names. Since node names should be more concise than section or |
| chapter titles, you must manually edit node names so inserted.@refill |
| |
| For example, the following marks a whole buffer as a region and inserts |
| @code{@@node} lines and titles throughout:@refill |
| |
| @example |
| C-x h C-u M-x texinfo-insert-node-lines |
| @end example |
| |
| (Note that this command inserts titles as node names in @code{@@node} |
| lines; the @code{texinfo-start-menu-description} command |
| (@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles |
| as descriptions in menu entries, a different action. However, in both |
| cases, you need to edit the inserted text.)@refill |
| |
| @item M-x texinfo-multiple-files-update |
| @findex texinfo-multiple-files-update @r{(in brief)} |
| Update nodes and menus in a document built from several separate files. |
| With @kbd{C-u} as a prefix argument, create and insert a master menu in |
| the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first |
| update all the menus and all the `Next', `Previous', and `Up' pointers |
| of all the included files before creating and inserting a master menu in |
| the outer file. The @code{texinfo-multiple-files-update} command is |
| described in the appendix on @code{@@include} files. |
| @ifinfo |
| @xref{texinfo-multiple-files-update}.@refill |
| @end ifinfo |
| @iftex |
| @xref{texinfo-multiple-files-update, , |
| @code{texinfo-multiple-files-update}}.@refill |
| @end iftex |
| |
| @item M-x texinfo-indent-menu-description |
| @findex texinfo-indent-menu-description |
| Indent every description in the menu following point to the specified |
| column. You can use this command to give yourself more space for |
| descriptions. With an argument (@kbd{C-u} as prefix argument, if |
| interactive), the @code{texinfo-indent-menu-description} command indents |
| every description in every menu in the region. However, this command |
| does not indent the second and subsequent lines of a multi-line |
| description.@refill |
| |
| @item M-x texinfo-sequential-node-update |
| @findex texinfo-sequential-node-update |
| Insert the names of the nodes immediately following and preceding the |
| current node as the `Next' or `Previous' pointers regardless of those |
| nodes' hierarchical level. This means that the `Next' node of a |
| subsection may well be the next chapter. Sequentially ordered nodes are |
| useful for novels and other documents that you read through |
| sequentially. (However, in Info, the @code{g* @key{RET}} command lets |
| you look through the file sequentially, so sequentially ordered nodes |
| are not strictly necessary.) With an argument (prefix argument, if |
| interactive), the @code{texinfo-sequential-node-update} command |
| sequentially updates all the nodes in the region.@refill |
| @end table |
| |
| @node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode |
| @comment node-name, next, previous, up |
| @section Formatting for Info |
| @cindex Formatting for Info |
| @cindex Running an Info formatter |
| @cindex Info formatting |
| |
| Texinfo mode provides several commands for formatting part or all of a |
| Texinfo file for Info. Often, when you are writing a document, you |
| want to format only part of a file---that is, a region.@refill |
| |
| You can use either the @code{texinfo-format-region} or the |
| @code{makeinfo-region} command to format a region:@refill |
| |
| @table @kbd |
| @findex texinfo-format-region |
| @item C-c C-e C-r |
| @itemx M-x texinfo-format-region |
| @itemx C-c C-m C-r |
| @itemx M-x makeinfo-region |
| Format the current region for Info.@refill |
| @end table |
| |
| You can use either the @code{texinfo-format-buffer} or the |
| @code{makeinfo-buffer} command to format a whole buffer:@refill |
| |
| @table @kbd |
| @findex texinfo-format-buffer |
| @item C-c C-e C-b |
| @itemx M-x texinfo-format-buffer |
| @itemx C-c C-m C-b |
| @itemx M-x makeinfo-buffer |
| Format the current buffer for Info.@refill |
| @end table |
| |
| @need 1000 |
| For example, after writing a Texinfo file, you can type the following: |
| |
| @example |
| C-u C-c C-u m |
| @exdent or |
| C-u M-x texinfo-master-menu |
| @end example |
| |
| @noindent |
| This updates all the nodes and menus. Then type the following to create |
| an Info file: |
| |
| @example |
| C-c C-m C-b |
| @exdent or |
| M-x makeinfo-buffer |
| @end example |
| |
| For @TeX{} or the Info formatting commands to work, the file @emph{must} |
| include a line that has @code{@@setfilename} in its header.@refill |
| |
| @xref{Create an Info File}, for details about Info formatting.@refill |
| |
| @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode |
| @comment node-name, next, previous, up |
| @section Formatting and Printing |
| @cindex Formatting for printing |
| @cindex Printing a region or buffer |
| @cindex Region formatting and printing |
| @cindex Buffer formatting and printing |
| @cindex Part of file formatting and printing |
| |
| Typesetting and printing a Texinfo file is a multi-step process in which |
| you first create a file for printing (called a @sc{dvi} file), and then |
| print the file. Optionally, you may also create indices. To do this, |
| you must run the @code{texindex} command after first running the |
| @code{tex} typesetting command; and then you must run the @code{tex} |
| command again. Or else run the @code{texi2dvi} command which |
| automatically creates indices as needed.@refill |
| |
| Often, when you are writing a document, you want to typeset and print |
| only part of a file to see what it will look like. You can use the |
| @code{texinfo-tex-region} and related commands for this purpose. Use |
| the @code{texinfo-tex-buffer} command to format all of a |
| buffer.@refill |
| |
| @table @kbd |
| @item C-c C-t C-b |
| @itemx M-x texinfo-tex-buffer |
| @findex texinfo-tex-buffer |
| Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the |
| buffer, this command automatically creates or updates indices as |
| needed.@refill |
| |
| @item C-c C-t C-r |
| @itemx M-x texinfo-tex-region |
| @findex texinfo-tex-region |
| Run @TeX{} on the region.@refill |
| |
| @item C-c C-t C-i |
| @itemx M-x texinfo-texindex |
| Run @code{texindex} to sort the indices of a Texinfo file formatted with |
| @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does |
| not run @code{texindex} automatically; it only runs the @code{tex} |
| typesetting command. You must run the @code{texinfo-tex-region} command |
| a second time after sorting the raw index files with the @code{texindex} |
| command. (Usually, you do not format an index when you format a region, |
| only when you format a buffer. Now that the @code{texi2dvi} command |
| exists, there is no little need for this command.)@refill |
| |
| @item C-c C-t C-p |
| @itemx M-x texinfo-tex-print |
| @findex texinfo-tex-print |
| Print the file (or the part of the file) previously formatted with |
| @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill |
| @end table |
| |
| For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the |
| file @emph{must} start with a @samp{\input texinfo} line and must |
| include an @code{@@settitle} line. The file must end with @code{@@bye} |
| on a line by itself. (When you use @code{texinfo-tex-region}, you must |
| surround the @code{@@settitle} line with start-of-header and |
| end-of-header lines.)@refill |
| |
| @xref{Format/Print Hardcopy}, for a description of the other @TeX{} related |
| commands, such as @code{tex-show-print-queue}.@refill |
| |
| @node Texinfo Mode Summary, , Printing, Texinfo Mode |
| @comment node-name, next, previous, up |
| @section Texinfo Mode Summary |
| |
| In Texinfo mode, each set of commands has default keybindings that |
| begin with the same keys. All the commands that are custom-created |
| for Texinfo mode begin with @kbd{C-c}. The keys are somewhat |
| mnemonic.@refill |
| |
| @subheading Insert Commands |
| |
| The insert commands are invoked by typing @kbd{C-c} twice and then the |
| first letter of the @@-command to be inserted. (It might make more |
| sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but |
| @kbd{C-c C-c} is quick to type.)@refill |
| |
| @example |
| C-c C-c c @r{Insert} @samp{@@code}. |
| C-c C-c d @r{Insert} @samp{@@dfn}. |
| C-c C-c e @r{Insert} @samp{@@end}. |
| C-c C-c i @r{Insert} @samp{@@item}. |
| C-c C-c n @r{Insert} @samp{@@node}. |
| C-c C-c s @r{Insert} @samp{@@samp}. |
| C-c C-c v @r{Insert} @samp{@@var}. |
| C-c C-c @{ @r{Insert braces.} |
| C-c C-c ] |
| C-c C-c @} @r{Move out of enclosing braces.} |
| |
| @group |
| C-c C-c C-d @r{Insert a node's section title} |
| @r{in the space for the description} |
| @r{in a menu entry line.} |
| @end group |
| @end example |
| |
| @subheading Show Structure |
| |
| The @code{texinfo-show-structure} command is often used within a |
| narrowed region.@refill |
| |
| @example |
| C-c C-s @r{List all the headings.} |
| @end example |
| |
| @subheading The Master Update Command |
| |
| The @code{texinfo-master-menu} command creates a master menu; and can |
| be used to update every node and menu in a file as well.@refill |
| |
| @example |
| @group |
| C-c C-u m |
| M-x texinfo-master-menu |
| @r{Create or update a master menu.} |
| @end group |
| |
| @group |
| C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} |
| @r{create or update all nodes and regular} |
| @r{menus, and then create a master menu.} |
| @end group |
| @end example |
| |
| @subheading Update Pointers |
| |
| The update pointer commands are invoked by typing @kbd{C-c C-u} and |
| then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for |
| @code{texinfo-every-node-update}.@refill |
| |
| @example |
| C-c C-u C-n @r{Update a node.} |
| C-c C-u C-e @r{Update every node in the buffer.} |
| @end example |
| |
| @subheading Update Menus |
| |
| Invoke the update menu commands by typing @kbd{C-c C-u} |
| and then either @kbd{C-m} for @code{texinfo-make-menu} or |
| @kbd{C-a} for @code{texinfo-all-menus-update}. To update |
| both nodes and menus at the same time, precede @kbd{C-c C-u |
| C-a} with @kbd{C-u}.@refill |
| |
| @example |
| C-c C-u C-m @r{Make or update a menu.} |
| |
| @group |
| C-c C-u C-a @r{Make or update all} |
| @r{menus in a buffer.} |
| @end group |
| |
| @group |
| C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} |
| @r{first create or update all nodes and} |
| @r{then create or update all menus.} |
| @end group |
| @end example |
| |
| @subheading Format for Info |
| |
| The Info formatting commands that are written in Emacs Lisp are |
| invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region |
| or @kbd{C-b} for the whole buffer.@refill |
| |
| The Info formatting commands that are written in C and based on the |
| @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then |
| either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill |
| |
| @need 800 |
| @noindent |
| Use the @code{texinfo-format@dots{}} commands: |
| |
| @example |
| @group |
| C-c C-e C-r @r{Format the region.} |
| C-c C-e C-b @r{Format the buffer.} |
| @end group |
| @end example |
| |
| @need 750 |
| @noindent |
| Use @code{makeinfo}: |
| |
| @example |
| C-c C-m C-r @r{Format the region.} |
| C-c C-m C-b @r{Format the buffer.} |
| C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} |
| C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} |
| @end example |
| |
| @subheading Typeset and Print |
| |
| The @TeX{} typesetting and printing commands are invoked by typing |
| @kbd{C-c C-t} and then another control command: @kbd{C-r} for |
| @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, |
| and so on.@refill |
| |
| @example |
| C-c C-t C-r @r{Run @TeX{} on the region.} |
| C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} |
| C-c C-t C-i @r{Run} @code{texindex}. |
| C-c C-t C-p @r{Print the @sc{dvi} file.} |
| C-c C-t C-q @r{Show the print queue.} |
| C-c C-t C-d @r{Delete a job from the print queue.} |
| C-c C-t C-k @r{Kill the current @TeX{} formatting job.} |
| C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} |
| C-c C-t C-l @r{Recenter the output buffer.} |
| @end example |
| |
| @subheading Other Updating Commands |
| |
| The `other updating commands' do not have standard keybindings because |
| they are rarely used. |
| |
| @example |
| @group |
| M-x texinfo-insert-node-lines |
| @r{Insert missing @code{@@node} lines in region.} |
| @r{With @kbd{C-u} as a prefix argument,} |
| @r{use section titles as node names.} |
| @end group |
| |
| @group |
| M-x texinfo-multiple-files-update |
| @r{Update a multi-file document.} |
| @r{With @kbd{C-u 2} as a prefix argument,} |
| @r{create or update all nodes and menus} |
| @r{in all included files first.} |
| @end group |
| |
| @group |
| M-x texinfo-indent-menu-description |
| @r{Indent descriptions.} |
| @end group |
| |
| @group |
| M-x texinfo-sequential-node-update |
| @r{Insert node pointers in strict sequence.} |
| @end group |
| @end example |
| |
| @node Beginning a File, Ending a File, Texinfo Mode, Top |
| @comment node-name, next, previous, up |
| @chapter Beginning a Texinfo File |
| @cindex Beginning a Texinfo file |
| @cindex Texinfo file beginning |
| @cindex File beginning |
| |
| Certain pieces of information must be provided at the beginning of a |
| Texinfo file, such as the name of the file and the title of the |
| document.@refill |
| |
| @menu |
| * Four Parts:: Four parts begin a Texinfo file. |
| * Sample Beginning:: Here is a sample beginning for a Texinfo file. |
| * Header:: The very beginning of a Texinfo file. |
| * Info Summary and Permissions:: Summary and copying permissions for Info. |
| * Titlepage & Copyright Page:: Creating the title and copyright pages. |
| * The Top Node:: Creating the `Top' node and master menu. |
| * Software Copying Permissions:: Ensure that you and others continue to |
| have the right to use and share software. |
| @end menu |
| |
| @node Four Parts, Sample Beginning, Beginning a File, Beginning a File |
| @ifinfo |
| @heading Four Parts Begin a File |
| @end ifinfo |
| |
| Generally, the beginning of a Texinfo file has four parts:@refill |
| |
| @enumerate |
| @item |
| The header, delimited by special comment lines, that includes the |
| commands for naming the Texinfo file and telling @TeX{} what |
| definitions' file to use when processing the Texinfo file.@refill |
| |
| @item |
| A short statement of what the file is about, with a copyright notice |
| and copying permissions. This is enclosed in @code{@@ifinfo} and |
| @code{@@end ifinfo} commands so that the formatters place it only |
| in the Info file.@refill |
| |
| @item |
| A title page and copyright page, with a copyright notice and copying |
| permissions. This is enclosed between @code{@@titlepage} and |
| @code{@@end titlepage} commands. The title and copyright page appear |
| only in the printed @w{manual}.@refill |
| |
| @item |
| The `Top' node that contains a menu for the whole Info file. The |
| contents of this node appear only in the Info file.@refill |
| @end enumerate |
| |
| Also, optionally, you may include the copying conditions for a program |
| and a warranty disclaimer. The copying section will be followed by an |
| introduction or else by the first chapter of the manual.@refill |
| |
| Since the copyright notice and copying permissions for the Texinfo |
| document (in contrast to the copying permissions for a program) are in |
| parts that appear only in the Info file or only in the printed manual, |
| this information must be given twice.@refill |
| |
| @node Sample Beginning, Header, Four Parts, Beginning a File |
| @comment node-name, next, previous, up |
| @section Sample Texinfo File Beginning |
| |
| The following sample shows what is needed.@refill |
| |
| @example |
| \input texinfo @@c -*-texinfo-*- |
| @@c %**start of header |
| @@setfilename @var{name-of-info-file} |
| @@settitle @var{name-of-manual} |
| @@setchapternewpage odd |
| @@c %**end of header |
| |
| @@ifinfo |
| This file documents @dots{} |
| |
| Copyright @var{year} @var{copyright-owner} |
| |
| @group |
| Permission is granted to @dots{} |
| @@end ifinfo |
| @end group |
| |
| @group |
| @@c This title page illustrates only one of the |
| @@c two methods of forming a title page. |
| @end group |
| |
| @group |
| @@titlepage |
| @@title @var{name-of-manual-when-printed} |
| @@subtitle @var{subtitle-if-any} |
| @@subtitle @var{second-subtitle} |
| @@author @var{author} |
| @end group |
| |
| @group |
| @@c The following two commands |
| @@c start the copyright page. |
| @@page |
| @@vskip 0pt plus 1filll |
| Copyright @@copyright@{@} @var{year} @var{copyright-owner} |
| @end group |
| |
| Published by @dots{} |
| |
| Permission is granted to @dots{} |
| @@end titlepage |
| |
| @@node Top, Overview, (dir), (dir) |
| |
| @@ifinfo |
| This document describes @dots{} |
| |
| This document applies to version @dots{} |
| of the program named @dots{} |
| @@end ifinfo |
| |
| @group |
| @@menu |
| * Copying:: Your rights and freedoms. |
| * First Chapter:: Getting started @dots{} |
| * Second Chapter:: @dots{} |
| @dots{} |
| @dots{} |
| @@end menu |
| @end group |
| |
| @group |
| @@node First Chapter, Second Chapter, top, top |
| @@comment node-name, next, previous, up |
| @@chapter First Chapter |
| @@cindex Index entry for First Chapter |
| @end group |
| @end example |
| |
| @node Header, Info Summary and Permissions, Sample Beginning, Beginning a File |
| @comment node-name, next, previous, up |
| @section The Texinfo File Header |
| @cindex Header for Texinfo files |
| @cindex Texinfo file header |
| |
| Texinfo files start with at least three lines that provide Info and |
| @TeX{} with necessary information. These are the @code{\input |
| texinfo} line, the @code{@@settitle} line, and the |
| @code{@@setfilename} line. If you want to run @TeX{} on just a part |
| of the Texinfo File, you must write the @code{@@settitle} |
| and @code{@@setfilename} lines between start-of-header and end-of-header |
| lines.@refill |
| |
| Thus, the beginning of a Texinfo file looks like this: |
| |
| @example |
| @group |
| \input texinfo @@c -*-texinfo-*- |
| @@setfilename sample.info |
| @@settitle Sample Document |
| @end group |
| @end example |
| |
| @noindent |
| or else like this: |
| |
| @example |
| @group |
| \input texinfo @@c -*-texinfo-*- |
| @@c %**start of header |
| @@setfilename sample.info |
| @@settitle Sample Document |
| @@c %**end of header |
| @end group |
| @end example |
| |
| @menu |
| * First Line:: The first line of a Texinfo file. |
| * Start of Header:: Formatting a region requires this. |
| * setfilename:: Tell Info the name of the Info file. |
| * settitle:: Create a title for the printed work. |
| * setchapternewpage:: Start chapters on right-hand pages. |
| * paragraphindent:: An option to specify paragraph indentation. |
| * End of Header:: Formatting a region requires this. |
| @end menu |
| |
| @node First Line, Start of Header, Header, Header |
| @comment node-name, next, previous, up |
| @subsection The First Line of a Texinfo File |
| @cindex First line of a Texinfo file |
| @cindex Beginning line of a Texinfo file |
| @cindex Header of a Texinfo file |
| |
| Every Texinfo file that is to be the top-level input to @TeX{} must begin |
| with a line that looks like this:@refill |
| |
| @example |
| \input texinfo @@c -*-texinfo-*- |
| @end example |
| |
| @noindent |
| This line serves two functions: |
| |
| @enumerate |
| @item |
| When the file is processed by @TeX{}, the @code{\input texinfo} command |
| tells @TeX{} to load the macros needed for processing a Texinfo file. |
| These are in a file called @file{texinfo.tex}, which is usually located |
| in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash, |
| @samp{\}, to mark the beginning of a command, just as Texinfo uses |
| @code{@@}. The @file{texinfo.tex} file causes the switch from @samp{\} |
| to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which |
| is why it appears at the beginning of the file.@refill |
| |
| @item |
| When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode |
| specification tells Emacs to use Texinfo mode.@refill |
| @end enumerate |
| |
| @node Start of Header, setfilename, First Line, Header |
| @comment node-name, next, previous, up |
| @subsection Start of Header |
| @cindex Start of header line |
| |
| Write a start-of-header line on the second line of a Texinfo file. |
| Follow the start-of-header line with @code{@@setfilename} and |
| @code{@@settitle} lines and, optionally, with other command lines, such |
| as @code{@@smallbook} or @code{@@footnotestyle}; and then by an |
| end-of-header line (@pxref{End of Header}).@refill |
| |
| With these lines, you can format part of a Texinfo file for Info or |
| typeset part for printing.@refill |
| |
| A start-of-header line looks like this:@refill |
| |
| @example |
| @@c %**start of header |
| @end example |
| |
| The odd string of characters, @samp{%**}, is to ensure that no other |
| comment is accidentally taken for a start-of-header line.@refill |
| |
| @node setfilename, settitle, Start of Header, Header |
| @comment node-name, next, previous, up |
| @subsection @code{@@setfilename} |
| @cindex Info file requires @code{@@setfilename} |
| @findex setfilename |
| |
| In order to serve as the primary input file for either @code{makeinfo} |
| or @TeX{}, a Texinfo file must contain a line that looks like this: |
| |
| @example |
| @@setfilename @var{info-file-name} |
| @end example |
| |
| Write the @code{@@setfilename} command at the beginning of a line and |
| follow it on the same line by the Info file name. Do not write |
| anything else on the line; anything on the line after the command is |
| considered part of the file name, including a comment.@refill |
| |
| The @code{@@setfilename} line specifies the name of the Info file to be |
| generated. This name should be different from the name of the Texinfo |
| file. There are two conventions for choosing the name: you can either |
| remove the @samp{.tex} extension from the input file name, or replace it |
| with the @samp{.info} extension. |
| |
| Some operating systems cannot handle long file names. You can run into |
| a problem even when the file name you specify is itself short enough. |
| This occurs because the Info formatters split a long Info file into |
| short indirect subfiles, and name them by appending `-1', `-2', @dots{}, |
| `-10', `-11', and so on, to the original file name. (@xref{Tag and |
| Split Files, , Tag Files and Split Files}.) The subfile name |
| @file{texinfo.info-10}, for example, is too long for some systems; so |
| the Info file name for this document is @file{texinfo} rather than |
| @file{texinfo.info}.@refill |
| |
| The Info formatting commands ignore everything written before the |
| @code{@@setfilename} line, which is why the very first line of |
| the file (the @code{\input} line) does not need to be commented out. |
| |
| The @code{@@setfilename} line produces no output when you typeset a |
| printed manual, but is does an essential job: it opens the index, |
| cross-reference, and other auxiliary files used by Texinfo. |
| |
| @node settitle, setchapternewpage, setfilename, Header |
| @comment node-name, next, previous, up |
| @subsection @code{@@settitle} |
| @findex settitle |
| |
| In order to be made into a printed manual, a Texinfo file must contain |
| a line that looks like this:@refill |
| |
| @example |
| @@settitle @var{title} |
| @end example |
| |
| Write the @code{@@settitle} command at the beginning of a line and |
| follow it on the same line by the title. This tells @TeX{} the title |
| to use in a header or footer. Do not write anything else on the line; |
| anything on the line after the command is considered part of the |
| title, including a comment.@refill |
| |
| Conventionally, when @TeX{} formats a Texinfo file for double-sided |
| output, the title is printed in the left-hand (even-numbered) page |
| headings and the current chapter title is printed in the right-hand |
| (odd-numbered) page headings. (@TeX{} learns the title of each chapter |
| from each @code{@@chapter} command.) Page footers are not |
| printed.@refill |
| |
| Even if you are printing in a single-sided style, @TeX{} looks for an |
| @code{@@settitle} command line, in case you include the manual title |
| in the heading. @refill |
| |
| The @code{@@settitle} command should precede everything that generates |
| actual output in @TeX{}.@refill |
| |
| Although the title in the @code{@@settitle} command is usually the |
| same as the title on the title page, it does not affect the title as |
| it appears on the title page. Thus, the two do not need not match |
| exactly; and the title in the @code{@@settitle} command can be a |
| shortened or expanded version of the title as it appears on the title |
| page. (@xref{titlepage, , @code{@@titlepage}}.)@refill |
| |
| @TeX{} prints page headings only for that text that comes after the |
| @code{@@end titlepage} command in the Texinfo file, or that comes |
| after an @code{@@headings} command that turns on headings. |
| (@xref{headings on off, , The @code{@@headings} Command}, for more |
| information.)@refill |
| |
| You may, if you wish, create your own, customized headings and |
| footings. @xref{Headings, , Page Headings}, for a detailed discussion |
| of this process.@refill |
| |
| @node setchapternewpage, paragraphindent, settitle, Header |
| @comment node-name, next, previous, up |
| @subsection @code{@@setchapternewpage} |
| @cindex Starting chapters |
| @cindex Pages, starting odd |
| @findex setchapternewpage |
| |
| In a book or a manual, text is usually printed on both sides of the |
| paper, chapters start on right-hand pages, and right-hand pages have |
| odd numbers. But in short reports, text often is printed only on one |
| side of the paper. Also in short reports, chapters sometimes do not |
| start on new pages, but are printed on the same page as the end of the |
| preceding chapter, after a small amount of vertical whitespace.@refill |
| |
| You can use the @code{@@setchapternewpage} command with various |
| arguments to specify how @TeX{} should start chapters and whether it |
| should typeset pages for printing on one or both sides of the paper |
| (single-sided or double-sided printing).@refill |
| |
| Write the @code{@@setchapternewpage} command at the beginning of a |
| line followed by its argument.@refill |
| |
| For example, you would write the following to cause each chapter to |
| start on a fresh odd-numbered page:@refill |
| |
| @example |
| @@setchapternewpage odd |
| @end example |
| |
| You can specify one of three alternatives with the |
| @code{@@setchapternewpage} command:@refill |
| |
| @table @asis |
| @ignore |
| @item No @code{@@setchapternewpage} command |
| If the Texinfo file does not contain an @code{@@setchapternewpage} |
| command before the @code{@@titlepage} command, @TeX{} automatically |
| begins chapters on new pages and prints headings in the standard |
| format for single-sided printing. This is the conventional format for |
| single-sided printing.@refill |
| |
| The result is exactly the same as when you write |
| @code{@@setchapternewpage on}.@refill |
| @end ignore |
| @item @code{@@setchapternewpage off} |
| Cause @TeX{} to typeset a new chapter on the same page as the last |
| chapter, after skipping some vertical whitespace. Also, cause @TeX{} to |
| format page headers for single-sided printing. (You can override the |
| headers format with the @code{@@headings double} command; see |
| @ref{headings on off, , The @code{@@headings} Command}.)@refill |
| |
| @item @code{@@setchapternewpage on} |
| Cause @TeX{} to start new chapters on new pages and to typeset page |
| headers for single-sided printing. This is the form most often |
| used for short reports.@refill |
| |
| This alternative is the default.@refill |
| |
| @item @code{@@setchapternewpage odd} |
| Cause @TeX{} to start new chapters on new, odd-numbered pages |
| (right-handed pages) and to typeset for double-sided printing. This is |
| the form most often used for books and manuals.@refill |
| @end table |
| |
| @noindent |
| Texinfo does not have an @code{@@setchapternewpage even} command.@refill |
| |
| @noindent |
| (You can countermand or modify an @code{@@setchapternewpage} command |
| with an @code{@@headings} command. @xref{headings on off, , The |
| @code{@@headings} Command}.)@refill |
| |
| At the beginning of a manual or book, pages are not numbered---for |
| example, the title and copyright pages of a book are not numbered. |
| By convention, table of contents pages are numbered with roman |
| numerals and not in sequence with the rest of the document.@refill |
| |
| Since an Info file does not have pages, the @code{@@setchapternewpage} |
| command has no effect on it.@refill |
| |
| Usually, you do not write an @code{@@setchapternewpage} command for |
| single-sided printing, but accept the default which is to typeset for |
| single-sided printing and to start new chapters on new pages. Usually, |
| you write an @code{@@setchapternewpage odd} command for double-sided |
| printing.@refill |
| |
| @node paragraphindent, End of Header, setchapternewpage, Header |
| @comment node-name, next, previous, up |
| @subsection Paragraph Indenting |
| @cindex Indenting paragraphs |
| @cindex Paragraph indentation |
| @findex paragraphindent |
| |
| The Info formatting commands may insert spaces at the beginning of the |
| first line of each paragraph, thereby indenting that paragraph. You |
| can use the @code{@@paragraphindent} command to specify the |
| indentation. Write an @code{@@paragraphindent} command at the |
| beginning of a line followed by either @samp{asis} or a number. The |
| template is:@refill |
| |
| @example |
| @@paragraphindent @var{indent} |
| @end example |
| |
| The Info formatting commands indent according to the value of |
| @var{indent}:@refill |
| |
| @itemize @bullet |
| @item |
| If the value of @var{indent} is @samp{asis}, the Info formatting |
| commands do not change the existing indentation.@refill |
| |
| @item |
| If the value of @var{indent} is 0, the Info formatting commands delete |
| existing indentation.@refill |
| |
| @item |
| If the value of @var{indent} is greater than 0, the Info formatting |
| commands indent the paragraph by that number of spaces.@refill |
| @end itemize |
| |
| The default value of @var{indent} is @samp{asis}.@refill |
| |
| Write the @code{@@paragraphindent} command before or shortly after the |
| end-of-header line at the beginning of a Texinfo file. (If you write |
| the command between the start-of-header and end-of-header lines, the |
| region formatting commands indent paragraphs as specified.)@refill |
| |
| A peculiarity of the @code{texinfo-format-buffer} and |
| @code{texinfo-format-region} commands is that they do not indent (nor |
| fill) paragraphs that contain @code{@@w} or @code{@@*} commands. |
| @xref{Refilling Paragraphs}, for a detailed description of what goes |
| on.@refill |
| |
| @node End of Header, , paragraphindent, Header |
| @comment node-name, next, previous, up |
| @subsection End of Header |
| @cindex End of header line |
| |
| Follow the header lines with an @w{end-of-header} line. |
| An end-of-header line looks like this:@refill |
| |
| @example |
| @@c %**end of header |
| @end example |
| |
| If you include the @code{@@setchapternewpage} command between the |
| start-of-header and end-of-header lines, @TeX{} will typeset a region as |
| that command specifies. Similarly, if you include an @code{@@smallbook} |
| command between the start-of-header and end-of-header lines, @TeX{} will |
| typeset a region in the ``small'' book format.@refill |
| |
| @ifinfo |
| The reason for the odd string of characters (@samp{%**}) is so that the |
| @code{texinfo-tex-region} command does not accidentally find |
| something that it should not when it is looking for the header.@refill |
| |
| The start-of-header line and the end-of-header line are Texinfo mode |
| variables that you can change.@refill |
| @end ifinfo |
| |
| @iftex |
| @xref{Start of Header}. |
| @end iftex |
| |
| @node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File |
| @comment node-name, next, previous, up |
| @section Summary and Copying Permissions for Info |
| |
| The title page and the copyright page appear only in the printed copy of |
| the manual; therefore, the same information must be inserted in a |
| section that appears only in the Info file. This section usually |
| contains a brief description of the contents of the Info file, a |
| copyright notice, and copying permissions.@refill |
| |
| The copyright notice should read:@refill |
| |
| @example |
| Copyright @var{year} @var{copyright-owner} |
| @end example |
| |
| @noindent |
| and be put on a line by itself.@refill |
| |
| Standard text for the copyright permissions is contained in an appendix |
| to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying |
| Permissions}, for the complete text.@refill |
| |
| The permissions text appears in an Info file @emph{before} the first |
| node. This mean that a reader does @emph{not} see this text when |
| reading the file using Info, except when using the advanced Info command |
| @kbd{g *}. |
| |
| @node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File |
| @comment node-name, next, previous, up |
| @section The Title and Copyright Pages |
| |
| A manual's name and author are usually printed on a title page. |
| Sometimes copyright information is printed on the title page as well; |
| more often, copyright information is printed on the back of the title |
| page. |
| |
| The title and copyright pages appear in the printed manual, but not in the |
| Info file. Because of this, it is possible to use several slightly |
| obscure @TeX{} typesetting commands that cannot be used in an Info file. |
| In addition, this part of the beginning of a Texinfo file contains the text |
| of the copying permissions that will appear in the printed manual.@refill |
| |
| @xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the |
| standard text for the copyright permissions.@refill |
| |
| @menu |
| * titlepage:: Create a title for the printed document. |
| * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, |
| and @code{@@sp} commands. |
| * title subtitle author:: The @code{@@title}, @code{@@subtitle}, |
| and @code{@@author} commands. |
| * Copyright & Permissions:: How to write the copyright notice and |
| include copying permissions. |
| * end titlepage:: Turn on page headings after the title and |
| copyright pages. |
| * headings on off:: An option for turning headings on and off |
| and double or single sided printing. |
| @end menu |
| |
| @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page |
| @comment node-name, next, previous, up |
| @subsection @code{@@titlepage} |
| @cindex Title page |
| @findex titlepage |
| |
| Start the material for the title page and following copyright page |
| with @code{@@titlepage} on a line by itself and end it with |
| @code{@@end titlepage} on a line by itself.@refill |
| |
| The @code{@@end titlepage} command starts a new page and turns on page |
| numbering. (@xref{Headings, , Page Headings}, for details about how to |
| generate page headings.) All the material that you want to |
| appear on unnumbered pages should be put between the |
| @code{@@titlepage} and @code{@@end titlepage} commands. By using the |
| @code{@@page} command you can force a page break within the region |
| delineated by the @code{@@titlepage} and @code{@@end titlepage} |
| commands and thereby create more than one unnumbered page. This is |
| how the copyright page is produced. (The @code{@@titlepage} command |
| might perhaps have been better named the |
| @code{@@titleandadditionalpages} command, but that would have been |
| rather long!)@refill |
| |
| @c !!! append refill to footnote when makeinfo can handle it. |
| When you write a manual about a computer program, you should write the |
| version of the program to which the manual applies on the title |
| page. If the manual changes more frequently than the program or is |
| independent of it, you should also include an edition |
| number@footnote{We have found that it is helpful to refer to versions |
| of manuals as `editions' and versions of programs as `versions'; |
| otherwise, we find we are liable to confuse each other in conversation |
| by referring to both the documentation and the software with the same |
| words.} for the manual. This helps readers keep track of which manual |
| is for which version of the program. (The `Top' node |
| should also contain this information; see @ref{makeinfo top, , |
| @code{@@top}}.)@refill |
| |
| Texinfo provides two main methods for creating a title page. One method |
| uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands |
| to generate a title page in which the words on the page are |
| centered.@refill |
| |
| The second method uses the @code{@@title}, @code{@@subtitle}, and |
| @code{@@author} commands to create a title page with black rules under |
| the title and author lines and the subtitle text set flush to the |
| right hand side of the page. With this method, you do not specify any |
| of the actual formatting of the title page. You specify the text |
| you want, and Texinfo does the formatting. You may use either |
| method.@refill |
| |
| @findex shorttitlepage |
| For extremely simple applications, Texinfo also provides a command |
| @code{@@shorttitlepage} which takes a single argument as the title. |
| The argument is typeset on a page by itself and followed by a blank |
| page. |
| |
| |
| @node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page |
| @comment node-name, next, previous, up |
| @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} |
| @findex titlefont |
| @findex center |
| @findex sp @r{(titlepage line spacing)} |
| |
| You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} |
| commands to create a title page for a printed document. (This is the |
| first of the two methods for creating a title page in Texinfo.)@refill |
| |
| Use the @code{@@titlefont} command to select a large font suitable for |
| the title itself.@refill |
| |
| @need 700 |
| For example: |
| |
| @example |
| @@titlefont@{Texinfo@} |
| @end example |
| |
| Use the @code{@@center} command at the beginning of a line to center |
| the remaining text on that line. Thus,@refill |
| |
| @example |
| @@center @@titlefont@{Texinfo@} |
| @end example |
| |
| @noindent |
| centers the title, which in this example is ``Texinfo'' printed |
| in the title font.@refill |
| |
| Use the @code{@@sp} command to insert vertical space. For example:@refill |
| |
| @example |
| @@sp 2 |
| @end example |
| |
| @noindent |
| This inserts two blank lines on the printed page. (@xref{sp, , |
| @code{@@sp}}, for more information about the @code{@@sp} |
| command.)@refill |
| |
| A template for this method looks like this:@refill |
| |
| @example |
| @group |
| @@titlepage |
| @@sp 10 |
| @@center @@titlefont@{@var{name-of-manual-when-printed}@} |
| @@sp 2 |
| @@center @var{subtitle-if-any} |
| @@sp 2 |
| @@center @var{author} |
| @dots{} |
| @@end titlepage |
| @end group |
| @end example |
| |
| The spacing of the example fits an 8 1/2 by 11 inch manual.@refill |
| |
| @node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page |
| @comment node-name, next, previous, up |
| @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} |
| @findex title |
| @findex subtitle |
| @findex author |
| |
| You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} |
| commands to create a title page in which the vertical and horizontal |
| spacing is done for you automatically. This contrasts with the method |
| described in |
| the previous section, in which the @code{@@sp} command is needed to |
| adjust vertical spacing.@refill |
| |
| Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} |
| commands at the beginning of a line followed by the title, subtitle, |
| or author.@refill |
| |
| The @code{@@title} command produces a line in which the title is set |
| flush to the left-hand side of the page in a larger than normal font. |
| The title is underlined with a black rule.@refill |
| |
| The @code{@@subtitle} command sets subtitles in a normal-sized font |
| flush to the right-hand side of the page.@refill |
| |
| The @code{@@author} command sets the names of the author or authors in |
| a middle-sized font flush to the left-hand side of the page on a line |
| near the bottom of the title page. The names are underlined with a |
| black rule that is thinner than the rule that underlines the title. |
| (The black rule only occurs if the @code{@@author} command line is |
| followed by an @code{@@page} command line.)@refill |
| |
| There are two ways to use the @code{@@author} command: you can write |
| the name or names on the remaining part of the line that starts with |
| an @code{@@author} command:@refill |
| |
| @example |
| @@author by Jane Smith and John Doe |
| @end example |
| |
| @noindent |
| or you can write the names one above each other by using two (or more) |
| @code{@@author} commands:@refill |
| |
| @example |
| @group |
| @@author Jane Smith |
| @@author John Doe |
| @end group |
| @end example |
| |
| @noindent |
| (Only the bottom name is underlined with a black rule.)@refill |
| |
| @need 950 |
| A template for this method looks like this:@refill |
| |
| @example |
| @group |
| @@titlepage |
| @@title @var{name-of-manual-when-printed} |
| @@subtitle @var{subtitle-if-any} |
| @@subtitle @var{second-subtitle} |
| @@author @var{author} |
| @@page |
| @dots{} |
| @@end titlepage |
| @end group |
| @end example |
| |
| @ifinfo |
| @noindent |
| Contrast this form with the form of a title page written using the |
| @code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill |
| |
| @example |
| @@titlepage |
| @@sp 10 |
| @@center @@titlefont@{Name of Manual When Printed@} |
| @@sp 2 |
| @@center Subtitle, If Any |
| @@sp 1 |
| @@center Second subtitle |
| @@sp 2 |
| @@center Author |
| @@page |
| @dots{} |
| @@end titlepage |
| @end example |
| @end ifinfo |
| |
| @node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page |
| @comment node-name, next, previous, up |
| @subsection Copyright Page and Permissions |
| @cindex Copyright page |
| @cindex Printed permissions |
| @cindex Permissions, printed |
| |
| By international treaty, the copyright notice for a book should be |
| either on the title page or on the back of the title page. The |
| copyright notice should include the year followed by the name of the |
| organization or person who owns the copyright.@refill |
| |
| When the copyright notice is on the back of the title page, that page |
| is customarily not numbered. Therefore, in Texinfo, the information |
| on the copyright page should be within @code{@@titlepage} and |
| @code{@@end titlepage} commands.@refill |
| |
| @findex vskip |
| @findex filll |
| @cindex Vertical whitespace (@samp{vskip}) |
| Use the @code{@@page} command to cause a page break. To push the |
| copyright notice and the other text on the copyright page towards the |
| bottom of the page, you can write a somewhat mysterious line after the |
| @code{@@page} command that reads like this:@refill |
| |
| @example |
| @@vskip 0pt plus 1filll |
| @end example |
| |
| @noindent |
| This is a @TeX{} command that is not supported by the Info formatting |
| commands. The @code{@@vskip} command inserts whitespace. The |
| @samp{0pt plus 1filll} means to put in zero points of mandatory whitespace, |
| and as much optional whitespace as needed to push the |
| following text to the bottom of the page. Note the use of three |
| @samp{l}s in the word @samp{filll}; this is the correct usage in |
| @TeX{}.@refill |
| |
| @findex copyright |
| In a printed manual, the @code{@@copyright@{@}} command generates a |
| @samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The |
| copyright notice itself has the following legally defined sequence:@refill |
| |
| @example |
| Copyright @copyright{} @var{year} @var{copyright-owner} |
| @end example |
| |
| It is customary to put information on how to get a manual after the |
| copyright notice, followed by the copying permissions for the |
| manual.@refill |
| |
| Note that permissions must be given here as well as in the summary |
| segment within @code{@@ifinfo} and @code{@@end ifinfo} that |
| immediately follows the header since this text appears only in the |
| printed manual and the @samp{ifinfo} text appears only in the Info |
| file.@refill |
| |
| @xref{Sample Permissions}, for the standard text.@refill |
| |
| @node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page |
| @comment node-name, next, previous, up |
| @subsection Heading Generation |
| @findex end titlepage |
| @cindex Headings, page, begin to appear |
| @cindex Titlepage end starts headings |
| @cindex End titlepage starts headings |
| |
| An @code{@@end titlepage} command on a line by itself not only marks |
| the end of the title and copyright pages, but also causes @TeX{} to start |
| generating page headings and page numbers. |
| |
| To repeat what is said elsewhere, Texinfo has two standard page heading |
| formats, one for documents which are printed on one side of each sheet of paper |
| (single-sided printing), and the other for documents which are printed on both |
| sides of each sheet (double-sided printing). |
| (@xref{setchapternewpage, ,@code{@@setchapternewpage}}.) |
| You can specify these formats in different ways:@refill |
| |
| @itemize @bullet |
| @item |
| The conventional way is to write an @code{@@setchapternewpage} command |
| before the title page commands, and then have the @code{@@end |
| titlepage} command start generating page headings in the manner desired. |
| (@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill |
| |
| @item |
| Alternatively, you can use the @code{@@headings} command to prevent page |
| headings from being generated or to start them for either single or |
| double-sided printing. (Write an @code{@@headings} command immediately |
| after the @code{@@end titlepage} command. @xref{headings on off, , The |
| @code{@@headings} Command}, for more information.)@refill |
| |
| @item |
| Or, you may specify your own page heading and footing format. |
| @xref{Headings, , Page Headings}, for detailed |
| information about page headings and footings.@refill |
| @end itemize |
| |
| Most documents are formatted with the standard single-sided or |
| double-sided format, using @code{@@setchapternewpage odd} for |
| double-sided printing and no @code{@@setchapternewpage} command for |
| single-sided printing.@refill |
| |
| @node headings on off, , end titlepage, Titlepage & Copyright Page |
| @comment node-name, next, previous, up |
| @subsection The @code{@@headings} Command |
| @findex headings |
| |
| The @code{@@headings} command is rarely used. It specifies what kind of |
| page headings and footings to print on each page. Usually, this is |
| controlled by the @code{@@setchapternewpage} command. You need the |
| @code{@@headings} command only if the @code{@@setchapternewpage} command |
| does not do what you want, or if you want to turn off pre-defined page |
| headings prior to defining your own. Write an @code{@@headings} command |
| immediately after the @code{@@end titlepage} command.@refill |
| |
| You can use @code{@@headings} as follows:@refill |
| |
| @table @code |
| @item @@headings off |
| Turn off printing of page headings.@refill |
| |
| @item @@headings single |
| Turn on page headings appropriate for single-sided printing. |
| @refill |
| |
| @item @@headings double |
| Turn on page headings appropriate for double-sided printing. The two |
| commands, @code{@@headings on} and @code{@@headings double}, are |
| synonymous.@refill |
| |
| @item @@headings singleafter |
| @itemx @@headings doubleafter |
| Turn on @code{single} or @code{double} headings, respectively, after the |
| current page is output. |
| |
| @item @@headings on |
| Turn on page headings: @code{single} if @samp{@@setchapternewpage |
| on}, @code{double} otherwise. |
| @end table |
| |
| For example, suppose you write @code{@@setchapternewpage off} before the |
| @code{@@titlepage} command to tell @TeX{} to start a new chapter on the |
| same page as the end of the last chapter. This command also causes |
| @TeX{} to typeset page headers for single-sided printing. To cause |
| @TeX{} to typeset for double sided printing, write @code{@@headings |
| double} after the @code{@@end titlepage} command. |
| |
| You can stop @TeX{} from generating any page headings at all by |
| writing @code{@@headings off} on a line of its own immediately after the |
| line containing the @code{@@end titlepage} command, like this:@refill |
| |
| @example |
| @@end titlepage |
| @@headings off |
| @end example |
| |
| @noindent |
| The @code{@@headings off} command overrides the @code{@@end titlepage} |
| command, which would otherwise cause @TeX{} to print page |
| headings.@refill |
| |
| You can also specify your own style of page heading and footing. |
| @xref{Headings, , Page Headings}, for more information.@refill |
| |
| @node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File |
| @comment node-name, next, previous, up |
| @section The `Top' Node and Master Menu |
| @cindex @samp{@r{Top}} node |
| @cindex Master menu |
| @cindex Node, `Top' |
| |
| The `Top' node is the node from which you enter an Info file.@refill |
| |
| A `Top' node should contain a brief description of the Info file and an |
| extensive, master menu for the whole Info file. |
| This helps the reader understand what the Info file is |
| about. Also, you should write the version number of the program to |
| which the Info file applies; or, at least, the edition number.@refill |
| |
| The contents of the `Top' node should appear only in the Info file; none |
| of it should appear in printed output, so enclose it between |
| @code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not |
| print either an @code{@@node} line or a menu; they appear only in Info; |
| strictly speaking, you are not required to enclose these parts between |
| @code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so. |
| @xref{Conditionals, , Conditionally Visible Text}.)@refill |
| |
| @menu |
| * Title of Top Node:: Sketch what the file is about. |
| * Master Menu Parts:: A master menu has three or more parts. |
| @end menu |
| |
| @node Title of Top Node, Master Menu Parts, The Top Node, The Top Node |
| @ifinfo |
| @subheading `Top' Node Title |
| @end ifinfo |
| |
| Sometimes, you will want to place an @code{@@top} sectioning command |
| line containing the title of the document immediately after the |
| @code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top} |
| Sectioning Command}, for more information).@refill |
| |
| For example, the beginning of the Top node of this manual contains an |
| @code{@@top} sectioning command, a short description, and edition and |
| version information. It looks like this:@refill |
| |
| @example |
| @group |
| @dots{} |
| @@end titlepage |
| |
| @@ifinfo |
| @@node Top, Copying, (dir), (dir) |
| @@top Texinfo |
| |
| Texinfo is a documentation system@dots{} |
| @end group |
| |
| @group |
| This is edition@dots{} |
| @dots{} |
| @@end ifinfo |
| @end group |
| |
| @group |
| @@menu |
| * Copying:: Texinfo is freely |
| redistributable. |
| * Overview:: What is Texinfo? |
| @dots{} |
| @end group |
| @@end menu |
| @end example |
| |
| In a `Top' node, the `Previous', and `Up' nodes usually refer to the top |
| level directory of the whole Info system, which is called @samp{(dir)}. |
| The `Next' node refers to the first node that follows the main or master |
| menu, which is usually the copying permissions, introduction, or first |
| chapter.@refill |
| |
| @node Master Menu Parts, , Title of Top Node, The Top Node |
| @subsection Parts of a Master Menu |
| @cindex Master menu parts |
| @cindex Parts of a master menu |
| |
| A @dfn{master menu} is a detailed main menu listing all the nodes in a |
| file. |
| |
| A master menu is enclosed in @code{@@menu} and @code{@@end menu} |
| commands and does not appear in the printed document.@refill |
| |
| Generally, a master menu is divided into parts.@refill |
| |
| @itemize @bullet |
| @item |
| The first part contains the major nodes in the Texinfo file: the nodes |
| for the chapters, chapter-like sections, and the appendices.@refill |
| |
| @item |
| The second part contains nodes for the indices.@refill |
| |
| @item |
| The third and subsequent parts contain a listing of the other, lower |
| level nodes, often ordered by chapter. This way, rather than go |
| through an intermediary menu, an inquirer can go directly to a |
| particular node when searching for specific information. These menu |
| items are not required; add them if you think they are a |
| convenience. If you do use them, put @code{@@detailmenu} before the |
| first one, and @code{@@end detailmenu} after the last; otherwise, |
| @code{makeinfo} will get confused. |
| @end itemize |
| |
| Each section in the menu can be introduced by a descriptive line. So |
| long as the line does not begin with an asterisk, it will not be |
| treated as a menu entry. (@xref{Writing a Menu}, for more |
| information.)@refill |
| |
| For example, the master menu for this manual looks like the following |
| (but has many more entries):@refill |
| |
| @example |
| @group |
| @@menu |
| * Copying:: Texinfo is freely |
| redistributable. |
| * Overview:: What is Texinfo? |
| * Texinfo Mode:: Special features in GNU Emacs. |
| @dots{} |
| @dots{} |
| @end group |
| @group |
| * Command and Variable Index:: |
| An entry for each @@-command. |
| * Concept Index:: An entry for each concept. |
| @end group |
| |
| @group |
| @@detailmenu |
| --- The Detailed Node Listing --- |
| |
| Overview of Texinfo |
| |
| * Info Files:: What is an Info file? |
| * Printed Manuals:: Characteristics of |
| a printed manual. |
| @dots{} |
| @dots{} |
| @end group |
| |
| @group |
| Using Texinfo Mode |
| |
| * Info on a Region:: Formatting part of a file |
| for Info. |
| @dots{} |
| @dots{} |
| @@end detailmenu |
| @@end menu |
| @end group |
| @end example |
| |
| @node Software Copying Permissions, , The Top Node, Beginning a File |
| @comment node-name, next, previous, up |
| @section Software Copying Permissions |
| @cindex Software copying permissions |
| @cindex Copying software |
| @cindex Distribution |
| @cindex License agreement |
| |
| If the Texinfo file has a section containing the ``General Public |
| License'' and the distribution information and a warranty disclaimer |
| for the software that is documented, this section usually follows the |
| `Top' node. The General Public License is very important to Project |
| GNU software. It ensures that you and others will continue to have a |
| right to use and share the software.@refill |
| |
| The copying and distribution information and the disclaimer are |
| followed by an introduction or else by the first chapter of the |
| manual.@refill |
| |
| @cindex Introduction, as part of file |
| Although an introduction is not a required part of a Texinfo file, it |
| is very helpful. Ideally, it should state clearly and concisely what |
| the file is about and who would be interested in reading it. In |
| general, an introduction would follow the licensing and distribution |
| information, although sometimes people put it earlier in the document. |
| Usually, an introduction is put in an @code{@@unnumbered} section. |
| (@xref{unnumbered & appendix, , The @code{@@unnumbered} and |
| @code{@@appendix} Commands}.)@refill |
| |
| @node Ending a File, Structuring, Beginning a File, Top |
| @comment node-name, next, previous, up |
| @chapter Ending a Texinfo File |
| @cindex Ending a Texinfo file |
| @cindex Texinfo file ending |
| @cindex File ending |
| @findex bye |
| |
| The end of a Texinfo file should include the commands that create |
| indices and generate detailed and summary tables of contents. |
| And it must include the @code{@@bye} command that marks the last line |
| processed by @TeX{}.@refill |
| |
| @need 700 |
| For example: |
| |
| @example |
| @@node Concept Index, , Variables Index, Top |
| @@c node-name, next, previous, up |
| @@unnumbered Concept Index |
| |
| @@printindex cp |
| |
| @@contents |
| @@bye |
| @end example |
| |
| @menu |
| * Printing Indices & Menus:: How to print an index in hardcopy and |
| generate index menus in Info. |
| * Contents:: How to create a table of contents. |
| * File End:: How to mark the end of a file. |
| @end menu |
| |
| @node Printing Indices & Menus, Contents, Ending a File, Ending a File |
| @comment node-name, next, previous, up |
| @section Index Menus and Printing an Index |
| @findex printindex |
| @cindex Printing an index |
| @cindex Indices, printing and menus |
| @cindex Generating menus with indices |
| @cindex Menus generated with indices |
| |
| To print an index means to include it as part of a manual or Info |
| file. This does not happen automatically just because you use |
| @code{@@cindex} or other index-entry generating commands in the |
| Texinfo file; those just cause the raw data for the index to be |
| accumulated. To generate an index, you must include the |
| @code{@@printindex} command at the place in the document where you |
| want the index to appear. Also, as part of the process of creating a |
| printed manual, you must run a program called @code{texindex} |
| (@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted |
| index file. The sorted index file is what is actually used to |
| print the index.@refill |
| |
| Texinfo offers six different types of predefined index: the concept |
| index, the function index, the variables index, the keystroke index, the |
| program index, and the data type index (@pxref{Predefined Indices}). Each |
| index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr}, |
| @samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them |
| into separate sections (@pxref{Combining Indices}); or you may define |
| your own indices (@pxref{New Indices, , Defining New Indices}).@refill |
| |
| The @code{@@printindex} command takes a two-letter index name, reads |
| the corresponding sorted index file and formats it appropriately into |
| an index.@refill |
| |
| @ignore |
| The two-letter index names are: |
| |
| @table @samp |
| @item cp |
| concept index |
| @item fn |
| function index |
| @item vr |
| variable index |
| @item ky |
| key index |
| @item pg |
| program index |
| @item tp |
| data type index |
| @end table |
| @end ignore |
| The @code{@@printindex} command does not generate a chapter heading |
| for the index. Consequently, you should precede the |
| @code{@@printindex} command with a suitable section or chapter command |
| (usually @code{@@unnumbered}) to supply the chapter heading and put |
| the index into the table of contents. Precede the @code{@@unnumbered} |
| command with an @code{@@node} line.@refill |
| |
| @need 1200 |
| For example: |
| |
| @smallexample |
| @group |
| @@node Variable Index, Concept Index, Function Index, Top |
| @@comment node-name, next, previous, up |
| @@unnumbered Variable Index |
| |
| @@printindex vr |
| @end group |
| |
| @group |
| @@node Concept Index, , Variable Index, Top |
| @@comment node-name, next, previous, up |
| @@unnumbered Concept Index |
| |
| @@printindex cp |
| @end group |
| |
| @group |
| @@summarycontents |
| @@contents |
| @@bye |
| @end group |
| @end smallexample |
| |
| @noindent |
| (Readers often prefer that the concept index come last in a book, |
| since that makes it easiest to find.)@refill |
| |
| @ignore |
| In @TeX{}, the @code{@@printindex} command needs a sorted index file |
| to work from. @TeX{} does not know how to do sorting; this is a |
| deficiency. @TeX{} writes output files of raw index data; use the |
| @code{texindex} program to convert these files to sorted index files. |
| (@xref{Format/Print Hardcopy}, for more information.)@refill |
| @end ignore |
| @node Contents, File End, Printing Indices & Menus, Ending a File |
| @comment node-name, next, previous, up |
| @section Generating a Table of Contents |
| @cindex Table of contents |
| @cindex Contents, Table of |
| @findex contents |
| @findex summarycontents |
| @findex shortcontents |
| |
| The @code{@@chapter}, @code{@@section}, and other structuring commands |
| supply the information to make up a table of contents, but they do not |
| cause an actual table to appear in the manual. To do this, you must |
| use the @code{@@contents} and @code{@@summarycontents} |
| commands:@refill |
| |
| @table @code |
| @item @@contents |
| Generate a table of contents in a printed manual, including all |
| chapters, sections, subsections, etc., as well as appendices and |
| unnumbered chapters. (Headings generated by the @code{@@heading} |
| series of commands do not appear in the table of contents.) The |
| @code{@@contents} command should be written on a line by |
| itself.@refill |
| |
| @item @@shortcontents |
| @itemx @@summarycontents |
| (@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the |
| two commands are exactly the same.)@refill |
| |
| Generate a short or summary table of contents that lists only the |
| chapters (and appendices and unnumbered chapters). Omit sections, subsections |
| and subsubsections. Only a long manual needs a short table |
| of contents in addition to the full table of contents.@refill |
| |
| Write the @code{@@shortcontents} command on a line by itself right |
| @emph{before} the @code{@@contents} command.@refill |
| @end table |
| |
| The table of contents commands automatically generate a chapter-like |
| heading at the top of the first table of contents page. Write the table |
| of contents commands at the very end of a Texinfo file, just before the |
| @code{@@bye} command, following any index sections---anything in the |
| Texinfo file after the table of contents commands will be omitted from |
| the table of contents.@refill |
| |
| When you print a manual with a table of contents, the table of |
| contents are printed last and numbered with roman numerals. You need |
| to place those pages in their proper place, after the title page, |
| yourself. (This is the only collating you need to do for a printed |
| manual. The table of contents is printed last because it is generated |
| after the rest of the manual is typeset.)@refill |
| |
| @need 700 |
| Here is an example of where to write table of contents commands:@refill |
| |
| @example |
| @group |
| @var{indices}@dots{} |
| @@shortcontents |
| @@contents |
| @@bye |
| @end group |
| @end example |
| |
| Since an Info file uses menus instead of tables of contents, the Info |
| formatting commands ignore the @code{@@contents} and |
| @code{@@shortcontents} commands.@refill |
| |
| @node File End, , Contents, Ending a File |
| @comment node-name, next, previous, up |
| @section @code{@@bye} File Ending |
| @findex bye |
| |
| An @code{@@bye} command terminates @TeX{} or Info formatting. None of |
| the formatting commands see any of the file following @code{@@bye}. |
| The @code{@@bye} command should be on a line by itself.@refill |
| |
| If you wish, you may follow the @code{@@bye} line with notes. These notes |
| will not be formatted and will not appear in either Info or a printed |
| manual; it is as if text after @code{@@bye} were within @code{@@ignore} |
| @dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line |
| with a local variables list. @xref{Compile-Command, , Using Local |
| Variables and the Compile Command}, for more information.@refill |
| |
| @node Structuring, Nodes, Ending a File, Top |
| @comment node-name, next, previous, up |
| @chapter Chapter Structuring |
| @cindex Chapter structuring |
| @cindex Structuring of chapters |
| |
| The @dfn{chapter structuring} commands divide a document into a hierarchy of |
| chapters, sections, subsections, and subsubsections. These commands |
| generate large headings; they also provide information for the table |
| of contents of a printed manual (@pxref{Contents, , Generating a Table |
| of Contents}).@refill |
| |
| The chapter structuring commands do not create an Info node structure, |
| so normally you should put an @code{@@node} command immediately before |
| each chapter structuring command (@pxref{Nodes}). The only time you |
| are likely to use the chapter structuring commands without using the |
| node structuring commands is if you are writing a document that |
| contains no cross references and will never be transformed into Info |
| format.@refill |
| |
| It is unlikely that you will ever write a Texinfo file that is |
| intended only as an Info file and not as a printable document. If you |
| do, you might still use chapter structuring commands to create a |
| heading at the top of each node---but you don't need to.@refill |
| |
| @menu |
| * Tree Structuring:: A manual is like an upside down tree @dots{} |
| * Structuring Command Types:: How to divide a manual into parts. |
| * makeinfo top:: The @code{@@top} command, part of the `Top' node. |
| * chapter:: |
| * unnumbered & appendix:: |
| * majorheading & chapheading:: |
| * section:: |
| * unnumberedsec appendixsec heading:: |
| * subsection:: |
| * unnumberedsubsec appendixsubsec subheading:: |
| * subsubsection:: Commands for the lowest level sections. |
| * Raise/lower sections:: How to change commands' hierarchical level. |
| @end menu |
| |
| @node Tree Structuring, Structuring Command Types, Structuring, Structuring |
| @comment node-name, next, previous, up |
| @section Tree Structure of Sections |
| @cindex Tree structuring |
| |
| A Texinfo file is usually structured like a book with chapters, |
| sections, subsections, and the like. This structure can be visualized |
| as a tree (or rather as an upside-down tree) with the root at the top |
| and the levels corresponding to chapters, sections, subsection, and |
| subsubsections.@refill |
| |
| Here is a diagram that shows a Texinfo file with three chapters, |
| each of which has two sections.@refill |
| |
| @example |
| @group |
| Top |
| | |
| ------------------------------------- |
| | | | |
| Chapter 1 Chapter 2 Chapter 3 |
| | | | |
| -------- -------- -------- |
| | | | | | | |
| Section Section Section Section Section Section |
| 1.1 1.2 2.1 2.2 3.1 3.2 |
| |
| @end group |
| @end example |
| |
| In a Texinfo file that has this structure, the beginning of Chapter 2 |
| looks like this:@refill |
| |
| @example |
| @group |
| @@node Chapter 2, Chapter 3, Chapter 1, top |
| @@chapter Chapter 2 |
| @end group |
| @end example |
| |
| The chapter structuring commands are described in the sections that |
| follow; the @code{@@node} and @code{@@menu} commands are described in |
| following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill |
| |
| @node Structuring Command Types, makeinfo top, Tree Structuring, Structuring |
| @comment node-name, next, previous, up |
| @section Types of Structuring Command |
| |
| The chapter structuring commands fall into four groups or series, each |
| of which contains structuring commands corresponding to the |
| hierarchical levels of chapters, sections, subsections, and |
| subsubsections.@refill |
| |
| The four groups are the @code{@@chapter} series, the |
| @code{@@unnumbered} series, the @code{@@appendix} series, and the |
| @code{@@heading} series.@refill |
| |
| Each command produces titles that have a different appearance on the |
| printed page or Info file; only some of the commands produce |
| titles that are listed in the table of contents of a printed book or |
| manual.@refill |
| |
| @itemize @bullet |
| @item |
| The @code{@@chapter} and @code{@@appendix} series of commands produce |
| numbered or lettered entries both in the body of a printed work and in |
| its table of contents.@refill |
| |
| @item |
| The @code{@@unnumbered} series of commands produce unnumbered entries |
| both in the body of a printed work and in its table of contents. The |
| @code{@@top} command, which has a special use, is a member of this |
| series (@pxref{makeinfo top, , @code{@@top}}).@refill |
| |
| @item |
| The @code{@@heading} series of commands produce unnumbered headings |
| that do not appear in a table of contents. The heading commands never |
| start a new page.@refill |
| |
| @item |
| The @code{@@majorheading} command produces results similar to using |
| the @code{@@chapheading} command but generates a larger vertical |
| whitespace before the heading.@refill |
| |
| @item |
| When an @code{@@setchapternewpage} command says to do so, the |
| @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands |
| start new pages in the printed manual; the @code{@@heading} commands |
| do not.@refill |
| @end itemize |
| |
| @need 1000 |
| Here are the four groups of chapter structuring commands:@refill |
| |
| @c Slightly different formatting for regular sized books and smallbooks. |
| @ifset smallbook |
| @sp 1 |
| @tex |
| {\let\rm=\indrm \let\tt=\indtt |
| \halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& |
| \hskip.5em#\hfil\cr |
| |
| & & & \rm No new pages\cr |
| \rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr |
| \rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr |
| |
| & & & \cr |
| & \tt @@top& & \tt @@majorheading\cr |
| \tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr |
| \tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr |
| \tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& |
| \tt @@subheading\cr |
| \tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& |
| \tt @@subsubheading\cr}} |
| @end tex |
| @end ifset |
| @ifclear smallbook |
| @sp 1 |
| @tex |
| \vbox{ |
| \halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& |
| \hskip.5em#\hfil& \hskip.5em #\hfil\cr |
| |
| & & & \cr |
| & & & \rm No new pages\cr |
| \rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr |
| \rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr |
| |
| & & & \cr |
| & \tt @@top& & \tt @@majorheading\cr |
| \tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr |
| \tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr |
| \tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& |
| \tt @@subheading\cr |
| \tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& |
| \tt @@subsubheading\cr}} |
| @end tex |
| @end ifclear |
| @ifinfo |
| @example |
| @group |
| @r{No new pages} |
| @r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} |
| @r{In contents} @r{In contents} @r{In contents} @r{Not in contents} |
| |
| @@top @@majorheading |
| @@chapter @@unnumbered @@appendix @@chapheading |
| @@section @@unnumberedsec @@appendixsec @@heading |
| @@subsection @@unnumberedsubsec @@appendixsubsec @@subheading |
| @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading |
| @end group |
| @end example |
| @end ifinfo |
| |
| @c Cannot line up columns properly inside of an example because of roman |
| @c proportional fonts. |
| @ignore |
| @ifset smallbook |
| @iftex |
| @smallexample |
| @group |
| @r{No new pages} |
| @r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} |
| @r{In contents} @r{In contents} @r{In contents} @r{Not in contents} |
| |
| @@top @@majorheading |
| @@chapter @@unnumbered @@appendix @@chapheading |
| @@section @@unnumberedsec @@appendixsec @@heading |
| @@subsection @@unnumberedsubsec @@appendixsubsec @@subheading |
| @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading |
| @end group |
| @end smallexample |
| @end iftex |
| @end ifset |
| @ifclear smallbook |
| @iftex |
| @smallexample |
| @group |
| @r{No new pages} |
| @r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} |
| @r{In contents} @r{In contents} @r{In contents} @r{Not in contents} |
| |
| @@top @@majorheading |
| @@chapter @@unnumbered @@appendix @@chapheading |
| @@section @@unnumberedsec @@appendixsec @@heading |
| @@subsection @@unnumberedsubsec @@appendixsubsec @@subheading |
| @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading |
| @end group |
| @end smallexample |
| @end iftex |
| @end ignore |
| |
| @node makeinfo top, chapter, Structuring Command Types, Structuring |
| @comment node-name, next, previous, up |
| @section @code{@@top} |
| |
| The @code{@@top} command is a special sectioning command that you use |
| only after an @code{@@node Top} line at the beginning of a Texinfo file. |
| The @code{@@top} command tells the @code{makeinfo} formatter |
| which node is the `Top' |
| node. It has the same typesetting effect as @code{@@unnumbered} |
| (@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). |
| For detailed information, see |
| @ref{makeinfo top command, , The @code{@@top} Command}.@refill |
| |
| @node chapter, unnumbered & appendix, makeinfo top, Structuring |
| @comment node-name, next, previous, up |
| @section @code{@@chapter} |
| @findex chapter |
| |
| @code{@@chapter} identifies a chapter in the document. Write the |
| command at the beginning of a line and follow it on the same line by |
| the title of the chapter.@refill |
| |
| For example, this chapter in this manual is entitled ``Chapter |
| Structuring''; the @code{@@chapter} line looks like this:@refill |
| |
| @example |
| @@chapter Chapter Structuring |
| @end example |
| |
| In @TeX{}, the @code{@@chapter} command creates a chapter in the |
| document, specifying the chapter title. The chapter is numbered |
| automatically.@refill |
| |
| In Info, the @code{@@chapter} command causes the title to appear on a |
| line by itself, with a line of asterisks inserted underneath. Thus, |
| in Info, the above example produces the following output:@refill |
| |
| @example |
| Chapter Structuring |
| ******************* |
| @end example |
| |
| @findex centerchap |
| Texinfo also provides a command @code{@@centerchap}, which is analogous |
| to @code{@@unnumbered}, but centers its argument in the printed output. |
| This kind of stylistic choice is not usually offered by Texinfo. |
| @c but the Hacker's Dictionary wanted it ... |
| |
| |
| @node unnumbered & appendix, majorheading & chapheading, chapter, Structuring |
| @comment node-name, next, previous, up |
| @section @code{@@unnumbered}, @code{@@appendix} |
| @findex unnumbered |
| @findex appendix |
| |
| Use the @code{@@unnumbered} command to create a chapter that appears |
| in a printed manual without chapter numbers of any kind. Use the |
| @code{@@appendix} command to create an appendix in a printed manual |
| that is labelled by letter instead of by number.@refill |
| |
| For Info file output, the @code{@@unnumbered} and @code{@@appendix} |
| commands are equivalent to @code{@@chapter}: the title is printed on a |
| line by itself with a line of asterisks underneath. (@xref{chapter, , |
| @code{@@chapter}}.)@refill |
| |
| To create an appendix or an unnumbered chapter, write an |
| @code{@@appendix} or @code{@@unnumbered} command at the beginning of a |
| line and follow it on the same line by the title, as you would if you |
| were creating a chapter.@refill |
| |
| |
| @node majorheading & chapheading, section, unnumbered & appendix, Structuring |
| @section @code{@@majorheading}, @code{@@chapheading} |
| @findex majorheading |
| @findex chapheading |
| |
| The @code{@@majorheading} and @code{@@chapheading} commands put |
| chapter-like headings in the body of a document.@refill |
| |
| However, neither command causes @TeX{} to produce a numbered heading |
| or an entry in the table of contents; and neither command causes |
| @TeX{} to start a new page in a printed manual.@refill |
| |
| In @TeX{}, an @code{@@majorheading} command generates a larger vertical |
| whitespace before the heading than an @code{@@chapheading} command but |
| is otherwise the same.@refill |
| |
| In Info, |
| the @code{@@majorheading} and |
| @code{@@chapheading} commands are equivalent to |
| @code{@@chapter}: the title is printed on a line by itself with a line |
| of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill |
| |
| @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring |
| @comment node-name, next, previous, up |
| @section @code{@@section} |
| @findex section |
| |
| In a printed manual, an @code{@@section} command identifies a |
| numbered section within a chapter. The section title appears in the |
| table of contents. In Info, an @code{@@section} command provides a |
| title for a segment of text, underlined with @samp{=}.@refill |
| |
| This section is headed with an @code{@@section} command and looks like |
| this in the Texinfo file:@refill |
| |
| @example |
| @@section @@code@{@@@@section@} |
| @end example |
| |
| To create a section, write the @code{@@section} command at the |
| beginning of a line and follow it on the same line by the section |
| title.@refill |
| |
| Thus, |
| |
| @example |
| @@section This is a section |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| This is a section |
| ================= |
| @end group |
| @end example |
| |
| @noindent |
| in Info. |
| |
| @node unnumberedsec appendixsec heading, subsection, section, Structuring |
| @comment node-name, next, previous, up |
| @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} |
| @findex unnumberedsec |
| @findex appendixsec |
| @findex heading |
| |
| The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} |
| commands are, respectively, the unnumbered, appendix-like, and |
| heading-like equivalents of the @code{@@section} command. |
| (@xref{section, , @code{@@section}}.)@refill |
| |
| @table @code |
| @item @@unnumberedsec |
| The @code{@@unnumberedsec} command may be used within an |
| unnumbered chapter or within a regular chapter or appendix to |
| provide an unnumbered section.@refill |
| |
| @item @@appendixsec |
| @itemx @@appendixsection |
| @code{@@appendixsection} is a longer spelling of the |
| @code{@@appendixsec} command; the two are synonymous.@refill |
| @findex appendixsection |
| |
| Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} |
| command is used only within appendices.@refill |
| |
| @item @@heading |
| You may use the @code{@@heading} command anywhere you wish for a |
| section-style heading that will not appear in the table of contents.@refill |
| @end table |
| |
| @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring |
| @comment node-name, next, previous, up |
| @section The @code{@@subsection} Command |
| @findex subsection |
| |
| Subsections are to sections as sections are to chapters. |
| (@xref{section, , @code{@@section}}.) In Info, subsection titles are |
| underlined with @samp{-}. For example,@refill |
| |
| @example |
| @@subsection This is a subsection |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| This is a subsection |
| -------------------- |
| @end group |
| @end example |
| |
| In a printed manual, subsections are listed in the table of contents |
| and are numbered three levels deep.@refill |
| |
| @node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring |
| @comment node-name, next, previous, up |
| @section The @code{@@subsection}-like Commands |
| @cindex Subsection-like commands |
| @findex unnumberedsubsec |
| @findex appendixsubsec |
| @findex subheading |
| |
| The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and |
| @code{@@subheading} commands are, respectively, the unnumbered, |
| appendix-like, and heading-like equivalents of the @code{@@subsection} |
| command. (@xref{subsection, , @code{@@subsection}}.)@refill |
| |
| In Info, the @code{@@subsection}-like commands generate a title |
| underlined with hyphens. In a printed manual, an @code{@@subheading} |
| command produces a heading like that of a subsection except that it is |
| not numbered and does not appear in the table of contents. Similarly, |
| an @code{@@unnumberedsubsec} command produces an unnumbered heading like |
| that of a subsection and an @code{@@appendixsubsec} command produces a |
| subsection-like heading labelled with a letter and numbers; both of |
| these commands produce headings that appear in the table of |
| contents.@refill |
| |
| @node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring |
| @comment node-name, next, previous, up |
| @section The `subsub' Commands |
| @cindex Subsub commands |
| @findex subsubsection |
| @findex unnumberedsubsubsec |
| @findex appendixsubsubsec |
| @findex subsubheading |
| |
| The fourth and lowest level sectioning commands in Texinfo are the |
| `subsub' commands. They are:@refill |
| |
| @table @code |
| @item @@subsubsection |
| Subsubsections are to subsections as subsections are to sections. |
| (@xref{subsection, , @code{@@subsection}}.) In a printed manual, |
| subsubsection titles appear in the table of contents and are numbered |
| four levels deep.@refill |
| |
| @item @@unnumberedsubsubsec |
| Unnumbered subsubsection titles appear in the table of contents of a |
| printed manual, but lack numbers. Otherwise, unnumbered |
| subsubsections are the same as subsubsections. In Info, unnumbered |
| subsubsections look exactly like ordinary subsubsections.@refill |
| |
| @item @@appendixsubsubsec |
| Conventionally, appendix commands are used only for appendices and are |
| lettered and numbered appropriately in a printed manual. They also |
| appear in the table of contents. In Info, appendix subsubsections look |
| exactly like ordinary subsubsections.@refill |
| |
| @item @@subsubheading |
| The @code{@@subsubheading} command may be used anywhere that you need |
| a small heading that will not appear in the table of contents. In |
| Info, subsubheadings look exactly like ordinary subsubsection |
| headings.@refill |
| @end table |
| |
| In Info, `subsub' titles are underlined with periods. |
| For example,@refill |
| |
| @example |
| @@subsubsection This is a subsubsection |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| This is a subsubsection |
| ....................... |
| @end group |
| @end example |
| |
| @node Raise/lower sections, , subsubsection, Structuring |
| @comment node-name, next, previous, up |
| @section @code{@@raisesections} and @code{@@lowersections} |
| @findex raisesections |
| @findex lowersections |
| @cindex Raising and lowering sections |
| @cindex Sections, raising and lowering |
| |
| The @code{@@raisesections} and @code{@@lowersections} commands raise and |
| lower the hierarchical level of chapters, sections, subsections and the |
| like. The @code{@@raisesections} command changes sections to chapters, |
| subsections to sections, and so on. The @code{@@lowersections} command |
| changes chapters to sections, sections to subsections, and so on. |
| |
| An @code{@@lowersections} command is useful if you wish to include text |
| that is written as an outer or standalone Texinfo file in another |
| Texinfo file as an inner, included file. If you write the command at |
| the beginning of the file, all your @code{@@chapter} commands are |
| formatted as if they were @code{@@section} commands, all your |
| @code{@@section} command are formatted as if they were |
| @code{@@subsection} commands, and so on. |
| |
| @need 1000 |
| @code{@@raisesections} raises a command one level in the chapter |
| structuring hierarchy:@refill |
| |
| @example |
| @group |
| @r{Change} @r{To} |
| |
| @@subsection @@section, |
| @@section @@chapter, |
| @@heading @@chapheading, |
| @r{etc.} |
| @end group |
| @end example |
| |
| @need 1000 |
| @code{@@lowersections} lowers a command one level in the chapter |
| structuring hierarchy:@refill |
| |
| @example |
| @group |
| @r{Change} @r{To} |
| |
| @@chapter @@section, |
| @@subsection @@subsubsection, |
| @@heading @@subheading, |
| @r{etc.} |
| @end group |
| @end example |
| |
| An @code{@@raisesections} or @code{@@lowersections} command changes only |
| those structuring commands that follow the command in the Texinfo file. |
| Write an @code{@@raisesections} or @code{@@lowersections} command on a |
| line of its own. |
| |
| An @code{@@lowersections} command cancels an @code{@@raisesections} |
| command, and vice versa. |
| |
| Repeated use of the commands continue to raise or lower the hierarchical |
| level a step at a time. |
| |
| An attempt to raise above `chapters' reproduces chapter commands; an |
| attempt to lower below `subsubsections' reproduces subsubsection |
| commands. |
| |
| @node Nodes, Menus, Structuring, Top |
| @comment node-name, next, previous, up |
| @chapter Nodes |
| |
| @dfn{Nodes} are the primary segments of a Texinfo file. They do not |
| themselves impose a hierarchic or any other kind of structure on a file. |
| Nodes contain @dfn{node pointers} that name other nodes, and can contain |
| @dfn{menus} which are lists of nodes. In Info, the movement commands |
| can carry you to a pointed-to node or to a node listed in a menu. Node |
| pointers and menus provide structure for Info files just as chapters, |
| sections, subsections, and the like, provide structure for printed |
| books.@refill |
| |
| @menu |
| * Two Paths:: Different commands to structure |
| Info output and printed output. |
| * Node Menu Illustration:: A diagram, and sample nodes and menus. |
| * node:: How to write a node, in detail. |
| * makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. |
| @end menu |
| |
| @node Two Paths, Node Menu Illustration, Nodes, Nodes |
| @ifinfo |
| @heading Two Paths |
| @end ifinfo |
| |
| The node and menu commands and the chapter structuring commands are |
| independent of each other: |
| |
| @itemize @bullet |
| @item |
| In Info, node and menu commands provide structure. The chapter |
| structuring commands generate headings with different kinds of |
| underlining---asterisks for chapters, hyphens for sections, and so on; |
| they do nothing else.@refill |
| |
| @item |
| In @TeX{}, the chapter structuring commands generate chapter and section |
| numbers and tables of contents. The node and menu commands provide |
| information for cross references; they do nothing else.@refill |
| @end itemize |
| |
| You can use node pointers and menus to structure an Info file any way |
| you want; and you can write a Texinfo file so that its Info output has a |
| different structure than its printed output. However, most Texinfo |
| files are written such that the structure for the Info output |
| corresponds to the structure for the printed output. It is not |
| convenient to do otherwise.@refill |
| |
| Generally, printed output is structured in a tree-like hierarchy in |
| which the chapters are the major limbs from which the sections branch |
| out. Similarly, node pointers and menus are organized to create a |
| matching structure in the Info output.@refill |
| |
| @node Node Menu Illustration, node, Two Paths, Nodes |
| @comment node-name, next, previous, up |
| @section Node and Menu Illustration |
| |
| Here is a copy of the diagram shown earlier that illustrates a Texinfo |
| file with three chapters, each of which contains two sections.@refill |
| |
| Note that the ``root'' is at the top of the diagram and the ``leaves'' |
| are at the bottom. This is how such a diagram is drawn conventionally; |
| it illustrates an upside-down tree. For this reason, the root node is |
| called the `Top' node, and `Up' node pointers carry you closer to the |
| root.@refill |
| |
| @example |
| @group |
| Top |
| | |
| ------------------------------------- |
| | | | |
| Chapter 1 Chapter 2 Chapter 3 |
| | | | |
| -------- -------- -------- |
| | | | | | | |
| Section Section Section Section Section Section |
| 1.1 1.2 2.1 2.2 3.1 3.2 |
| |
| @end group |
| @end example |
| |
| Write the beginning of the node for Chapter 2 like this:@refill |
| |
| @example |
| @group |
| @@node Chapter 2, Chapter 3, Chapter 1, top |
| @@comment node-name, next, previous, up |
| @end group |
| @end example |
| |
| @noindent |
| This @code{@@node} line says that the name of this node is ``Chapter 2'', the |
| name of the `Next' node is ``Chapter 3'', the name of the `Previous' |
| node is ``Chapter 1'', and the name of the `Up' node is ``Top''. |
| |
| @quotation |
| @strong{Please Note:} `Next' refers to the next node at the same |
| hierarchical level in the manual, not necessarily to the next node |
| within the Texinfo file. In the Texinfo file, the subsequent node may |
| be at a lower level---a section-level node may follow a chapter-level |
| node, and a subsection-level node may follow a section-level node. |
| `Next' and `Previous' refer to nodes at the @emph{same} hierarchical |
| level. (The `Top' node contains the exception to this rule. Since the |
| `Top' node is the only node at that level, `Next' refers to the first |
| following node, which is almost always a chapter or chapter-level |
| node.)@refill |
| @end quotation |
| |
| To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter |
| 2. (@xref{Menus}.) You would write the menu just |
| before the beginning of Section 2.1, like this:@refill |
| |
| @example |
| @group |
| @@menu |
| * Sect. 2.1:: Description of this section. |
| * Sect. 2.2:: |
| @@end menu |
| @end group |
| @end example |
| |
| Write the node for Sect. 2.1 like this:@refill |
| |
| @example |
| @group |
| @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 |
| @@comment node-name, next, previous, up |
| @end group |
| @end example |
| |
| In Info format, the `Next' and `Previous' pointers of a node usually |
| lead to other nodes at the same level---from chapter to chapter or from |
| section to section (sometimes, as shown, the `Previous' pointer points |
| up); an `Up' pointer usually leads to a node at the level above (closer |
| to the `Top' node); and a `Menu' leads to nodes at a level below (closer |
| to `leaves'). (A cross reference can point to a node at any level; |
| see @ref{Cross References}.)@refill |
| |
| Usually, an @code{@@node} command and a chapter structuring command are |
| used in sequence, along with indexing commands. (You may follow the |
| @code{@@node} line with a comment line that reminds you which pointer is |
| which.)@refill |
| |
| Here is the beginning of the chapter in this manual called ``Ending a |
| Texinfo File''. This shows an @code{@@node} line followed by a comment |
| line, an @code{@@chapter} line, and then by indexing lines.@refill |
| |
| @example |
| @group |
| @@node Ending a File, Structuring, Beginning a File, Top |
| @@comment node-name, next, previous, up |
| @@chapter Ending a Texinfo File |
| @@cindex Ending a Texinfo file |
| @@cindex Texinfo file ending |
| @@cindex File ending |
| @end group |
| @end example |
| |
| @node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes |
| @comment node-name, next, previous, up |
| @section The @code{@@node} Command |
| |
| @cindex Node, defined |
| A @dfn{node} is a segment of text that begins at an @code{@@node} |
| command and continues until the next @code{@@node} command. The |
| definition of node is different from that for chapter or section. A |
| chapter may contain sections and a section may contain subsections; |
| but a node cannot contain subnodes; the text of a node continues only |
| until the next @code{@@node} command in the file. A node usually |
| contains only one chapter structuring command, the one that follows |
| the @code{@@node} line. On the other hand, in printed output nodes |
| are used only for cross references, so a chapter or section may |
| contain any number of nodes. Indeed, a chapter usually contains |
| several nodes, one for each section, subsection, and |
| subsubsection.@refill |
| |
| To create a node, write an @code{@@node} command at the beginning of a |
| line, and follow it with four arguments, separated by commas, on the |
| rest of the same line. These arguments are the name of the node, and |
| the names of the `Next', `Previous', and `Up' pointers, in that order. |
| You may insert spaces before each pointer if you wish; the spaces are |
| ignored. You must write the name of the node, and the names of the |
| `Next', `Previous', and `Up' pointers, all on the same line. Otherwise, |
| the formatters fail. (@inforef{Top, info, info}, for more information |
| about nodes in Info.)@refill |
| |
| Usually, you write one of the chapter-structuring command lines |
| immediately after an @code{@@node} line---for example, an |
| @code{@@section} or @code{@@subsection} line. (@xref{Structuring |
| Command Types, , Types of Structuring Command}.)@refill |
| |
| @quotation |
| @strong{Please note:} The GNU Emacs Texinfo mode updating commands work |
| only with Texinfo files in which @code{@@node} lines are followed by chapter |
| structuring lines. @xref{Updating Requirements}.@refill |
| @end quotation |
| |
| @TeX{} uses @code{@@node} lines to identify the names to use for cross |
| references. For this reason, you must write @code{@@node} lines in a |
| Texinfo file that you intend to format for printing, even if you do not |
| intend to format it for Info. (Cross references, such as the one at the |
| end of this sentence, are made with @code{@@xref} and its related |
| commands; see @ref{Cross References}.)@refill |
| |
| @menu |
| * Node Names:: How to choose node and pointer names. |
| * Writing a Node:: How to write an @code{@@node} line. |
| * Node Line Tips:: Keep names short. |
| * Node Line Requirements:: Keep names unique, without @@-commands. |
| * First Node:: How to write a `Top' node. |
| * makeinfo top command:: How to use the @code{@@top} command. |
| * Top Node Summary:: Write a brief description for readers. |
| @end menu |
| |
| @node Node Names, Writing a Node, node, node |
| @ifinfo |
| @subheading Choosing Node and Pointer Names |
| @end ifinfo |
| |
| The name of a node identifies the node. The pointers enable |
| you to reach other nodes and consist of the names of those nodes.@refill |
| |
| Normally, a node's `Up' pointer contains the name of the node whose menu |
| mentions that node. The node's `Next' pointer contains the name of the |
| node that follows that node in that menu and its `Previous' pointer |
| contains the name of the node that precedes it in that menu. When a |
| node's `Previous' node is the same as its `Up' node, both node pointers |
| name the same node.@refill |
| |
| Usually, the first node of a Texinfo file is the `Top' node, and its |
| `Up' and `Previous' pointers point to the @file{dir} file, which |
| contains the main menu for all of Info.@refill |
| |
| The `Top' node itself contains the main or master menu for the manual. |
| Also, it is helpful to include a brief description of the manual in the |
| `Top' node. @xref{First Node}, for information on how to write the |
| first node of a Texinfo file.@refill |
| |
| @node Writing a Node, Node Line Tips, Node Names, node |
| @comment node-name, next, previous, up |
| @subsection How to Write an @code{@@node} Line |
| @cindex Writing an @code{@@node} line |
| @cindex @code{@@node} line writing |
| @cindex Node line writing |
| |
| The easiest way to write an @code{@@node} line is to write @code{@@node} |
| at the beginning of a line and then the name of the node, like |
| this:@refill |
| |
| @example |
| @@node @var{node-name} |
| @end example |
| |
| If you are using GNU Emacs, you can use the update node commands |
| provided by Texinfo mode to insert the names of the pointers; or you |
| can leave the pointers out of the Texinfo file and let @code{makeinfo} |
| insert node pointers into the Info file it creates. (@xref{Texinfo |
| Mode}, and @ref{makeinfo Pointer Creation}.)@refill |
| |
| Alternatively, you can insert the `Next', `Previous', and `Up' |
| pointers yourself. If you do this, you may find it helpful to use the |
| Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts |
| @samp{@@node} and a comment line listing the names of the pointers in |
| their proper order. The comment line helps you keep track of which |
| arguments are for which pointers. This comment line is especially useful |
| if you are not familiar with Texinfo.@refill |
| |
| The template for a node line with `Next', `Previous', and `Up' pointers |
| looks like this:@refill |
| |
| @example |
| @@node @var{node-name}, @var{next}, @var{previous}, @var{up} |
| @end example |
| |
| If you wish, you can ignore @code{@@node} lines altogether in your first |
| draft and then use the @code{texinfo-insert-node-lines} command to |
| create @code{@@node} lines for you. However, we do not |
| recommend this practice. It is better to name the node itself |
| at the same time that you |
| write a segment so you can easily make cross references. A large number |
| of cross references are an especially important feature of a good Info |
| file.@refill |
| |
| After you have inserted an @code{@@node} line, you should immediately |
| write an @@-command for the chapter or section and insert its name. |
| Next (and this is important!), put in several index entries. Usually, |
| you will find at least two and often as many as four or five ways of |
| referring to the node in the index. Use them all. This will make it |
| much easier for people to find the node.@refill |
| |
| @node Node Line Tips, Node Line Requirements, Writing a Node, node |
| @comment node-name, next, previous, up |
| @subsection @code{@@node} Line Tips |
| |
| Here are three suggestions: |
| |
| @itemize @bullet |
| @item |
| Try to pick node names that are informative but short.@refill |
| |
| In the Info file, the file name, node name, and pointer names are all |
| inserted on one line, which may run into the right edge of the window. |
| (This does not cause a problem with Info, but is ugly.)@refill |
| |
| @item |
| Try to pick node names that differ from each other near the beginnings |
| of their names. This way, it is easy to use automatic name completion in |
| Info.@refill |
| |
| @item |
| By convention, node names are capitalized just as they would be for |
| section or chapter titles---initial and significant words are |
| capitalized; others are not.@refill |
| @end itemize |
| |
| @node Node Line Requirements, First Node, Node Line Tips, node |
| @comment node-name, next, previous, up |
| @subsection @code{@@node} Line Requirements |
| |
| @cindex Node line requirements |
| Here are several requirements for @code{@@node} lines: |
| |
| @itemize @bullet |
| @cindex Unique nodename requirement |
| @cindex Nodename must be unique |
| @item |
| All the node names for a single Info file must be unique.@refill |
| |
| Duplicates confuse the Info movement commands. This means, for |
| example, that if you end every chapter with a summary, you must name |
| each summary node differently. You cannot just call each one |
| ``Summary''. You may, however, duplicate the titles of chapters, sections, |
| and the like. Thus you can end each chapter in a book with a section |
| called ``Summary'', so long as the node names for those sections are all |
| different.@refill |
| |
| @item |
| A pointer name must be the name of a node.@refill |
| |
| The node to which a pointer points may come before or after the |
| node containing the pointer.@refill |
| |
| @cindex @@-command in nodename |
| @cindex Nodename, cannot contain |
| @item |
| You cannot use any of the Texinfo @@-commands in a node name; |
| @w{@@-commands} confuse Info.@refill |
| |
| @need 750 |
| Thus, the beginning of the section called @code{@@chapter} looks like |
| this:@refill |
| |
| @smallexample |
| @group |
| @@node chapter, unnumbered & appendix, makeinfo top, Structuring |
| @@comment node-name, next, previous, up |
| @@section @@code@{@@@@chapter@} |
| @@findex chapter |
| @end group |
| @end smallexample |
| |
| @cindex Comma in nodename |
| @cindex Colon in nodename |
| @cindex Apostrophe in nodename |
| @item |
| You cannot use commas, colons, or apostrophes within a node name; these |
| confuse @TeX{} or the Info formatters.@refill |
| |
| @need 700 |
| For example, the following is a section title: |
| |
| @smallexample |
| @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} |
| @end smallexample |
| |
| @noindent |
| The corresponding node name is: |
| |
| @smallexample |
| unnumberedsec appendixsec heading |
| @end smallexample |
| |
| @cindex Case in nodename |
| @item |
| Case is significant. |
| @end itemize |
| |
| @node First Node, makeinfo top command, Node Line Requirements, node |
| @comment node-name, next, previous, up |
| @subsection The First Node |
| @cindex @samp{@r{Top}} node is first |
| @cindex First node |
| |
| The first node of a Texinfo file is the `Top' node, except in an |
| included file (@pxref{Include Files}). |
| |
| The `Top' node (which must be named @samp{top} or @samp{Top}) should |
| have as its `Up' and `Previous' nodes the name of a node in another |
| file, where there is a menu that leads to this file. Specify the file |
| name in parentheses. If the file is to be installed directly in the |
| Info directory file, use @samp{(dir)} as the parent of the `Top' node; |
| this is short for @samp{(dir)top}, and specifies the `Top' node in the |
| @file{dir} file, which contains the main menu for Info. For example, |
| the @code{@@node Top} line of this manual looks like this:@refill |
| |
| @example |
| @@node Top, Overview, (dir), (dir) |
| @end example |
| |
| @noindent |
| (You may use the Texinfo updating commands or the @code{makeinfo} |
| utility to insert these `Next' and @samp{(dir)} pointers |
| automatically.)@refill |
| |
| @xref{Install an Info File}, for more information about installing |
| an Info file in the @file{info} directory.@refill |
| |
| The `Top' node contains the main or master menu for the document. |
| |
| @node makeinfo top command, Top Node Summary, First Node, node |
| @comment node-name, next, previous, up |
| @subsection The @code{@@top} Sectioning Command |
| @findex top @r{(@@-command)} |
| |
| A special sectioning command, @code{@@top}, has been created for use |
| with the @code{@@node Top} line. The @code{@@top} sectioning command tells |
| @code{makeinfo} that it marks the `Top' node in the file. It provides |
| the information that @code{makeinfo} needs to insert node |
| pointers automatically. Write the @code{@@top} command at the |
| beginning of the line immediately following the @code{@@node Top} |
| line. Write the title on the remaining part of the same line as the |
| @code{@@top} command.@refill |
| |
| In Info, the @code{@@top} sectioning command causes the title to appear on a |
| line by itself, with a line of asterisks inserted underneath.@refill |
| |
| In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} |
| sectioning command is merely a synonym for @code{@@unnumbered}. |
| Neither of these formatters require an @code{@@top} command, and do |
| nothing special with it. You can use @code{@@chapter} or |
| @code{@@unnumbered} after the @code{@@node Top} line when you use |
| these formatters. Also, you can use @code{@@chapter} or |
| @code{@@unnumbered} when you use the Texinfo updating commands to |
| create or update pointers and menus.@refill |
| |
| @node Top Node Summary, , makeinfo top command, node |
| @subsection The `Top' Node Summary |
| @cindex @samp{@r{Top}} node summary |
| |
| You can help readers by writing a summary in the `Top' node, after the |
| @code{@@top} line, before the main or master menu. The summary should |
| briefly describe the document. In Info, this summary will appear just |
| before the master menu. In a printed manual, this summary will appear |
| on a page of its own.@refill |
| |
| If you do not want the summary to appear on a page of its own in a |
| printed manual, you can enclose the whole of the `Top' node, including |
| the @code{@@node Top} line and the @code{@@top} sectioning command line |
| or other sectioning command line between @code{@@ifinfo} and @code{@@end |
| ifinfo}. This prevents any of the text from appearing in the printed |
| output. (@pxref{Conditionals, , Conditionally Visible Text}). You can |
| repeat the brief description from the `Top' node within @code{@@iftex} |
| @dots{} @code{@@end iftex} at the beginning of the first chapter, for |
| those who read the printed manual. This saves paper and may look |
| neater.@refill |
| |
| You should write the version number of the program to which the manual |
| applies in the summary. This helps the reader keep track of which |
| manual is for which version of the program. If the manual changes more |
| frequently than the program or is independent of it, you should also |
| include an edition number for the manual. (The title page should also |
| contain this information: see @ref{titlepage, , |
| @code{@@titlepage}}.)@refill |
| |
| @node makeinfo Pointer Creation, , node, Nodes |
| @section Creating Pointers with @code{makeinfo} |
| @cindex Creating pointers with @code{makeinfo} |
| @cindex Pointer creation with @code{makeinfo} |
| @cindex Automatic pointer creation with @code{makeinfo} |
| |
| The @code{makeinfo} program has a feature for automatically creating |
| node pointers for a hierarchically organized file that lacks |
| them.@refill |
| |
| When you take advantage of this feature, you do not need to write the |
| `Next', `Previous', and `Up' pointers after the name of a node. |
| However, you must write a sectioning command, such as @code{@@chapter} |
| or @code{@@section}, on the line immediately following each truncated |
| @code{@@node} line. You cannot write a comment line after a node |
| line; the section line must follow it immediately.@refill |
| |
| In addition, you must follow the `Top' @code{@@node} line with a line beginning |
| with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo |
| top, , @code{@@top}}. |
| |
| Finally, you must write the name of each node (except for the `Top' |
| node) in a menu that is one or more hierarchical levels above the |
| node's hierarchical level.@refill |
| |
| This node pointer insertion feature in @code{makeinfo} is an |
| alternative to the menu and pointer creation and update commands in |
| Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially |
| helpful to people who do not use GNU Emacs for writing Texinfo |
| documents.@refill |
| |
| @node Menus, Cross References, Nodes, Top |
| @comment node-name, next, previous, up |
| @chapter Menus |
| @cindex Menus |
| @findex menu |
| |
| @dfn{Menus} contain pointers to subordinate |
| nodes.@footnote{Menus can carry you to any node, regardless |
| of the hierarchical structure; even to nodes in a different |
| Info file. However, the GNU Emacs Texinfo mode updating |
| commands work only to create menus of subordinate nodes. |
| Conventionally, cross references are used to refer to other |
| nodes.} In Info, you use menus to go to such nodes. Menus |
| have no effect in printed manuals and do not appear in |
| them.@refill |
| |
| By convention, a menu is put at the end of a node since a reader who |
| uses the menu may not see text that follows it.@refill |
| |
| @ifinfo |
| A node that has a menu should @emph{not} contain much text. If you |
| have a lot of text and a menu, move most of the text into a new |
| subnode---all but a few lines.@refill |
| @end ifinfo |
| @iftex |
| @emph{A node that has a menu should not contain much text.} If you |
| have a lot of text and a menu, move most of the text into a new |
| subnode---all but a few lines. Otherwise, a reader with a terminal |
| that displays only a few lines may miss the menu and its associated |
| text. As a practical matter, you should locate a menu within 20 lines |
| of the beginning of the node.@refill |
| @end iftex |
| |
| @menu |
| * Menu Location:: Put a menu in a short node. |
| * Writing a Menu:: What is a menu? |
| * Menu Parts:: A menu entry has three parts. |
| * Less Cluttered Menu Entry:: Two part menu entry. |
| * Menu Example:: Two and three part menu entries. |
| * Other Info Files:: How to refer to a different Info file. |
| @end menu |
| |
| @node Menu Location, Writing a Menu, Menus, Menus |
| @ifinfo |
| @heading Menus Need Short Nodes |
| @end ifinfo |
| @cindex Menu location |
| @cindex Location of menus |
| @cindex Nodes for menus are short |
| @cindex Short nodes for menus |
| |
| @ifinfo |
| A reader can easily see a menu that is close to the beginning of the |
| node. The node should be short. As a practical matter, you should |
| locate a menu within 20 lines of the beginning of the node. |
| Otherwise, a reader with a terminal that displays only a few lines may |
| miss the menu and its associated text.@refill |
| @end ifinfo |
| |
| The short text before a menu may look awkward in a printed manual. To |
| avoid this, you can write a menu near the beginning of its node and |
| follow the menu by an @code{@@node} line, and then an @code{@@heading} |
| line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, |
| the menu, @code{@@node} line, and title appear only in the Info file, |
| not the printed document.@refill |
| |
| For example, the preceding two paragraphs follow an Info-only menu, |
| @code{@@node} line, and heading, and look like this:@refill |
| |
| @example |
| @group |
| @@menu |
| * Menu Location:: Put a menu in a short node. |
| * Writing a Menu:: What is a menu? |
| * Menu Parts:: A menu entry has three parts. |
| * Less Cluttered Menu Entry:: Two part menu entry. |
| * Menu Example:: Two and three part entries. |
| * Other Info Files:: How to refer to a different |
| Info file. |
| @@end menu |
| |
| @@node Menu Location, Writing a Menu, , Menus |
| @@ifinfo |
| @@heading Menus Need Short Nodes |
| @@end ifinfo |
| @end group |
| @end example |
| |
| The Texinfo file for this document contains more than a dozen |
| examples of this procedure. One is at the beginning of this chapter; |
| another is at the beginning of the ``Cross References'' chapter.@refill |
| |
| @node Writing a Menu, Menu Parts, Menu Location, Menus |
| @section Writing a Menu |
| @cindex Writing a menu |
| @cindex Menu writing |
| |
| A menu consists of an @code{@@menu} command on a line by |
| itself followed by menu entry lines or menu comment lines |
| and then by an @code{@@end menu} command on a line by |
| itself.@refill |
| |
| A menu looks like this:@refill |
| |
| @example |
| @group |
| @@menu |
| Larger Units of Text |
| |
| * Files:: All about handling files. |
| * Multiples: Buffers. Multiple buffers; editing |
| several files at once. |
| @@end menu |
| @end group |
| @end example |
| |
| In a menu, every line that begins with an @w{@samp{* }} is a |
| @dfn{menu entry}. (Note the space after the asterisk.) A |
| line that does not start with an @w{@samp{* }} may also |
| appear in a menu. Such a line is not a menu entry but is a |
| menu comment line that appears in the Info file. In |
| the example above, the line @samp{Larger Units of Text} is a |
| menu comment line; the two lines starting with @w{@samp{* }} |
| are menu entries. |
| |
| @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus |
| @section The Parts of a Menu |
| @cindex Parts of a menu |
| @cindex Menu parts |
| @cindex @code{@@menu} parts |
| |
| A menu entry has three parts, only the second of which is |
| required:@refill |
| |
| @enumerate |
| @item |
| The menu entry name. |
| |
| @item |
| The name of the node (required). |
| |
| @item |
| A description of the item. |
| @end enumerate |
| |
| The template for a menu entry looks like this:@refill |
| |
| @example |
| * @var{menu-entry-name}: @var{node-name}. @var{description} |
| @end example |
| |
| Follow the menu entry name with a single colon and follow the node name |
| with tab, comma, period, or newline.@refill |
| |
| In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) |
| command. The menu entry name is what the user types after the @kbd{m} |
| command.@refill |
| |
| The third part of a menu entry is a descriptive phrase or |
| sentence. Menu entry names and node names are often short; the |
| description explains to the reader what the node is about. The |
| description, which is optional, can spread over two or more lines. A |
| useful description complements the node name rather than repeats |
| it.@refill |
| |
| @node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus |
| @comment node-name, next, previous, up |
| @section Less Cluttered Menu Entry |
| @cindex Two part menu entry |
| @cindex Double-colon menu entries |
| @cindex Menu entries with two colons |
| @cindex Less cluttered menu entry |
| @cindex Uncluttered menu entry |
| |
| When the menu entry name and node name are the same, you can write |
| the name immediately after the asterisk and space at the beginning of |
| the line and follow the name with two colons.@refill |
| |
| @need 800 |
| For example, write |
| |
| @example |
| * Name:: @var{description} |
| @end example |
| |
| @need 800 |
| @noindent |
| instead of |
| |
| @example |
| * Name: Name. @var{description} |
| @end example |
| |
| You should use the node name for the menu entry name whenever possible, |
| since it reduces visual clutter in the menu.@refill |
| |
| @node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus |
| @comment node-name, next, previous, up |
| @section A Menu Example |
| @cindex Menu example |
| @cindex Example menu |
| |
| A menu looks like this in Texinfo:@refill |
| |
| @example |
| @group |
| @@menu |
| * menu entry name: Node name. A short description. |
| * Node name:: This form is preferred. |
| @@end menu |
| @end group |
| @end example |
| |
| @need 800 |
| @noindent |
| This produces: |
| |
| @example |
| @group |
| * menu: |
| |
| * menu entry name: Node name. A short description. |
| * Node name:: This form is preferred. |
| @end group |
| @end example |
| |
| @need 700 |
| Here is an example as you might see it in a Texinfo file:@refill |
| |
| @example |
| @group |
| @@menu |
| Larger Units of Text |
| |
| * Files:: All about handling files. |
| * Multiples: Buffers. Multiple buffers; editing |
| several files at once. |
| @@end menu |
| @end group |
| @end example |
| |
| @need 800 |
| @noindent |
| This produces: |
| |
| @example |
| @group |
| * menu: |
| Larger Units of Text |
| |
| * Files:: All about handling files. |
| * Multiples: Buffers. Multiple buffers; editing |
| several files at once. |
| @end group |
| @end example |
| |
| In this example, the menu has two entries. @samp{Files} is both a menu |
| entry name and the name of the node referred to by that name. |
| @samp{Multiples} is the menu entry name; it refers to the node named |
| @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it |
| appears in the menu, but is not an entry.@refill |
| |
| Since no file name is specified with either @samp{Files} or |
| @samp{Buffers}, they must be the names of nodes in the same Info file |
| (@pxref{Other Info Files, , Referring to Other Info Files}).@refill |
| |
| @node Other Info Files, , Menu Example, Menus |
| @comment node-name, next, previous, up |
| @section Referring to Other Info Files |
| @cindex Referring to other Info files |
| @cindex Nodes in other Info files |
| @cindex Other Info files' nodes |
| @cindex Going to other Info files' nodes |
| @cindex Info; other files' nodes |
| |
| You can create a menu entry that enables a reader in Info to go to a |
| node in another Info file by writing the file name in parentheses just |
| before the node name. In this case, you should use the three-part menu |
| entry format, which saves the reader from having to type the file |
| name.@refill |
| |
| @need 800 |
| The format looks like this:@refill |
| |
| @example |
| @group |
| @@menu |
| * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} |
| * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} |
| @@end menu |
| @end group |
| @end example |
| |
| For example, to refer directly to the @samp{Outlining} and |
| @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a |
| menu like this:@refill |
| |
| @example |
| @group |
| @@menu |
| * Outlining: (emacs)Outline Mode. The major mode for |
| editing outlines. |
| * Rebinding: (emacs)Rebinding. How to redefine the |
| meaning of a key. |
| @@end menu |
| @end group |
| @end example |
| |
| If you do not list the node name, but only name the file, then Info |
| presumes that you are referring to the `Top' node.@refill |
| |
| The @file{dir} file that contains the main menu for Info has menu |
| entries that list only file names. These take you directly to the `Top' |
| nodes of each Info document. (@xref{Install an Info File}.)@refill |
| |
| @need 700 |
| For example: |
| |
| @example |
| @group |
| * Info: (info). Documentation browsing system. |
| * Emacs: (emacs). The extensible, self-documenting |
| text editor. |
| @end group |
| @end example |
| |
| @noindent |
| (The @file{dir} top level directory for the Info system is an Info file, |
| not a Texinfo file, but a menu entry looks the same in both types of |
| file.)@refill |
| |
| Note that the GNU Emacs Texinfo mode menu updating commands only work |
| with nodes within the current buffer, so you cannot use them to create |
| menus that refer to other files. You must write such menus by hand.@refill |
| |
| @node Cross References, Marking Text, Menus, Top |
| @comment node-name, next, previous, up |
| @chapter Cross References |
| @cindex Making cross references |
| @cindex Cross references |
| @cindex References |
| |
| @dfn{Cross references} are used to refer the reader to other parts of the |
| same or different Texinfo files. In Texinfo, nodes are the |
| places to which cross references can refer.@refill |
| |
| @menu |
| * References:: What cross references are for. |
| * Cross Reference Commands:: A summary of the different commands. |
| * Cross Reference Parts:: A cross reference has several parts. |
| * xref:: Begin a reference with `See' @dots{} |
| * Top Node Naming:: How to refer to the beginning of another file. |
| * ref:: A reference for the last part of a sentence. |
| * pxref:: How to write a parenthetical cross reference. |
| * inforef:: How to refer to an Info-only file. |
| @end menu |
| |
| @node References, Cross Reference Commands, Cross References, Cross References |
| @ifinfo |
| @heading What References Are For |
| @end ifinfo |
| |
| Often, but not always, a printed document should be designed so that |
| it can be read sequentially. People tire of flipping back and forth |
| to find information that should be presented to them as they need |
| it.@refill |
| |
| However, in any document, some information will be too detailed for |
| the current context, or incidental to it; use cross references to |
| provide access to such information. Also, an on-line help system or a |
| reference manual is not like a novel; few read such documents in |
| sequence from beginning to end. Instead, people look up what they |
| need. For this reason, such creations should contain many cross |
| references to help readers find other information that they may not |
| have read.@refill |
| |
| In a printed manual, a cross reference results in a page reference, |
| unless it is to another manual altogether, in which case the cross |
| reference names that manual.@refill |
| |
| In Info, a cross reference results in an entry that you can follow using |
| the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info |
| commands, info}.)@refill |
| |
| The various cross reference commands use nodes to define cross |
| reference locations. This is evident in Info, in which a cross |
| reference takes you to the specified node. @TeX{} also uses nodes to |
| define cross reference locations, but the action is less obvious. When |
| @TeX{} generates a @sc{dvi} file, it records nodes' page numbers and |
| uses the page numbers in making references. Thus, if you are writing |
| a manual that will only be printed, and will not be used on-line, you |
| must nonetheless write @code{@@node} lines to name the places to which |
| you make cross references.@refill |
| |
| @need 800 |
| @node Cross Reference Commands, Cross Reference Parts, References, Cross References |
| @comment node-name, next, previous, up |
| @section Different Cross Reference Commands |
| @cindex Different cross reference commands |
| |
| There are four different cross reference commands:@refill |
| |
| @table @code |
| @item @@xref |
| Used to start a sentence in the printed manual saying @w{`See @dots{}'} |
| or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}. |
| |
| @item @@ref |
| Used within or, more often, at the end of a sentence; same as |
| @code{@@xref} for Info; produces just the reference in the printed |
| manual without a preceding `See'.@refill |
| |
| @item @@pxref |
| Used within parentheses to make a reference that suits both an Info |
| file and a printed book. Starts with a lower case `see' within the |
| printed manual. (@samp{p} is for `parenthesis'.)@refill |
| |
| @item @@inforef |
| Used to make a reference to an Info file for which there is no printed |
| manual.@refill |
| @end table |
| |
| @noindent |
| (The @code{@@cite} command is used to make references to books and |
| manuals for which there is no corresponding Info file and, therefore, |
| no node to which to point. @xref{cite, , @code{@@cite}}.)@refill |
| |
| @node Cross Reference Parts, xref, Cross Reference Commands, Cross References |
| @comment node-name, next, previous, up |
| @section Parts of a Cross Reference |
| @cindex Cross reference parts |
| @cindex Parts of a cross reference |
| |
| A cross reference command requires only one argument, which is the |
| name of the node to which it refers. But a cross reference command |
| may contain up to four additional arguments. By using these |
| arguments, you can provide a cross reference name for Info, a topic |
| description or section title for the printed output, the name of a |
| different Info file, and the name of a different printed |
| manual.@refill |
| |
| Here is a simple cross reference example:@refill |
| |
| @example |
| @@xref@{Node name@}. |
| @end example |
| |
| @noindent |
| which produces |
| |
| @example |
| *Note Node name::. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See Section @var{nnn} [Node name], page @var{ppp}. |
| @end quotation |
| |
| @need 700 |
| Here is an example of a full five-part cross reference:@refill |
| |
| @example |
| @group |
| @@xref@{Node name, Cross Reference Name, Particular Topic, |
| info-file-name, A Printed Manual@}, for details. |
| @end group |
| @end example |
| |
| @noindent |
| which produces |
| |
| @example |
| *Note Cross Reference Name: (info-file-name)Node name, |
| for details. |
| @end example |
| |
| @noindent |
| in Info and |
| |
| @quotation |
| See section ``Particular Topic'' in @i{A Printed Manual}, for details. |
| @end quotation |
| |
| @noindent |
| in a printed book. |
| |
| The five possible arguments for a cross reference are:@refill |
| |
| @enumerate |
| @item |
| The node name (required). This is the node to which the |
| cross reference takes you. In a printed document, the location of the |
| node provides the page reference only for references within the same |
| document.@refill |
| |
| @item |
| The cross reference name for the Info reference, if it is to be different |
| from the node name. If you include this argument, it argument becomes |
| the first part of the cross reference. It is usually omitted.@refill |
| |
| @item |
| A topic description or section name. Often, this is the title of the |
| section. This is used as the name of the reference in the printed |
| manual. If omitted, the node name is used.@refill |
| |
| @item |
| The name of the Info file in which the reference is located, if it is |
| different from the current file.@refill |
| |
| @item |
| The name of a printed manual from a different Texinfo file.@refill |
| @end enumerate |
| |
| The template for a full five argument cross reference looks like |
| this:@refill |
| |
| @example |
| @group |
| @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, |
| @var{info-file-name}, @var{printed-manual-title}@}. |
| @end group |
| @end example |
| |
| Cross references with one, two, three, four, and five arguments are |
| described separately following the description of @code{@@xref}.@refill |
| |
| Write a node name in a cross reference in exactly the same way as in |
| the @code{@@node} line, including the same capitalization; otherwise, the |
| formatters may not find the reference.@refill |
| |
| You can write cross reference commands within a paragraph, but note |
| how Info and @TeX{} format the output of each of the various commands: |
| write @code{@@xref} at the beginning of a sentence; write |
| @code{@@pxref} only within parentheses, and so on.@refill |
| |
| @node xref, Top Node Naming, Cross Reference Parts, Cross References |
| @comment node-name, next, previous, up |
| @section @code{@@xref} |
| @findex xref |
| @cindex Cross references using @code{@@xref} |
| @cindex References using @code{@@xref} |
| |
| The @code{@@xref} command generates a cross reference for the |
| beginning of a sentence. The Info formatting commands convert it into |
| an Info cross reference, which the Info @samp{f} command can use to |
| bring you directly to another node. The @TeX{} typesetting commands |
| convert it into a page reference, or a reference to another book or |
| manual.@refill |
| |
| @menu |
| * Reference Syntax:: What a reference looks like and requires. |
| * One Argument:: @code{@@xref} with one argument. |
| * Two Arguments:: @code{@@xref} with two arguments. |
| * Three Arguments:: @code{@@xref} with three arguments. |
| * Four and Five Arguments:: @code{@@xref} with four and five arguments. |
| @end menu |
| |
| @node Reference Syntax, One Argument, xref, xref |
| @ifinfo |
| @subheading What a Reference Looks Like and Requires |
| @end ifinfo |
| |
| Most often, an Info cross reference looks like this:@refill |
| |
| @example |
| *Note @var{node-name}::. |
| @end example |
| |
| @noindent |
| or like this |
| |
| @example |
| *Note @var{cross-reference-name}: @var{node-name}. |
| @end example |
| |
| @noindent |
| In @TeX{}, a cross reference looks like this: |
| |
| @example |
| See Section @var{section-number} [@var{node-name}], page @var{page}. |
| @end example |
| |
| @noindent |
| or like this |
| |
| @example |
| See Section @var{section-number} [@var{title-or-topic}], page @var{page}. |
| @end example |
| |
| The @code{@@xref} command does not generate a period or comma to end |
| the cross reference in either the Info file or the printed output. |
| You must write that period or comma yourself; otherwise, Info will not |
| recognize the end of the reference. (The @code{@@pxref} command works |
| differently. @xref{pxref, , @code{@@pxref}}.)@refill |
| |
| @quotation |
| @strong{Please note:} A period or comma @strong{must} follow the closing |
| brace of an @code{@@xref}. It is required to terminate the cross |
| reference. This period or comma will appear in the output, both in |
| the Info file and in the printed manual.@refill |
| @end quotation |
| |
| @code{@@xref} must refer to an Info node by name. Use @code{@@node} |
| to define the node (@pxref{Writing a Node}).@refill |
| |
| @code{@@xref} is followed by several arguments inside braces, separated by |
| commas. Whitespace before and after these commas is ignored.@refill |
| |
| A cross reference requires only the name of a node; but it may contain |
| up to four additional arguments. Each of these variations produces a |
| cross reference that looks somewhat different.@refill |
| |
| @quotation |
| @strong{Please note:} Commas separate arguments in a cross reference; |
| avoid including them in the title or other part lest the formatters |
| mistake them for separators.@refill |
| @end quotation |
| |
| @node One Argument, Two Arguments, Reference Syntax, xref |
| @subsection @code{@@xref} with One Argument |
| |
| The simplest form of @code{@@xref} takes one argument, the name of |
| another node in the same Info file. The Info formatters produce |
| output that the Info readers can use to jump to the reference; @TeX{} |
| produces output that specifies the page and section number for you.@refill |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| @@xref@{Tropical Storms@}. |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| *Note Tropical Storms::. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See Section 3.1 [Tropical Storms], page 24. |
| @end quotation |
| |
| @noindent |
| (Note that in the preceding example the closing brace is followed by a |
| period.)@refill |
| |
| You can write a clause after the cross reference, like this:@refill |
| |
| @example |
| @@xref@{Tropical Storms@}, for more info. |
| @end example |
| |
| @noindent |
| which produces |
| |
| @example |
| *Note Tropical Storms::, for more info. |
| @end example |
| |
| @quotation |
| See Section 3.1 [Tropical Storms], page 24, for more info. |
| @end quotation |
| |
| @noindent |
| (Note that in the preceding example the closing brace is followed by a |
| comma, and then by the clause, which is followed by a period.)@refill |
| |
| @node Two Arguments, Three Arguments, One Argument, xref |
| @subsection @code{@@xref} with Two Arguments |
| |
| With two arguments, the second is used as the name of the Info cross |
| reference, while the first is still the name of the node to which the |
| cross reference points.@refill |
| |
| @need 750 |
| @noindent |
| The template is like this: |
| |
| @example |
| @@xref@{@var{node-name}, @var{cross-reference-name}@}. |
| @end example |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| @@xref@{Electrical Effects, Lightning@}. |
| @end example |
| |
| @noindent |
| produces: |
| |
| @example |
| *Note Lightning: Electrical Effects. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See Section 5.2 [Electrical Effects], page 57. |
| @end quotation |
| |
| @noindent |
| (Note that in the preceding example the closing brace is followed by a |
| period; and that the node name is printed, not the cross reference name.)@refill |
| |
| You can write a clause after the cross reference, like this:@refill |
| |
| @example |
| @@xref@{Electrical Effects, Lightning@}, for more info. |
| @end example |
| |
| @noindent |
| which produces |
| @example |
| *Note Lightning: Electrical Effects, for more info. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See Section 5.2 [Electrical Effects], page 57, for more info. |
| @end quotation |
| |
| @noindent |
| (Note that in the preceding example the closing brace is followed by a |
| comma, and then by the clause, which is followed by a period.)@refill |
| |
| @node Three Arguments, Four and Five Arguments, Two Arguments, xref |
| @subsection @code{@@xref} with Three Arguments |
| |
| A third argument replaces the node name in the @TeX{} output. The third |
| argument should be the name of the section in the printed output, or |
| else state the topic discussed by that section. Often, you will want to |
| use initial upper case letters so it will be easier to read when the |
| reference is printed. Use a third argument when the node name is |
| unsuitable because of syntax or meaning.@refill |
| |
| Remember to avoid placing a comma within the title or topic section of |
| a cross reference, or within any other section. The formatters divide |
| cross references into arguments according to the commas; a comma |
| within a title or other section will divide it into two arguments. In |
| a reference, you need to write a title such as ``Clouds, Mist, and |
| Fog'' without the commas.@refill |
| |
| Also, remember to write a comma or period after the closing brace of a |
| @code{@@xref} to terminate the cross reference. In the following |
| examples, a clause follows a terminating comma.@refill |
| |
| |
| @need 750 |
| @noindent |
| The template is like this: |
| |
| @example |
| @group |
| @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. |
| @end group |
| @end example |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| @@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, |
| for details. |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| *Note Lightning: Electrical Effects, for details. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See Section 5.2 [Thunder and Lightning], page 57, for details. |
| @end quotation |
| |
| If a third argument is given and the second one is empty, then the |
| third argument serves both. (Note how two commas, side by side, mark |
| the empty second argument.)@refill |
| |
| @example |
| @group |
| @@xref@{Electrical Effects, , Thunder and Lightning@}, |
| for details. |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| *Note Thunder and Lightning: Electrical Effects, for details. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See Section 5.2 [Thunder and Lightning], page 57, for details. |
| @end quotation |
| |
| As a practical matter, it is often best to write cross references with |
| just the first argument if the node name and the section title are the |
| same, and with the first and third arguments if the node name and title |
| are different.@refill |
| |
| Here are several examples from @cite{The GAWK Manual}:@refill |
| |
| @smallexample |
| @@xref@{Sample Program@}. |
| @@xref@{Glossary@}. |
| @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. |
| @@xref@{Close Output, , Closing Output Files and Pipes@}, |
| for more information. |
| @@xref@{Regexp, , Regular Expressions as Patterns@}. |
| @end smallexample |
| |
| @node Four and Five Arguments, , Three Arguments, xref |
| @subsection @code{@@xref} with Four and Five Arguments |
| |
| In a cross reference, a fourth argument specifies the name of another |
| Info file, different from the file in which the reference appears, and |
| a fifth argument specifies its title as a printed manual.@refill |
| |
| Remember that a comma or period must follow the closing brace of an |
| @code{@@xref} command to terminate the cross reference. In the |
| following examples, a clause follows a terminating comma.@refill |
| |
| @need 800 |
| @noindent |
| The template is: |
| |
| @example |
| @group |
| @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, |
| @var{info-file-name}, @var{printed-manual-title}@}. |
| @end group |
| @end example |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| @@xref@{Electrical Effects, Lightning, Thunder and Lightning, |
| weather, An Introduction to Meteorology@}, for details. |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| *Note Lightning: (weather)Electrical Effects, for details. |
| @end example |
| |
| @noindent |
| The name of the Info file is enclosed in parentheses and precedes |
| the name of the node. |
| |
| @noindent |
| In a printed manual, the reference looks like this:@refill |
| |
| @quotation |
| See section ``Thunder and Lightning'' in @i{An Introduction to |
| Meteorology}, for details. |
| @end quotation |
| |
| @noindent |
| The title of the printed manual is typeset in italics; and the |
| reference lacks a page number since @TeX{} cannot know to which page a |
| reference refers when that reference is to another manual.@refill |
| |
| Often, you will leave out the second argument when you use the long |
| version of @code{@@xref}. In this case, the third argument, the topic |
| description, will be used as the cross reference name in Info.@refill |
| |
| @noindent |
| The template looks like this: |
| |
| @example |
| @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, |
| @var{printed-manual-title}@}, for details. |
| @end example |
| |
| @noindent |
| which produces |
| |
| @example |
| *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See section @var{title-or-topic} in @var{printed-manual-title}, for details. |
| @end quotation |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| @@xref@{Electrical Effects, , Thunder and Lightning, |
| weather, An Introduction to Meteorology@}, for details. |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| *Note Thunder and Lightning: (weather)Electrical Effects, |
| for details. |
| @end group |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See section ``Thunder and Lightning'' in @i{An Introduction to |
| Meteorology}, for details. |
| @end quotation |
| |
| On rare occasions, you may want to refer to another Info file that |
| is within a single printed manual---when multiple Texinfo files are |
| incorporated into the same @TeX{} run but make separate Info files. |
| In this case, you need to specify only the fourth argument, and not |
| the fifth.@refill |
| |
| @node Top Node Naming, ref, xref, Cross References |
| @section Naming a `Top' Node |
| @cindex Naming a `Top' Node in references |
| @cindex @samp{@r{Top}} node naming for references |
| |
| In a cross reference, you must always name a node. This means that in |
| order to refer to a whole manual, you must identify the `Top' node by |
| writing it as the first argument to the @code{@@xref} command. (This |
| is different from the way you write a menu entry; see @ref{Other Info |
| Files, , Referring to Other Info Files}.) At the same time, to |
| provide a meaningful section topic or title in the printed cross |
| reference (instead of the word `Top'), you must write an appropriate |
| entry for the third argument to the @code{@@xref} command. |
| @refill |
| |
| @noindent |
| Thus, to make a cross reference to @cite{The GNU Make Manual}, |
| write:@refill |
| |
| @example |
| @@xref@{Top, , Overview, make, The GNU Make Manual@}. |
| @end example |
| |
| @noindent |
| which produces |
| |
| @example |
| *Note Overview: (make)Top. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| See section ``Overview'' in @i{The GNU Make Manual}. |
| @end quotation |
| |
| @noindent |
| In this example, @samp{Top} is the name of the first node, and |
| @samp{Overview} is the name of the first section of the manual.@refill |
| @node ref, pxref, Top Node Naming, Cross References |
| @comment node-name, next, previous, up |
| @section @code{@@ref} |
| @cindex Cross references using @code{@@ref} |
| @cindex References using @code{@@ref} |
| @findex ref |
| |
| @code{@@ref} is nearly the same as @code{@@xref} except that it does |
| not generate a `See' in the printed output, just the reference itself. |
| This makes it useful as the last part of a sentence.@refill |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| For more information, see @@ref@{Hurricanes@}. |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| For more information, see *Note Hurricanes. |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| For more information, see Section 8.2 [Hurricanes], page 123. |
| @end quotation |
| |
| The @code{@@ref} command sometimes leads writers to express themselves |
| in a manner that is suitable for a printed manual but looks awkward |
| in the Info format. Bear in mind that your audience will be using |
| both the printed and the Info format.@refill |
| |
| @need 800 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| Sea surges are described in @@ref@{Hurricanes@}. |
| @end group |
| @end example |
| |
| @need 800 |
| @noindent |
| produces |
| |
| @quotation |
| Sea surges are described in Section 6.7 [Hurricanes], page 72. |
| @end quotation |
| |
| @need 800 |
| @noindent |
| in a printed document, and the following in Info: |
| |
| @example |
| Sea surges are described in *Note Hurricanes::. |
| @end example |
| |
| @quotation |
| @strong{Caution:} You @emph{must} write a period or comma immediately |
| after an @code{@@ref} command with two or more arguments. Otherwise, |
| Info will not find the end of the cross reference entry and its |
| attempt to follow the cross reference will fail. As a general rule, |
| you should write a period or comma after every @code{@@ref} command. |
| This looks best in both the printed and the Info output.@refill |
| @end quotation |
| |
| @node pxref, inforef, ref, Cross References |
| @comment node-name, next, previous, up |
| @section @code{@@pxref} |
| @cindex Cross references using @code{@@pxref} |
| @cindex References using @code{@@pxref} |
| @findex pxref |
| |
| The parenthetical reference command, @code{@@pxref}, is nearly the |
| same as @code{@@xref}, but you use it @emph{only} inside parentheses |
| and you do @emph{not} type a comma or period after the command's |
| closing brace. The command differs from @code{@@xref} in two |
| ways:@refill |
| |
| @enumerate |
| @item |
| @TeX{} typesets the reference for the printed manual with a lower case |
| `see' rather than an upper case `See'.@refill |
| |
| @item |
| The Info formatting commands automatically end the reference with a |
| closing colon or period.@refill |
| @end enumerate |
| |
| Because one type of formatting automatically inserts closing |
| punctuation and the other does not, you should use @code{@@pxref} |
| @emph{only} inside parentheses as part of another sentence. Also, you |
| yourself should not insert punctuation after the reference, as you do |
| with @code{@@xref}.@refill |
| |
| @code{@@pxref} is designed so that the output looks right and works |
| right between parentheses both in printed output and in an Info file. |
| In a printed manual, a closing comma or period should not follow a |
| cross reference within parentheses; such punctuation is wrong. But in |
| an Info file, suitable closing punctuation must follow the cross |
| reference so Info can recognize its end. @code{@@pxref} spares you |
| the need to use complicated methods to put a terminator into one form |
| of the output and not the other.@refill |
| |
| @noindent |
| With one argument, a parenthetical cross reference looks like |
| this:@refill |
| |
| @example |
| @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} |
| @end example |
| |
| @need 800 |
| @noindent |
| which produces |
| |
| @example |
| @group |
| @dots{} storms cause flooding (*Note Hurricanes::) @dots{} |
| @end group |
| @end example |
| |
| @noindent |
| and |
| |
| @quotation |
| @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} |
| @end quotation |
| |
| With two arguments, a parenthetical cross reference has this |
| template:@refill |
| |
| @example |
| @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} |
| @end example |
| |
| @noindent |
| which produces |
| |
| @example |
| @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{} |
| @end example |
| |
| @noindent |
| and |
| |
| @need 1500 |
| @quotation |
| @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} |
| @end quotation |
| |
| @code{@@pxref} can be used with up to five arguments just like |
| @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill |
| |
| @quotation |
| @strong{Please note:} Use @code{@@pxref} only as a parenthetical |
| reference. Do not try to use @code{@@pxref} as a clause in a sentence. |
| It will look bad in either the Info file, the printed output, or |
| both.@refill |
| |
| Also, parenthetical cross references look best at the ends of sentences. |
| Although you may write them in the middle of a sentence, that location |
| breaks up the flow of text.@refill |
| @end quotation |
| |
| @node inforef, , pxref, Cross References |
| @comment node-name, next, previous, up |
| @section @code{@@inforef} |
| @cindex Cross references using @code{@@inforef} |
| @cindex References using @code{@@inforef} |
| @findex inforef |
| |
| @code{@@inforef} is used for cross references to Info files for which |
| there are no printed manuals. Even in a printed manual, |
| @code{@@inforef} generates a reference directing the user to look in |
| an Info file.@refill |
| |
| The command takes either two or three arguments, in the following |
| order:@refill |
| |
| @enumerate |
| @item |
| The node name. |
| |
| @item |
| The cross reference name (optional). |
| |
| @item |
| The Info file name. |
| @end enumerate |
| |
| @noindent |
| Separate the arguments with commas, as with @code{@@xref}. Also, you |
| must terminate the reference with a comma or period after the |
| @samp{@}}, as you do with @code{@@xref}.@refill |
| |
| @noindent |
| The template is: |
| |
| @example |
| @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, |
| @end example |
| |
| @need 800 |
| @noindent |
| Thus, |
| |
| @example |
| @group |
| @@inforef@{Expert, Advanced Info commands, info@}, |
| for more information. |
| @end group |
| @end example |
| |
| @need 800 |
| @noindent |
| produces |
| |
| @example |
| @group |
| *Note Advanced Info commands: (info)Expert, |
| for more information. |
| @end group |
| @end example |
| |
| @need 800 |
| @noindent |
| and |
| |
| @quotation |
| See Info file @file{info}, node @samp{Expert}, for more information. |
| @end quotation |
| |
| @need 800 |
| @noindent |
| Similarly, |
| |
| @example |
| @group |
| @@inforef@{Expert, , info@}, for more information. |
| @end group |
| @end example |
| |
| @need 800 |
| @noindent |
| produces |
| |
| @example |
| *Note (info)Expert::, for more information. |
| @end example |
| |
| @need 800 |
| @noindent |
| and |
| |
| @quotation |
| See Info file @file{info}, node @samp{Expert}, for more information. |
| @end quotation |
| |
| The converse of @code{@@inforef} is @code{@@cite}, which is used to |
| refer to printed works for which no Info form exists. @xref{cite, , |
| @code{@@cite}}.@refill |
| |
| @node Marking Text, Quotations and Examples, Cross References, Top |
| @comment node-name, next, previous, up |
| @chapter Marking Words and Phrases |
| @cindex Paragraph, marking text within |
| @cindex Marking words and phrases |
| @cindex Words and phrases, marking them |
| @cindex Marking text within a paragraph |
| |
| In Texinfo, you can mark words and phrases in a variety of ways. |
| The Texinfo formatters use this information to determine how to |
| highlight the text. |
| You can specify, for example, whether a word or phrase is a |
| defining occurrence, a metasyntactic variable, or a symbol used in a |
| program. Also, you can emphasize text.@refill |
| |
| @menu |
| * Indicating:: How to indicate definitions, files, etc. |
| * Emphasis:: How to emphasize text. |
| @end menu |
| |
| @node Indicating, Emphasis, Marking Text, Marking Text |
| @comment node-name, next, previous, up |
| @section Indicating Definitions, Commands, etc. |
| @cindex Highlighting text |
| @cindex Indicating commands, definitions, etc. |
| |
| Texinfo has commands for indicating just what kind of object a piece of |
| text refers to. For example, metasyntactic variables are marked by |
| @code{@@var}, and code by @code{@@code}. Since the pieces of text are |
| labelled by commands that tell what kind of object they are, it is easy |
| to change the way the Texinfo formatters prepare such text. (Texinfo is |
| an @emph{intentional} formatting language rather than a @emph{typesetting} |
| formatting language.)@refill |
| |
| For example, in a printed manual, |
| code is usually illustrated in a typewriter font; |
| @code{@@code} tells @TeX{} to typeset this text in this font. But it |
| would be easy to change the way @TeX{} highlights code to use another |
| font, and this change would not effect how keystroke examples are |
| highlighted. If straight typesetting commands were used in the body |
| of the file and you wanted to make a change, you would need to check |
| every single occurrence to make sure that you were changing code and |
| not something else that should not be changed.@refill |
| |
| @menu |
| * Useful Highlighting:: Highlighting provides useful information. |
| * code:: How to indicate code. |
| * kbd:: How to show keyboard input. |
| * key:: How to specify keys. |
| * samp:: How to show a literal sequence of characters. |
| * var:: How to indicate a metasyntactic variable. |
| * file:: How to indicate the name of a file. |
| * dfn:: How to specify a definition. |
| * cite:: How to refer to a book that is not in Info. |
| * url:: How to indicate a world wide web reference. |
| * email:: How to indicate an electronic mail address. |
| @end menu |
| |
| @node Useful Highlighting, code, Indicating, Indicating |
| @ifinfo |
| @subheading Highlighting Commands are Useful |
| @end ifinfo |
| |
| The highlighting commands can be used to generate useful information |
| from the file, such as lists of functions or file names. It is |
| possible, for example, to write a program in Emacs Lisp (or a keyboard |
| macro) to insert an index entry after every paragraph that contains |
| words or phrases marked by a specified command. You could do this to |
| construct an index of functions if you had not already made the |
| entries.@refill |
| |
| The commands serve a variety of purposes:@refill |
| |
| @table @code |
| @item @@code@{@var{sample-code}@} |
| Indicate text that is a literal example of a piece of a program.@refill |
| |
| @item @@kbd@{@var{keyboard-characters}@} |
| Indicate keyboard input.@refill |
| |
| @item @@key@{@var{key-name}@} |
| Indicate the conventional name for a key on a keyboard.@refill |
| |
| @item @@samp@{@var{text}@} |
| Indicate text that is a literal example of a sequence of characters.@refill |
| |
| @item @@var@{@var{metasyntactic-variable}@} |
| Indicate a metasyntactic variable.@refill |
| |
| @item @@url@{@var{uniform-resource-locator}@} |
| Indicate a uniform resource locator for the World Wide Web. |
| |
| @item @@file@{@var{file-name}@} |
| Indicate the name of a file.@refill |
| |
| @item @@email@{@var{email-address}@} |
| Indicate an electronic mail address. |
| |
| @item @@dfn@{@var{term}@} |
| Indicate the introductory or defining use of a term.@refill |
| |
| @item @@cite@{@var{reference}@} |
| Indicate the name of a book.@refill |
| |
| @ignore |
| @item @@ctrl@{@var{ctrl-char}@} |
| Use for an @sc{ascii} control character.@refill |
| @end ignore |
| @end table |
| |
| @node code, kbd, Useful Highlighting, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@code}@{@var{sample-code}@} |
| @findex code |
| |
| Use the @code{@@code} command to indicate text that is a piece of a |
| program and which consists of entire syntactic tokens. Enclose the |
| text in braces.@refill |
| |
| Thus, you should use @code{@@code} for an expression in a program, for |
| the name of a variable or function used in a program, or for a |
| keyword. Also, you should use @code{@@code} for the name of a |
| program, such as @code{diff}, that is a name used in the machine. (You |
| should write the name of a program in the ordinary text font if you |
| regard it as a new English word, such as `Emacs' or `Bison'.)@refill |
| |
| Use @code{@@code} for environment variables such as @code{TEXINPUTS}, |
| and other variables.@refill |
| |
| Use @code{@@code} for command names in command languages that |
| resemble programming languages, such as Texinfo or the shell. |
| For example, @code{@@code} and @code{@@samp} are produced by writing |
| @samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo |
| source, respectively.@refill |
| |
| Note, however, that you should not use @code{@@code} for shell options |
| such as @samp{-c} when such options stand alone. (Use @code{@@samp}.) |
| Also, an entire shell command often looks better if written using |
| @code{@@samp} rather than @code{@@code}. In this case, the rule is to |
| choose the more pleasing format.@refill |
| |
| It is incorrect to alter the case of a word inside an @code{@@code} |
| command when it appears at the beginning of a sentence. Most computer |
| languages are case sensitive. In C, for example, @code{Printf} is |
| different from the identifier @code{printf}, and most likely is a |
| misspelling of it. Even in languages which are not case sensitive, it |
| is confusing to a human reader to see identifiers spelled in different |
| ways. Pick one spelling and always use that. If you do not want to |
| start a sentence with a command written all in lower case, you should |
| rearrange the sentence.@refill |
| |
| Do not use the @code{@@code} command for a string of characters shorter |
| than a syntactic token. If you are writing about @samp{TEXINPU}, which |
| is just a part of the name for the @code{TEXINPUTS} environment |
| variable, you should use @code{@@samp}.@refill |
| |
| In particular, you should not use the @code{@@code} command when writing |
| about the characters used in a token; do not, for example, use |
| @code{@@code} when you are explaining what letters or printable symbols |
| can be used in the names of functions. (Use @code{@@samp}.) Also, you |
| should not use @code{@@code} to mark text that is considered input to |
| programs unless the input is written in a language that is like a |
| programming language. For example, you should not use @code{@@code} for |
| the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although |
| you may use @code{@@code} for the names of the Emacs Lisp functions that |
| the keystroke commands invoke.@refill |
| |
| In the printed manual, @code{@@code} causes @TeX{} to typeset the |
| argument in a typewriter face. In the Info file, it causes the Info |
| formatting commands to use single quotation marks around the text. |
| |
| @need 700 |
| For example, |
| |
| @example |
| Use @@code@{diff@} to compare two files. |
| @end example |
| |
| @noindent |
| produces this in the printed manual:@refill |
| |
| @quotation |
| Use @code{diff} to compare two files. |
| @end quotation |
| @iftex |
| |
| @noindent |
| and this in the Info file:@refill |
| |
| @example |
| Use `diff' to compare two files. |
| @end example |
| @end iftex |
| |
| @node kbd, key, code, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@kbd}@{@var{keyboard-characters}@} |
| @findex kbd |
| |
| Use the @code{@@kbd} command for characters of input to be typed by |
| users. For example, to refer to the characters @kbd{M-a}, |
| write@refill |
| |
| @example |
| @@kbd@{M-a@} |
| @end example |
| |
| @noindent |
| and to refer to the characters @kbd{M-x shell}, write@refill |
| |
| @example |
| @@kbd@{M-x shell@} |
| @end example |
| |
| The @code{@@kbd} command has the same effect as @code{@@code} in Info, |
| but may produce a different font in a printed manual.@refill |
| |
| You can embed another @@-command inside the braces of an @code{@@kbd} |
| command. Here, for example, is the way to describe a command that |
| would be described more verbosely as ``press an @samp{r} and then |
| press the @key{RET} key'':@refill |
| |
| @example |
| @@kbd@{r @@key@{RET@}@} |
| @end example |
| |
| @noindent |
| This produces: @kbd{r @key{RET}} |
| |
| You also use the @code{@@kbd} command if you are spelling out the letters |
| you type; for example:@refill |
| |
| @example |
| To give the @@code@{logout@} command, |
| type the characters @@kbd@{l o g o u t @@key@{RET@}@}. |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @quotation |
| To give the @code{logout} command, |
| type the characters @kbd{l o g o u t @key{RET}}. |
| @end quotation |
| |
| (Also, this example shows that you can add spaces for clarity. If you |
| really want to mention a space character as one of the characters of |
| input, write @kbd{@@key@{SPC@}} for it.)@refill |
| |
| @node key, samp, kbd, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@key}@{@var{key-name}@} |
| @findex key |
| |
| Use the @code{@@key} command for the conventional name for a key on a |
| keyboard, as in:@refill |
| |
| @example |
| @@key@{RET@} |
| @end example |
| |
| You can use the @code{@@key} command within the argument of an |
| @code{@@kbd} command when the sequence of characters to be typed |
| includes one or more keys that are described by name.@refill |
| |
| @need 700 |
| For example, to produce @kbd{C-x @key{ESC}} you would type:@refill |
| |
| @example |
| @@kbd@{C-x @@key@{ESC@}@} |
| @end example |
| |
| Here is a list of the recommended names for keys: |
| @cindex Recommended names for keys |
| @cindex Keys, recommended names |
| @cindex Names recommended for keys |
| @cindex Abbreviations for keys |
| |
| @quotation |
| @table @t |
| @item SPC |
| Space |
| @item RET |
| Return |
| @item LFD |
| Linefeed (however, since most keyboards nowadays do not have a Linefeed key, |
| it might be better to call this character @kbd{C-j}. |
| @item TAB |
| Tab |
| @item BS |
| Backspace |
| @item ESC |
| Escape |
| @item DEL |
| Delete |
| @item SHIFT |
| Shift |
| @item CTRL |
| Control |
| @item META |
| Meta |
| @end table |
| @end quotation |
| |
| @cindex META key |
| There are subtleties to handling words like `meta' or `ctrl' that are |
| names of shift keys. When mentioning a character in which the shift key |
| is used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone; do |
| not use the @code{@@key} command; but when you are referring to the |
| shift key in isolation, use the @code{@@key} command. For example, |
| write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and |
| @samp{@@key@{META@}} to produce @key{META}. |
| |
| @c I don't think this is a good explanation. |
| @c I think it will puzzle readers more than it clarifies matters. -- rms. |
| @c In other words, use @code{@@kbd} for what you do, and use @code{@@key} |
| @c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to |
| @c the beginning of the sentence. The @code{@@key@{META@}} key is often in |
| @c the lower left of the keyboard.''@refill |
| |
| @node samp, var, key, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@samp}@{@var{text}@} |
| @findex samp |
| |
| Use the @code{@@samp} command to indicate text that is a literal example |
| or `sample' of a sequence of characters in a file, string, pattern, etc. |
| Enclose the text in braces. The argument appears within single |
| quotation marks in both the Info file and the printed manual; in |
| addition, it is printed in a fixed-width font.@refill |
| |
| @example |
| To match @@samp@{foo@} at the end of the line, |
| use the regexp @@samp@{foo$@}. |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| To match @samp{foo} at the end of the line, use the regexp |
| @samp{foo$}.@refill |
| @end quotation |
| |
| Any time you are referring to single characters, you should use |
| @code{@@samp} unless @code{@@kbd} is more appropriate. Use |
| @code{@@samp} for the names of command-line options. Also, you may use |
| @code{@@samp} for entire statements in C and for entire shell |
| commands---in this case, @code{@@samp} often looks better than |
| @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is |
| not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill |
| |
| Only include punctuation marks within braces if they are part of the |
| string you are specifying. Write punctuation marks outside the braces |
| if those punctuation marks are part of the English text that surrounds |
| the string. In the following sentence, for example, the commas and |
| period are outside of the braces:@refill |
| |
| @example |
| @group |
| In English, the vowels are @@samp@{a@}, @@samp@{e@}, |
| @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes |
| @@samp@{y@}. |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @quotation |
| In English, the vowels are @samp{a}, @samp{e}, |
| @samp{i}, @samp{o}, @samp{u}, and sometimes |
| @samp{y}. |
| @end quotation |
| |
| @node var, file, samp, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@var}@{@var{metasyntactic-variable}@} |
| @findex var |
| |
| Use the @code{@@var} command to indicate metasyntactic variables. A |
| @dfn{metasyntactic variable} is something that stands for another piece of |
| text. For example, you should use a metasyntactic variable in the |
| documentation of a function to describe the arguments that are passed |
| to that function.@refill |
| |
| Do not use @code{@@var} for the names of particular variables in |
| programming languages. These are specific names from a program, so |
| @code{@@code} is correct for them. For example, the Lisp variable |
| @code{texinfo-tex-command} is not a metasyntactic variable; it is |
| properly formatted using @code{@@code}.@refill |
| |
| The effect of @code{@@var} in the Info file is to change the case of |
| the argument to all upper case; in the printed manual, to italicize it. |
| |
| @need 700 |
| For example, |
| |
| @example |
| To delete file @@var@{filename@}, |
| type @@code@{rm @@var@{filename@}@}. |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| To delete file @var{filename}, type @code{rm @var{filename}}. |
| @end quotation |
| |
| @noindent |
| (Note that @code{@@var} may appear inside @code{@@code}, |
| @code{@@samp}, @code{@@file}, etc.)@refill |
| |
| Write a metasyntactic variable all in lower case without spaces, and |
| use hyphens to make it more readable. Thus, the Texinfo source for |
| the illustration of how to begin a Texinfo manual looks like |
| this:@refill |
| |
| @example |
| @group |
| \input texinfo |
| @@@@setfilename @@var@{info-file-name@} |
| @@@@settitle @@var@{name-of-manual@} |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @example |
| @group |
| \input texinfo |
| @@setfilename @var{info-file-name} |
| @@settitle @var{name-of-manual} |
| @end group |
| @end example |
| |
| In some documentation styles, metasyntactic variables are shown with |
| angle brackets, for example:@refill |
| |
| @example |
| @dots{}, type rm <filename> |
| @end example |
| |
| @noindent |
| However, that is not the style that Texinfo uses. (You can, of |
| course, modify the sources to @TeX{} and the Info formatting commands |
| to output the @code{<@dots{}>} format if you wish.)@refill |
| |
| @node file, dfn, var, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@file}@{@var{file-name}@} |
| @findex file |
| |
| Use the @code{@@file} command to indicate text that is the name of a |
| file, buffer, or directory, or is the name of a node in Info. You can |
| also use the command for file name suffixes. Do not use @code{@@file} |
| for symbols in a programming language; use @code{@@code}. |
| |
| Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. |
| For example,@refill |
| |
| @example |
| The @@file@{.el@} files are in |
| the @@file@{/usr/local/emacs/lisp@} directory. |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| The @file{.el} files are in |
| the @file{/usr/local/emacs/lisp} directory. |
| @end quotation |
| |
| @node dfn, cite, file, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@dfn}@{@var{term}@} |
| @findex dfn |
| |
| Use the @code{@@dfn} command to identify the introductory or defining |
| use of a technical term. Use the command only in passages whose |
| purpose is to introduce a term which will be used again or which the |
| reader ought to know. Mere passing mention of a term for the first |
| time does not deserve @code{@@dfn}. The command generates italics in |
| the printed manual, and double quotation marks in the Info file. For |
| example:@refill |
| |
| @example |
| Getting rid of a file is called @@dfn@{deleting@} it. |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| Getting rid of a file is called @dfn{deleting} it. |
| @end quotation |
| |
| As a general rule, a sentence containing the defining occurrence of a |
| term should be a definition of the term. The sentence does not need |
| to say explicitly that it is a definition, but it should contain the |
| information of a definition---it should make the meaning clear. |
| |
| @node cite, url, dfn, Indicating |
| @comment node-name, next, previous, up |
| @subsection @code{@@cite}@{@var{reference}@} |
| @findex cite |
| |
| Use the @code{@@cite} command for the name of a book that lacks a |
| companion Info file. The command produces italics in the printed |
| manual, and quotation marks in the Info file.@refill |
| |
| (If a book is written in Texinfo, it is better to use a cross reference |
| command since a reader can easily follow such a reference in Info. |
| @xref{xref, , @code{@@xref}}.)@refill |
| |
| @ignore |
| @c node ctrl, , cite, Indicating |
| @comment node-name, next, previous, up |
| @c subsection @code{@@ctrl}@{@var{ctrl-char}@} |
| @findex ctrl |
| |
| The @code{@@ctrl} command is seldom used. It describes an @sc{ascii} |
| control character by inserting the actual character into the Info |
| file. |
| |
| Usually, in Texinfo, you talk what you type as keyboard entry by |
| describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for |
| @kbd{C-a}. Use @code{@@kbd} in this way when talking about a control |
| character that is typed on the keyboard by the user. When talking |
| about a control character appearing in a file or a string, do not use |
| @code{@@kbd} since the control character is not typed. Also, do not |
| use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, |
| to make it easier for a reader to understand.@refill |
| |
| @code{@@ctrl} is an idea from the beginnings of Texinfo which may not |
| really fit in to the scheme of things. But there may be times when |
| you want to use the command. The pattern is |
| @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character |
| whose control-equivalent is wanted. For example, to specify |
| @samp{control-f}, you would enter@refill |
| |
| @example |
| @@ctrl@{f@} |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| @ctrl{f} |
| @end quotation |
| |
| In the Info file, this generates the specified control character, output |
| literally into the file. This is done so a user can copy the specified |
| control character (along with whatever else he or she wants) into another |
| Emacs buffer and use it. Since the `control-h',`control-i', and |
| `control-j' characters are formatting characters, they should not be |
| indicated with @code{@@ctrl}.@refill |
| |
| In a printed manual, @code{@@ctrl} generates text to describe or |
| identify that control character: an uparrow followed by the character |
| @var{ch}.@refill |
| @end ignore |
| |
| @node url, email, cite, Indicating |
| @subsection @code{@@url}@{@var{uniform-resource-locator}@} |
| @findex url |
| |
| Use the @code{@@url} command to indicate a uniform resource locator on |
| the World Wide Web. For example: |
| |
| @c Two lines because one is too long for smallbook format. |
| @example |
| The official GNU ftp site is |
| @@url@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@}. |
| @end example |
| |
| In Info and @TeX{}, this acts like @code{@@samp}. When |
| Texinfo is converted to HTML, this produces a link you can follow. |
| |
| @node email, , url, Indicating |
| @subsection @code{@@email}@{@var{email-address}@} |
| @findex email |
| |
| Use the @code{@@email} command to indicate an electronic mail address. |
| For example: |
| |
| @example |
| Send bug reports to @email{bug-texinfo@@prep.ai.mit.edu}. |
| @end example |
| |
| In Info and @TeX{}, this acts like @code{@@samp}. When we have support |
| for conversion of Texinfo to HTML, this will produce a link you can |
| follow to bring up a mail composition window initialized with |
| @var{email-address}. |
| |
| @node Emphasis, , Indicating, Marking Text |
| @comment node-name, next, previous, up |
| @section Emphasizing Text |
| @cindex Emphasizing text |
| |
| Usually, Texinfo changes the font to mark words in the text according to |
| what category the words belong to; an example is the @code{@@code} command. |
| Most often, this is the best way to mark words. |
| However, sometimes you will want to emphasize text without indicating a |
| category. Texinfo has two commands to do this. Also, Texinfo has |
| several commands that specify the font in which @TeX{} will typeset |
| text. These commands have no affect on Info and only one of them, |
| the @code{@@r} command, has any regular use.@refill |
| |
| @menu |
| * emph & strong:: How to emphasize text in Texinfo. |
| * Smallcaps:: How to use the small caps font. |
| * Fonts:: Various font commands for printed output. |
| * Customized Highlighting:: How to define highlighting commands. |
| @end menu |
| |
| @node emph & strong, Smallcaps, Emphasis, Emphasis |
| @comment node-name, next, previous, up |
| @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} |
| @cindex Emphasizing text, font for |
| @findex emph |
| @findex strong |
| |
| The @code{@@emph} and @code{@@strong} commands are for emphasis; |
| @code{@@strong} is stronger. In printed output, @code{@@emph} |
| produces @emph{italics} and @code{@@strong} produces |
| @strong{bold}.@refill |
| |
| @need 800 |
| For example, |
| |
| @example |
| @group |
| @@quotation |
| @@strong@{Caution:@} @@code@{rm * .[^.]*@} removes @@emph@{all@} |
| files in the directory. |
| @@end quotation |
| @end group |
| @end example |
| |
| @iftex |
| @noindent |
| produces the following in printed output: |
| |
| @quotation |
| @strong{Caution}: @code{rm * .[^.]*} removes @emph{all} |
| files in the directory. |
| @end quotation |
| |
| @noindent |
| and the following in Info: |
| @end iftex |
| @ifinfo |
| @noindent |
| produces: |
| @end ifinfo |
| |
| @example |
| *Caution*: `rm * .[^.]*' removes *all* |
| files in the directory. |
| @end example |
| |
| The @code{@@strong} command is seldom used except to mark what is, in |
| effect, a typographical element, such as the word `Caution' in the |
| preceding example. |
| |
| In the Info file, both @code{@@emph} and @code{@@strong} put asterisks |
| around the text.@refill |
| |
| @quotation |
| @strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the |
| word @samp{Note}; Info will mistake the combination for a cross |
| reference. Use a phrase such as @strong{Please note} or |
| @strong{Caution} instead.@refill |
| @end quotation |
| |
| @node Smallcaps, Fonts, emph & strong, Emphasis |
| @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font |
| @cindex Small caps font |
| @findex sc @r{(small caps font)} |
| |
| @iftex |
| Use the @samp{@@sc} command to set text in the printed output in @sc{a |
| small caps font} and set text in the Info file in upper case letters.@refill |
| @end iftex |
| @ifinfo |
| Use the @samp{@@sc} command to set text in the printed output in a |
| small caps font and set text in the Info file in upper case letters.@refill |
| @end ifinfo |
| |
| Write the text between braces in lower case, like this:@refill |
| |
| @example |
| The @@sc@{acm@} and @@sc@{ieee@} are technical societies. |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @display |
| The @sc{acm} and @sc{ieee} are technical societies. |
| @end display |
| |
| @TeX{} typesets the small caps font in a manner that prevents the |
| letters from `jumping out at you on the page'. This makes small caps |
| text easier to read than text in all upper case. The Info formatting |
| commands set all small caps text in upper case.@refill |
| |
| @ifinfo |
| If the text between the braces of an @code{@@sc} command is upper case, |
| @TeX{} typesets in full-size capitals. Use full-size capitals |
| sparingly.@refill |
| @end ifinfo |
| @iftex |
| If the text between the braces of an @code{@@sc} command is upper case, |
| @TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals |
| sparingly.@refill |
| @end iftex |
| |
| You may also use the small caps font for a jargon word such as |
| @sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill |
| |
| There are subtleties to using the small caps font with a jargon word |
| such as @sc{cdr}, a word used in Lisp programming. In this case, you |
| should use the small caps font when the word refers to the second and |
| subsequent elements of a list (the @sc{cdr} of the list), but you |
| should use @samp{@@code} when the word refers to the Lisp function of |
| the same spelling.@refill |
| |
| @node Fonts, Customized Highlighting, Smallcaps, Emphasis |
| @comment node-name, next, previous, up |
| @subsection Fonts for Printing, Not Info |
| @cindex Fonts for printing, not for Info |
| @findex i @r{(italic font)} |
| @findex b @r{(bold font)} |
| @findex t @r{(typewriter font)} |
| @findex r @r{(Roman font)} |
| |
| Texinfo provides four font commands that specify font changes in the |
| printed manual but have no effect in the Info file. @code{@@i} |
| requests @i{italic} font (in some versions of @TeX{}, a slanted font |
| is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the |
| @t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a |
| @r{roman} font, which is the usual font in which text is printed. All |
| four commands apply to an argument that follows, surrounded by |
| braces.@refill |
| |
| Only the @code{@@r} command has much use: in example programs, you |
| can use the @code{@@r} command to convert code comments from the |
| fixed-width font to a roman font. This looks better in printed |
| output.@refill |
| |
| @need 700 |
| For example, |
| |
| @example |
| @group |
| @@lisp |
| (+ 2 2) ; @@r@{Add two plus two.@} |
| @@end lisp |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @lisp |
| (+ 2 2) ; @r{Add two plus two.} |
| @end lisp |
| |
| If possible, you should avoid using the other three font commands. If |
| you need to use one, it probably indicates a gap in the Texinfo |
| language.@refill |
| |
| @node Customized Highlighting, , Fonts, Emphasis |
| @comment node-name, next, previous, up |
| @subsection Customized Highlighting |
| @cindex Highlighting, customized |
| @cindex Customized highlighting |
| |
| @c I think this whole section is obsolete with the advent of macros |
| @c --karl, 15sep96. |
| You can use regular @TeX{} commands inside of @code{@@iftex} @dots{} |
| @code{@@end iftex} to create your own customized highlighting commands |
| for Texinfo. The easiest way to do this is to equate your customized |
| commands with pre-existing commands, such as those for italics. Such |
| new commands work only with @TeX{}.@refill |
| |
| @findex definfoenclose |
| @cindex Enclosure command for Info |
| You can use the @code{@@definfoenclose} command inside of |
| @code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info |
| with the same names as new commands for @TeX{}. |
| @code{@@definfoenclose} creates new commands for Info that mark text by |
| enclosing it in strings that precede and follow the text. |
| @footnote{Currently, @code{@@definfoenclose} works only with |
| @code{texinfo-format-buffer} and @code{texinfo-format-region}, not with |
| @code{makeinfo}.}@refill |
| |
| Here is how to create a new @@-command called @code{@@phoo} that causes |
| @TeX{} to typeset its argument in italics and causes Info to display the |
| argument between @samp{//} and @samp{\\}.@refill |
| |
| @need 1300 |
| For @TeX{}, write the following to equate the @code{@@phoo} command with |
| the existing @code{@@i} italics command:@refill |
| |
| @example |
| @group |
| @@iftex |
| @@global@@let@@phoo=@@i |
| @@end iftex |
| @end group |
| @end example |
| |
| @noindent |
| This defines @code{@@phoo} as a command that causes @TeX{} to typeset |
| the argument to @code{@@phoo} in italics. @code{@@global@@let} tells |
| @TeX{} to equate the next argument with the argument that follows the |
| equals sign. |
| |
| @need 1300 |
| For Info, write the following to tell the Info formatters to enclose the |
| argument between @samp{//} and @samp{\\}: |
| |
| @example |
| @group |
| @@ifinfo |
| @@definfoenclose phoo, //, \\ |
| @@end ifinfo |
| @end group |
| @end example |
| |
| @noindent |
| Write the @code{@@definfoenclose} command on a line and follow it with |
| three arguments separated by commas (commas are used as separators in an |
| @code{@@node} line in the same way).@refill |
| |
| @itemize @bullet |
| @item |
| The first argument to @code{@@definfoenclose} is the @@-command name |
| @strong{without} the @samp{@@}; |
| |
| @item |
| the second argument is the Info start delimiter string; and, |
| |
| @item |
| the third argument is the Info end delimiter string. |
| @end itemize |
| |
| @noindent |
| The latter two arguments enclose the highlighted text in the Info file. |
| A delimiter string may contain spaces. Neither the start nor end |
| delimiter is required. However, if you do not provide a start |
| delimiter, you must follow the command name with two commas in a row; |
| otherwise, the Info formatting commands will misinterpret the end |
| delimiter string as a start delimiter string.@refill |
| |
| After you have defined @code{@@phoo} both for @TeX{} and for Info, you |
| can then write @code{@@phoo@{bar@}} to see @samp{//bar\\} |
| in Info and see |
| @ifinfo |
| @samp{bar} in italics in printed output. |
| @end ifinfo |
| @iftex |
| @i{bar} in italics in printed output. |
| @end iftex |
| |
| Note that each definition applies to its own formatter: one for @TeX{}, |
| the other for Info. |
| |
| @need 1200 |
| Here is another example: |
| |
| @example |
| @group |
| @@ifinfo |
| @@definfoenclose headword, , : |
| @@end ifinfo |
| @@iftex |
| @@global@@let@@headword=@@b |
| @@end iftex |
| @end group |
| @end example |
| |
| @noindent |
| This defines @code{@@headword} as an Info formatting command that |
| inserts nothing before and a colon after the argument and as a @TeX{} |
| formatting command to typeset its argument in bold. |
| |
| @node Quotations and Examples, Lists and Tables, Marking Text, Top |
| @comment node-name, next, previous, up |
| @chapter Quotations and Examples |
| |
| Quotations and examples are blocks of text consisting of one or more |
| whole paragraphs that are set off from the bulk of the text and |
| treated differently. They are usually indented.@refill |
| |
| In Texinfo, you always begin a quotation or example by writing an |
| @@-command at the beginning of a line by itself, and end it by writing |
| an @code{@@end} command that is also at the beginning of a line by |
| itself. For instance, you begin an example by writing @code{@@example} |
| by itself at the beginning of a line and end the example by writing |
| @code{@@end example} on a line by itself, at the beginning of that |
| line.@refill |
| @findex end |
| |
| @menu |
| * Block Enclosing Commands:: Use different constructs for |
| different purposes. |
| * quotation:: How to write a quotation. |
| * example:: How to write an example in a fixed-width font. |
| * noindent:: How to prevent paragraph indentation. |
| * Lisp Example:: How to illustrate Lisp code. |
| * smallexample & smalllisp:: Forms for the @code{@@smallbook} option. |
| * display:: How to write an example in the current font. |
| * format:: How to write an example that does not narrow |
| the margins. |
| * exdent:: How to undo the indentation of a line. |
| * flushleft & flushright:: How to push text flushleft or flushright. |
| * cartouche:: How to draw cartouches around examples. |
| @end menu |
| |
| @node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples |
| @section The Block Enclosing Commands |
| |
| Here are commands for quotations and examples:@refill |
| |
| @table @code |
| @item @@quotation |
| Indicate text that is quoted. The text is filled, indented, and |
| printed in a roman font by default.@refill |
| |
| @item @@example |
| Illustrate code, commands, and the like. The text is printed |
| in a fixed-width font, and indented but not filled.@refill |
| |
| @item @@lisp |
| Illustrate Lisp code. The text is printed in a fixed-width font, |
| and indented but not filled.@refill |
| |
| @item @@smallexample |
| Illustrate code, commands, and the like. Similar to |
| @code{@@example}, except that in @TeX{} this command typesets text in |
| a smaller font for the smaller @code{@@smallbook} format than for the |
| 8.5 by 11 inch format.@refill |
| |
| @item @@smalllisp |
| Illustrate Lisp code. Similar to @code{@@lisp}, except that |
| in @TeX{} this command typesets text in a smaller font for the smaller |
| @code{@@smallbook} format than for the 8.5 by 11 inch format.@refill |
| |
| @item @@display |
| Display illustrative text. The text is indented but not filled, and |
| no font is specified (so, by default, the font is roman).@refill |
| |
| @item @@format |
| Print illustrative text. The text is not indented and not filled |
| and no font is specified (so, by default, the font is roman).@refill |
| @end table |
| |
| The @code{@@exdent} command is used within the above constructs to |
| undo the indentation of a line. |
| |
| The @code{@@flushleft} and @code{@@flushright} commands are used to line |
| up the left or right margins of unfilled text.@refill |
| |
| The @code{@@noindent} command may be used after one of the above |
| constructs to prevent the following text from being indented as a new |
| paragraph.@refill |
| |
| You can use the @code{@@cartouche} command within one of the above |
| constructs to highlight the example or quotation by drawing a box with |
| rounded corners around it. (The @code{@@cartouche} command affects |
| only the printed manual; it has no effect in the Info file; see |
| @ref{cartouche, , Drawing Cartouches Around Examples}.)@refill |
| |
| @node quotation, example, Block Enclosing Commands, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@quotation} |
| @cindex Quotations |
| @findex quotation |
| |
| The text of a quotation is |
| processed normally except that:@refill |
| |
| @itemize @bullet |
| @item |
| the margins are closer to the center of the page, so the whole of the |
| quotation is indented;@refill |
| |
| @item |
| the first lines of paragraphs are indented no more than other |
| lines;@refill |
| |
| @item |
| in the printed output, interparagraph spacing is reduced.@refill |
| @end itemize |
| |
| @quotation |
| This is an example of text written between an @code{@@quotation} |
| command and an @code{@@end quotation} command. An @code{@@quotation} |
| command is most often used to indicate text that is excerpted from |
| another (real or hypothetical) printed work.@refill |
| @end quotation |
| |
| Write an @code{@@quotation} command as text on a line by itself. This |
| line will disappear from the output. Mark the end of the quotation |
| with a line beginning with and containing only @code{@@end quotation}. |
| The @code{@@end quotation} line will likewise disappear from the |
| output. Thus, the following,@refill |
| |
| @example |
| @@quotation |
| This is |
| a foo. |
| @@end quotation |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| This is a foo. |
| @end quotation |
| |
| @node example, noindent, quotation, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@example} |
| @cindex Examples, formatting them |
| @cindex Formatting examples |
| @findex example |
| |
| The @code{@@example} command is used to indicate an example that is |
| not part of the running text, such as computer input or output.@refill |
| |
| @example |
| @group |
| This is an example of text written between an |
| @code{@@example} command |
| and an @code{@@end example} command. |
| The text is indented but not filled. |
| @end group |
| |
| @group |
| In the printed manual, the text is typeset in a |
| fixed-width font, and extra spaces and blank lines are |
| significant. In the Info file, an analogous result is |
| obtained by indenting each line with five spaces. |
| @end group |
| @end example |
| |
| Write an @code{@@example} command at the beginning of a line by itself. |
| This line will disappear from the output. Mark the end of the example |
| with an @code{@@end example} command, also written at the beginning of a |
| line by itself. The @code{@@end example} will disappear from the |
| output.@refill |
| |
| @need 700 |
| For example, |
| |
| @example |
| @@example |
| mv foo bar |
| @@end example |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| mv foo bar |
| @end example |
| |
| Since the lines containing @code{@@example} and @code{@@end example} |
| will disappear, you should put a blank line before the |
| @code{@@example} and another blank line after the @code{@@end |
| example}. (Remember that blank lines between the beginning |
| @code{@@example} and the ending @code{@@end example} will appear in |
| the output.)@refill |
| |
| @quotation |
| @strong{Caution:} Do not use tabs in the lines of an example (or anywhere |
| else in Texinfo, for that matter)! @TeX{} treats tabs as single |
| spaces, and that is not what they look like. This is a problem with |
| @TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to |
| convert tabs in a region to multiple spaces.)@refill |
| @end quotation |
| |
| Examples are often, logically speaking, ``in the middle'' of a |
| paragraph, and the text continues after an example should not be |
| indented. The @code{@@noindent} command prevents a piece of text from |
| being indented as if it were a new paragraph. |
| @ifinfo |
| (@xref{noindent}.) |
| @end ifinfo |
| |
| (The @code{@@code} command is used for examples of code that are |
| embedded within sentences, not set off from preceding and following |
| text. @xref{code, , @code{@@code}}.) |
| |
| @node noindent, Lisp Example, example, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@noindent} |
| @findex noindent |
| |
| An example or other inclusion can break a paragraph into segments. |
| Ordinarily, the formatters indent text that follows an example as a new |
| paragraph. However, you can prevent this by writing @code{@@noindent} |
| at the beginning of a line by itself preceding the continuation |
| text.@refill |
| |
| @need 1500 |
| For example: |
| |
| @example |
| @group |
| @@example |
| This is an example |
| @@end example |
| |
| @@noindent |
| This line is not indented. As you can see, the |
| beginning of the line is fully flush left with the line |
| that follows after it. (This whole example is between |
| @@code@{@@@@display@} and @@code@{@@@@end display@}.) |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @display |
| @example |
| This is an example |
| @end example |
| @tex |
| % Remove extra vskip; this is a kludge to counter the effect of display |
| \vskip-3.5\baselineskip |
| @end tex |
| |
| @noindent |
| This line is not indented. As you can see, the |
| beginning of the line is fully flush left with the line |
| that follows after it. (This whole example is between |
| @code{@@display} and @code{@@end display}.) |
| @end display |
| |
| To adjust the number of blank lines properly in the Info file output, |
| remember that the line containing @code{@@noindent} does not generate a |
| blank line, and neither does the @code{@@end example} line.@refill |
| |
| In the Texinfo source file for this manual, each line that says |
| `produces' is preceded by a line containing @code{@@noindent}.@refill |
| |
| Do not put braces after an @code{@@noindent} command; they are not |
| necessary, since @code{@@noindent} is a command used outside of |
| paragraphs (@pxref{Command Syntax}).@refill |
| |
| @node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@lisp} |
| @cindex Lisp example |
| @findex lisp |
| |
| The @code{@@lisp} command is used for Lisp code. It is synonymous |
| with the @code{@@example} command. |
| |
| @lisp |
| This is an example of text written between an |
| @code{@@lisp} command and an @code{@@end lisp} command. |
| @end lisp |
| |
| Use @code{@@lisp} instead of @code{@@example} so as to preserve |
| information regarding the nature of the example. This is useful, for |
| example, if you write a function that evaluates only and all the Lisp |
| code in a Texinfo file. Then you can use the Texinfo file as a Lisp |
| library.@footnote{It would be straightforward to extend Texinfo to |
| work in a similar fashion for C, @sc{fortran}, or other languages.}@refill |
| |
| Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by |
| itself.@refill |
| |
| @node smallexample & smalllisp, display, Lisp Example, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@smallexample} and @code{@@smalllisp} |
| @cindex Small book example |
| @cindex Example for a small book |
| @cindex Lisp example for a small book |
| @findex smallexample |
| @findex smalllisp |
| |
| In addition to the regular @code{@@example} and @code{@@lisp} commands, |
| Texinfo has two other ``example-style'' commands. These are the |
| @code{@@smallexample} and @code{@@smalllisp} commands. Both these |
| commands are designed for use with the @code{@@smallbook} command that |
| causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format |
| rather than the regular 8.5 by 11 inch format.@refill |
| |
| In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands |
| typeset text in a smaller font for the smaller @code{@@smallbook} |
| format than for the 8.5 by 11 inch format. Consequently, many examples |
| containing long lines fit in a narrower, @code{@@smallbook} page |
| without needing to be shortened. Both commands typeset in the normal |
| font size when you format for the 8.5 by 11 inch size; indeed, |
| in this situation, the @code{@@smallexample} and @code{@@smalllisp} |
| commands are defined to be the @code{@@example} and @code{@@lisp} |
| commands.@refill |
| |
| In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are |
| equivalent to the @code{@@example} and @code{@@lisp} commands, and work |
| exactly the same.@refill |
| |
| Mark the end of @code{@@smallexample} or @code{@@smalllisp} with |
| @code{@@end smallexample} or @code{@@end smalllisp}, |
| respectively.@refill |
| |
| @iftex |
| Here is an example written in the small font used by the |
| @code{@@smallexample} and @code{@@smalllisp} commands: |
| |
| @ifclear smallbook |
| @display |
| @tex |
| % Remove extra vskip; this is a kludge to counter the effect of display |
| \vskip-3\baselineskip |
| {\ninett |
| \dots{} to make sure that you have the freedom to |
| distribute copies of free software (and charge for |
| this service if you wish), that you receive source |
| code or can get it if you want it, that you can |
| change the software or use pieces of it in new free |
| programs; and that you know you can do these things.} |
| @end tex |
| @end display |
| @end ifclear |
| @end iftex |
| @ifset smallbook |
| @iftex |
| @smallexample |
| This is an example of text written between @code{@@smallexample} and |
| @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, |
| this text appears in its normal size; but in a 7 by 9.25 inch manual, |
| this text appears in a smaller font. |
| @end smallexample |
| @end iftex |
| @end ifset |
| @ifinfo |
| @smallexample |
| This is an example of text written between @code{@@smallexample} and |
| @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, |
| this text appears in its normal size; but in a 7 by 9.25 inch manual, |
| this text appears in a smaller font. |
| @end smallexample |
| @end ifinfo |
| |
| The @code{@@smallexample} and @code{@@smalllisp} commands make it |
| easier to prepare smaller format manuals without forcing you to edit |
| examples by hand to fit them onto narrower pages.@refill |
| |
| As a general rule, a printed document looks better if you write all the |
| examples in a chapter consistently in @code{@@example} or in |
| @code{@@smallexample}. Only occasionally should you mix the two |
| formats.@refill |
| |
| @xref{smallbook, , Printing ``Small'' Books}, for more information |
| about the @code{@@smallbook} command.@refill |
| |
| @node display, format, smallexample & smalllisp, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@display} |
| @cindex Display formatting |
| @findex display |
| |
| The @code{@@display} command begins a kind of example. It is like the |
| @code{@@example} command |
| except that, in |
| a printed manual, @code{@@display} does not select the fixed-width |
| font. In fact, it does not specify the font at all, so that the text |
| appears in the same font it would have appeared in without the |
| @code{@@display} command.@refill |
| |
| @display |
| This is an example of text written between an @code{@@display} command |
| and an @code{@@end display} command. The @code{@@display} command |
| indents the text, but does not fill it. |
| @end display |
| |
| @node format, exdent, display, Quotations and Examples |
| @comment node-name, next, previous, up |
| @section @code{@@format} |
| @findex format |
| |
| The @code{@@format} command is similar to @code{@@example} except |
| that, in the printed manual, @code{@@format} does not select the |
| fixed-width font and does not narrow the margins.@refill |
| |
| @format |
| This is an example of text written between an @code{@@format} command |
| and an @code{@@end format} command. As you can see |
| from this example, |
| the @code{@@format} command does not fill the text. |
| @end format |
| |
| @node exdent, flushleft & flushright, format, Quotations and Examples |
| @section @code{@@exdent}: Undoing a Line's Indentation |
| @cindex Indentation undoing |
| @findex exdent |
| |
| The @code{@@exdent} command removes any indentation a line might have. |
| The command is written at the beginning of a line and applies only to |
| the text that follows the command that is on the same line. Do not use |
| braces around the text. In a printed manual, the text on an |
| @code{@@exdent} line is printed in the roman font.@refill |
| |
| @code{@@exdent} is usually used within examples. Thus,@refill |
| |
| @example |
| @group |
| @@example |
| This line follows an @@@@example command. |
| @@exdent This line is exdented. |
| This line follows the exdented line. |
| The @@@@end example comes on the next line. |
| @@end group |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| This line follows an @@example command. |
| @exdent This line is exdented. |
| This line follows the exdented line. |
| The @@end example comes on the next line. |
| @end group |
| @end example |
| |
| In practice, the @code{@@exdent} command is rarely used. |
| Usually, you un-indent text by ending the example and |
| returning the page to its normal width.@refill |
| |
| @node flushleft & flushright, cartouche, exdent, Quotations and Examples |
| @section @code{@@flushleft} and @code{@@flushright} |
| @findex flushleft |
| @findex flushright |
| |
| The @code{@@flushleft} and @code{@@flushright} commands line up the |
| ends of lines on the left and right margins of a page, |
| but do not fill the text. The commands are written on lines of their |
| own, without braces. The @code{@@flushleft} and @code{@@flushright} |
| commands are ended by @code{@@end flushleft} and @code{@@end |
| flushright} commands on lines of their own.@refill |
| |
| @need 1500 |
| For example, |
| |
| @example |
| @group |
| @@flushleft |
| This text is |
| written flushleft. |
| @@end flushleft |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| @flushleft |
| This text is |
| written flushleft. |
| @end flushleft |
| @end quotation |
| |
| |
| Flushright produces the type of indentation often used in the return |
| address of letters.@refill |
| |
| @need 1500 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| @@flushright |
| Here is an example of text written |
| flushright. The @@code@{@@flushright@} command |
| right justifies every line but leaves the |
| left end ragged. |
| @@end flushright |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @flushright |
| Here is an example of text written |
| flushright. The @code{@@flushright} command |
| right justifies every line but leaves the |
| left end ragged. |
| @end flushright |
| |
| @node cartouche, , flushleft & flushright, Quotations and Examples |
| @section Drawing Cartouches Around Examples |
| @findex cartouche |
| @cindex Box with rounded corners |
| |
| In a printed manual, the @code{@@cartouche} command draws a box with |
| rounded corners around its contents. You can use this command to |
| further highlight an example or quotation. For instance, you could |
| write a manual in which one type of example is surrounded by a cartouche |
| for emphasis.@refill |
| |
| The @code{@@cartouche} command affects only the printed manual; it has |
| no effect in the Info file.@refill |
| |
| @need 1500 |
| For example, |
| |
| @example |
| @group |
| @@example |
| @@cartouche |
| % pwd |
| /usr/local/lib/emacs/info |
| @@end cartouche |
| @@end example |
| @end group |
| @end example |
| |
| @noindent |
| surrounds the two-line example with a box with rounded corners, in the |
| printed manual. |
| |
| @iftex |
| In a printed manual, the example looks like this:@refill |
| |
| @example |
| @group |
| @cartouche |
| % pwd |
| /usr/local/lib/emacs/info |
| @end cartouche |
| @end group |
| @end example |
| @end iftex |
| |
| @node Lists and Tables, Indices, Quotations and Examples, Top |
| @comment node-name, next, previous, up |
| @chapter Making Lists and Tables |
| @cindex Making lists and tables |
| @cindex Lists and tables, making them |
| @cindex Tables and lists, making them |
| |
| Texinfo has several ways of making lists and two-column tables. Lists can |
| be bulleted or numbered, while two-column tables can highlight the items in |
| the first column.@refill |
| |
| @menu |
| * Introducing Lists:: Texinfo formats lists for you. |
| * itemize:: How to construct a simple list. |
| * enumerate:: How to construct a numbered list. |
| * Two-column Tables:: How to construct a two-column table. |
| * Multi-column Tables:: How to construct generalized tables. |
| @end menu |
| |
| @ifinfo |
| @node Introducing Lists, itemize, Lists and Tables, Lists and Tables |
| @heading Introducing Lists |
| @end ifinfo |
| |
| Texinfo automatically indents the text in lists or tables, and numbers |
| an enumerated list. This last feature is useful if you modify the |
| list, since you do not need to renumber it yourself.@refill |
| |
| Numbered lists and tables begin with the appropriate @@-command at the |
| beginning of a line, and end with the corresponding @code{@@end} |
| command on a line by itself. The table and itemized-list commands |
| also require that you write formatting information on the same line as |
| the beginning @@-command.@refill |
| |
| Begin an enumerated list, for example, with an @code{@@enumerate} |
| command and end the list with an @code{@@end enumerate} command. |
| Begin an itemized list with an @code{@@itemize} command, followed on |
| the same line by a formatting command such as @code{@@bullet}, and end |
| the list with an @code{@@end itemize} command.@refill |
| @findex end |
| |
| Precede each element of a list with an @code{@@item} or @code{@@itemx} |
| command.@refill |
| |
| @sp 1 |
| @noindent |
| Here is an itemized list of the different kinds of table and lists:@refill |
| |
| @itemize @bullet |
| @item |
| Itemized lists with and without bullets. |
| |
| @item |
| Enumerated lists, using numbers or letters. |
| |
| @item |
| Two-column tables with highlighting. |
| @end itemize |
| |
| @sp 1 |
| @noindent |
| Here is an enumerated list with the same items:@refill |
| |
| @enumerate |
| @item |
| Itemized lists with and without bullets. |
| |
| @item |
| Enumerated lists, using numbers or letters. |
| |
| @item |
| Two-column tables with highlighting. |
| @end enumerate |
| |
| @sp 1 |
| @noindent |
| And here is a two-column table with the same items and their |
| @w{@@-commands}:@refill |
| |
| @table @code |
| @item @@itemize |
| Itemized lists with and without bullets. |
| |
| @item @@enumerate |
| Enumerated lists, using numbers or letters. |
| |
| @item @@table |
| @itemx @@ftable |
| @itemx @@vtable |
| Two-column tables with indexing. |
| @end table |
| |
| @node itemize, enumerate, Introducing Lists, Lists and Tables |
| @comment node-name, next, previous, up |
| @section Making an Itemized List |
| @cindex Itemization |
| @findex itemize |
| |
| The @code{@@itemize} command produces sequences of indented |
| paragraphs, with a bullet or other mark inside the left margin |
| at the beginning of each paragraph for which such a mark is desired.@refill |
| |
| Begin an itemized list by writing @code{@@itemize} at the beginning of |
| a line. Follow the command, on the same line, with a character or a |
| Texinfo command that generates a mark. Usually, you will write |
| @code{@@bullet} after @code{@@itemize}, but you can use |
| @code{@@minus}, or any character or any special symbol that results in |
| a single character in the Info file. (When you write @code{@@bullet} |
| or @code{@@minus} after an @code{@@itemize} command, you may omit the |
| @samp{@{@}}.)@refill |
| |
| Write the text of the indented paragraphs themselves after the |
| @code{@@itemize}, up to another line that says @code{@@end |
| itemize}.@refill |
| |
| Before each paragraph for which a mark in the margin is desired, write |
| a line that says just @code{@@item}. Do not write any other text on this |
| line.@refill |
| @findex item |
| |
| Usually, you should put a blank line before an @code{@@item}. This |
| puts a blank line in the Info file. (@TeX{} inserts the proper |
| interline whitespace in either case.) Except when the entries are |
| very brief, these blank lines make the list look better.@refill |
| |
| Here is an example of the use of @code{@@itemize}, followed by the |
| output it produces. Note that @code{@@bullet} produces an @samp{*} in |
| Info and a round dot in @TeX{}.@refill |
| |
| @example |
| @group |
| @@itemize @@bullet |
| @@item |
| Some text for foo. |
| |
| @@item |
| Some text |
| for bar. |
| @@end itemize |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @quotation |
| @itemize @bullet |
| @item |
| Some text for foo. |
| |
| @item |
| Some text |
| for bar. |
| @end itemize |
| @end quotation |
| |
| Itemized lists may be embedded within other itemized lists. Here is a |
| list marked with dashes embedded in a list marked with bullets:@refill |
| |
| @example |
| @group |
| @@itemize @@bullet |
| @@item |
| First item. |
| |
| @@itemize @@minus |
| @@item |
| Inner item. |
| |
| @@item |
| Second inner item. |
| @@end itemize |
| |
| @@item |
| Second outer item. |
| @@end itemize |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @quotation |
| @itemize @bullet |
| @item |
| First item. |
| |
| @itemize @minus |
| @item |
| Inner item. |
| |
| @item |
| Second inner item. |
| @end itemize |
| |
| @item |
| Second outer item. |
| @end itemize |
| @end quotation |
| |
| @node enumerate, Two-column Tables, itemize, Lists and Tables |
| @comment node-name, next, previous, up |
| @section Making a Numbered or Lettered List |
| @cindex Enumeration |
| @findex enumerate |
| |
| @code{@@enumerate} is like @code{@@itemize} except that the marks in |
| the left margin contain successive integers or letters. |
| (@xref{itemize, , @code{@@itemize}}.)@refill |
| |
| Write the @code{@@enumerate} command at the beginning of a line. |
| The command does not require an argument, but accepts either a number or |
| a letter as an option. |
| Without an argument, @code{@@enumerate} starts the list |
| with the number 1. With a numeric argument, such as 3, |
| the command starts the list with that number. |
| With an upper or lower case letter, such as @kbd{a} or @kbd{A}, |
| the command starts the list with that letter.@refill |
| |
| Write the text of the enumerated list in the same way you write an |
| itemized list: put @code{@@item} on a line of its own before the start of |
| each paragraph that you want enumerated. Do not write any other text on |
| the line beginning with @code{@@item}.@refill |
| |
| You should put a blank line between entries in the list. |
| This generally makes it easier to read the Info file.@refill |
| |
| @need 1500 |
| Here is an example of @code{@@enumerate} without an argument:@refill |
| |
| @example |
| @group |
| @@enumerate |
| @@item |
| Underlying causes. |
| |
| @@item |
| Proximate causes. |
| @@end enumerate |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @enumerate |
| @item |
| Underlying causes. |
| |
| @item |
| Proximate causes. |
| @end enumerate |
| @sp 1 |
| Here is an example with an argument of @kbd{3}:@refill |
| @sp 1 |
| @example |
| @group |
| @@enumerate 3 |
| @@item |
| Predisposing causes. |
| |
| @@item |
| Precipitating causes. |
| |
| @@item |
| Perpetuating causes. |
| @@end enumerate |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @enumerate 3 |
| @item |
| Predisposing causes. |
| |
| @item |
| Precipitating causes. |
| |
| @item |
| Perpetuating causes. |
| @end enumerate |
| @sp 1 |
| Here is a brief summary of the alternatives. The summary is constructed |
| using @code{@@enumerate} with an argument of @kbd{a}.@refill |
| @sp 1 |
| @enumerate a |
| @item |
| @code{@@enumerate} |
| |
| Without an argument, produce a numbered list, starting with the number |
| 1.@refill |
| |
| @item |
| @code{@@enumerate @var{positive-integer}} |
| |
| With a (positive) numeric argument, start a numbered list with that |
| number. You can use this to continue a list that you interrupted with |
| other text.@refill |
| |
| @item |
| @code{@@enumerate @var{upper-case-letter}} |
| |
| With an upper case letter as argument, start a list |
| in which each item is marked |
| by a letter, beginning with that upper case letter.@refill |
| |
| @item |
| @code{@@enumerate @var{lower-case-letter}} |
| |
| With a lower case letter as argument, start a list |
| in which each item is marked by |
| a letter, beginning with that lower case letter.@refill |
| @end enumerate |
| |
| You can also nest enumerated lists, as in an outline.@refill |
| |
| @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables |
| @section Making a Two-column Table |
| @cindex Tables, making two-column |
| @findex table |
| |
| @code{@@table} is similar to @code{@@itemize}, but the command allows |
| you to specify a name or heading line for each item. (@xref{itemize, |
| , @code{@@itemize}}.) The @code{@@table} command is used to produce |
| two-column tables, and is especially useful for glossaries and |
| explanatory exhibits.@refill |
| |
| @menu |
| * table:: How to construct a two-column table. |
| * ftable vtable:: How to construct a two-column table |
| with automatic indexing. |
| * itemx:: How to put more entries in the first column. |
| @end menu |
| |
| @ifinfo |
| @node table, ftable vtable, Two-column Tables, Two-column Tables |
| @subheading Using the @code{@@table} Command |
| |
| Use the @code{@@table} command to produce two-column tables.@refill |
| @end ifinfo |
| |
| Write the @code{@@table} command at the beginning of a line and follow |
| it on the same line with an argument that is a Texinfo command such as |
| @code{@@code}, @code{@@samp}, @code{@@var}, or @code{@@kbd}. |
| Although these commands are usually followed by arguments in braces, |
| in this case you use the command name without an argument because |
| @code{@@item} will supply the argument. This command will be applied |
| to the text that goes into the first column of each item and |
| determines how it will be highlighted. For example, @code{@@samp} |
| will cause the text in the first column to be highlighted with an |
| @code{@@samp} command.@refill |
| |
| You may also choose to use the @code{@@asis} command as an argument to |
| @code{@@table}. @code{@@asis} is a command that does nothing; if you use this |
| command after @code{@@table}, @TeX{} and the Info formatting commands |
| output the first column entries without added highlighting (`as |
| is').@refill |
| |
| (The @code{@@table} command may work with other commands besides those |
| listed here. However, you can only use commands |
| that normally take arguments in braces.)@refill |
| |
| Begin each table entry with an @code{@@item} command at the beginning |
| of a line. Write the first column text on the same line as the |
| @code{@@item} command. Write the second column text on the line |
| following the @code{@@item} line and on subsequent lines. (You do not |
| need to type anything for an empty second column entry.) You may |
| write as many lines of supporting text as you wish, even several |
| paragraphs. But only text on the same line as the @code{@@item} will |
| be placed in the first column.@refill |
| @findex item |
| |
| Normally, you should put a blank line before an @code{@@item} line. |
| This puts a blank like in the Info file. Except when the entries are |
| very brief, a blank line looks better.@refill |
| |
| @need 1500 |
| The following table, for example, highlights the text in the first |
| column with an @code{@@samp} command:@refill |
| |
| @example |
| @group |
| @@table @@samp |
| @@item foo |
| This is the text for |
| @@samp@{foo@}. |
| |
| @@item bar |
| Text for @@samp@{bar@}. |
| @@end table |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @table @samp |
| @item foo |
| This is the text for |
| @samp{foo}. |
| @item bar |
| Text for @samp{bar}. |
| @end table |
| |
| If you want to list two or more named items with a single block of |
| text, use the @code{@@itemx} command. (@xref{itemx, , |
| @code{@@itemx}}.)@refill |
| |
| @node ftable vtable, itemx, table, Two-column Tables |
| @comment node-name, next, previous, up |
| @subsection @code{@@ftable} and @code{@@vtable} |
| @cindex Tables with indexes |
| @cindex Indexing table entries automatically |
| @findex ftable |
| @findex vtable |
| |
| The @code{@@ftable} and @code{@@vtable} commands are the same as the |
| @code{@@table} command except that @code{@@ftable} automatically enters |
| each of the items in the first column of the table into the index of |
| functions and @code{@@vtable} automatically enters each of the items in |
| the first column of the table into the index of variables. This |
| simplifies the task of creating indices. Only the items on the same |
| line as the @code{@@item} commands are indexed, and they are indexed in |
| exactly the form that they appear on that line. @xref{Indices, , |
| Creating Indices}, for more information about indices.@refill |
| |
| Begin a two-column table using @code{@@ftable} or @code{@@vtable} by |
| writing the @@-command at the beginning of a line, followed on the same |
| line by an argument that is a Texinfo command such as @code{@@code}, |
| exactly as you would for an @code{@@table} command; and end the table |
| with an @code{@@end ftable} or @code{@@end vtable} command on a line by |
| itself. |
| |
| See the example for @code{@@table} in the previous section. |
| |
| @node itemx, , ftable vtable, Two-column Tables |
| @comment node-name, next, previous, up |
| @subsection @code{@@itemx} |
| @cindex Two named items for @code{@@table} |
| @findex itemx |
| |
| Use the @code{@@itemx} command inside a table when you have two or |
| more first column entries for the same item, each of which should |
| appear on a line of its own. Use @code{@@itemx} for all but the first |
| entry. The @code{@@itemx} command works exactly like @code{@@item} |
| except that it does not generate extra vertical space above the first |
| column text.@refill |
| |
| @need 1000 |
| For example, |
| |
| @example |
| @group |
| @@table @@code |
| @@item upcase |
| @@itemx downcase |
| These two functions accept a character or a string as |
| argument, and return the corresponding upper case (lower |
| case) character or string. |
| @@end table |
| @end group |
| @end example |
| |
| @noindent |
| This produces: |
| |
| @table @code |
| @item upcase |
| @itemx downcase |
| These two functions accept a character or a string as |
| argument, and return the corresponding upper case (lower |
| case) character or string.@refill |
| @end table |
| |
| @noindent |
| (Note also that this example illustrates multi-line supporting text in |
| a two-column table.)@refill |
| |
| |
| @node Multi-column Tables, , Two-column Tables, Lists and Tables |
| @section Multi-column Tables |
| @cindex Tables, making multi-column |
| @findex multitable |
| |
| @code{@@multitable} allows you to construct tables with any number of |
| columns, with each column having any width you like. |
| |
| You define the column widths on the @code{@@multitable} line itself, and |
| write each row of the actual table following an @code{@@item} command, |
| with columns separated by an @code{@@tab} command. Finally, @code{@@end |
| multitable} completes the table. Details in the sections below. |
| |
| @menu |
| * Multitable Column Widths:: Defining multitable column widths. |
| * Multitable Rows:: Defining multitable rows, with examples. |
| @end menu |
| |
| @node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables |
| @subsection Multitable Column Widths |
| @cindex Multitable column widths |
| @cindex Column widths, defining for multitables |
| @cindex Widths, defining multitable column |
| |
| You can define the column widths for a multitable in two ways: as |
| fractions of the line length; or with a prototype row. Mixing the two |
| methods is not supported. In either case, the widths are defined |
| entirely on the same line as the @code{@@multitable} command. |
| |
| @enumerate |
| @item |
| @findex columnfractions |
| @cindex Line length, column widths as fraction of |
| To specify column widths as fractions of the line length, write |
| @code{@@columnfractions} and the decimal numbers (presumably less than |
| 1) after the @code{@@multitable} command, as in: |
| |
| @example |
| @@multitable @@columnfractions .33 .33 .33 |
| @end example |
| |
| @noindent The fractions need not add up exactly to 1.0, as these do |
| not. This allows you to produce tables that do not need the full line |
| length. |
| |
| @item |
| @cindex Prototype row, column widths defined by |
| To specify a prototype row, write the longest entry for each column |
| enclosed in braces after the @code{@@multitable} command. For example: |
| |
| @example |
| @@multitable @{some text for column one@} @{for column two@} |
| @end example |
| |
| @noindent |
| The first column will then have the width of the typeset `some text for |
| column one', and the second column the width of `for column two'. |
| |
| The prototype entries need not appear in the table itself. |
| |
| Although we used simple text in this example, the prototype entries can |
| contain Texinfo commands; markup commands such as @code{@@code} are |
| particularly likely to be useful. |
| |
| @end enumerate |
| |
| |
| @node Multitable Rows, , Multitable Column Widths, Multi-column Tables |
| @subsection Multitable Rows |
| @cindex Multitable rows |
| @cindex Rows, of a multitable |
| |
| @findex item |
| @cindex tab |
| After the @code{@@multitable} command defining the column widths (see |
| the previous section), you begin each row in the body of a multitable |
| with @code{@@item}, and separate the column entries with @code{@@tab}. |
| Line breaks are not special within the table body, and you may break |
| input lines in your source file as necessary. |
| |
| Here is a complete example of a multi-column table (the text is from |
| the GNU Emacs manual): |
| |
| @example |
| @@multitable @@columnfractions .15 .45 .4 |
| @@item Key @@tab Command @@tab Description |
| @@item C-x 2 |
| @@tab @@code@{split-window-vertically@} |
| @@tab Split the selected window into two windows, |
| with one above the other. |
| @@item C-x 3 |
| @@tab @@code@{split-window-horizontally@} |
| @@tab Split the selected window into two windows |
| positioned side by side. |
| @@item C-Mouse-2 |
| @@tab |
| @@tab In the mode line or scroll bar of a window, |
| split that window. |
| @@end multitable |
| @end example |
| |
| @noindent produces: |
| |
| @multitable @columnfractions .15 .45 .4 |
| @item Key @tab Command @tab Description |
| @item C-x 2 |
| @tab @code{split-window-vertically} |
| @tab Split the selected window into two windows, |
| with one above the other. |
| @item C-x 3 |
| @tab @code{split-window-horizontally} |
| @tab Split the selected window into two windows |
| positioned side by side. |
| @item C-Mouse-2 |
| @tab |
| @tab In the mode line or scroll bar of a window, |
| split that window. |
| @end multitable |
| |
| |
| @node Indices, Insertions, Lists and Tables, Top |
| @comment node-name, next, previous, up |
| @chapter Creating Indices |
| @cindex Indices |
| @cindex Creating indices |
| |
| Using Texinfo, you can generate indices without having to sort and |
| collate entries manually. In an index, the entries are listed in |
| alphabetical order, together with information on how to find the |
| discussion of each entry. In a printed manual, this information |
| consists of page numbers. In an Info file, this information is a menu |
| entry leading to the first node referenced.@refill |
| |
| Texinfo provides several predefined kinds of index: an index |
| for functions, an index for variables, an index for concepts, and so |
| on. You can combine indices or use them for other than their |
| canonical purpose. If you wish, you can define your own indices.@refill |
| |
| @menu |
| * Index Entries:: Choose different words for index entries. |
| * Predefined Indices:: Use different indices for different kinds |
| of entry. |
| * Indexing Commands:: How to make an index entry. |
| * Combining Indices:: How to combine indices. |
| * New Indices:: How to define your own indices. |
| @end menu |
| |
| @node Index Entries, Predefined Indices, Indices, Indices |
| @comment node-name, next, previous, up |
| @section Making Index Entries |
| @cindex Index entries, making |
| @cindex Entries, making index |
| |
| When you are making index entries, it is good practice to think of the |
| different ways people may look for something. Different people |
| @emph{do not} think of the same words when they look something up. A |
| helpful index will have items indexed under all the different words |
| that people may use. For example, one reader may think it obvious that |
| the two-letter names for indices should be listed under ``Indices, |
| two-letter names'', since the word ``Index'' is the general concept. |
| But another reader may remember the specific concept of two-letter |
| names and search for the entry listed as ``Two letter names for |
| indices''. A good index will have both entries and will help both |
| readers.@refill |
| |
| Like typesetting, the construction of an index is a highly skilled, |
| professional art, the subtleties of which are not appreciated until you |
| need to do it yourself.@refill |
| |
| @xref{Printing Indices & Menus}, for information about printing an index |
| at the end of a book or creating an index menu in an Info file.@refill |
| |
| @node Predefined Indices, Indexing Commands, Index Entries, Indices |
| @comment node-name, next, previous, up |
| @section Predefined Indices |
| |
| Texinfo provides six predefined indices:@refill |
| |
| @itemize @bullet |
| @item |
| A @dfn{concept index} listing concepts that are discussed.@refill |
| |
| @item |
| A @dfn{function index} listing functions (such as entry points of |
| libraries).@refill |
| |
| @item |
| A @dfn{variables index} listing variables (such as global variables |
| of libraries).@refill |
| |
| @item |
| A @dfn{keystroke index} listing keyboard commands.@refill |
| |
| @item |
| A @dfn{program index} listing names of programs.@refill |
| |
| @item |
| A @dfn{data type index} listing data types (such as structures defined in |
| header files).@refill |
| @end itemize |
| |
| @noindent |
| Not every manual needs all of these, and most manuals use two or three |
| of them. This manual has two indices: a |
| concept index and an @@-command index (that is actually the function |
| index but is called a command index in the chapter heading). Two or |
| more indices can be combined into one using the @code{@@synindex} or |
| @code{@@syncodeindex} commands. @xref{Combining Indices}.@refill |
| |
| @node Indexing Commands, Combining Indices, Predefined Indices, Indices |
| @comment node-name, next, previous, up |
| @section Defining the Entries of an Index |
| @cindex Defining indexing entries |
| @cindex Index entries |
| @cindex Entries for an index |
| @cindex Specifying index entries |
| @cindex Creating index entries |
| |
| The data to make an index come from many individual indexing commands |
| scattered throughout the Texinfo source file. Each command says to add |
| one entry to a particular index; after formatting, the index will give |
| the current page number or node name as the reference.@refill |
| |
| An index entry consists of an indexing command at the beginning of a |
| line followed, on the rest of the line, by the entry.@refill |
| |
| For example, this section begins with the following five entries for |
| the concept index:@refill |
| |
| @example |
| @@cindex Defining indexing entries |
| @@cindex Index entries |
| @@cindex Entries for an index |
| @@cindex Specifying index entries |
| @@cindex Creating index entries |
| @end example |
| |
| Each predefined index has its own indexing command---@code{@@cindex} |
| for the concept index, @code{@@findex} for the function index, and so |
| on.@refill |
| |
| @cindex Writing index entries |
| @cindex Index entry writing |
| Concept index entries consist of text. The best way to write an index |
| is to choose entries that are terse yet clear. If you can do this, |
| the index often looks better if the entries are not capitalized, but |
| written just as they would appear in the middle of a sentence. |
| (Capitalize proper names and acronyms that always call for upper case |
| letters.) This is the case convention we use in most GNU manuals' |
| indices. |
| |
| If you don't see how to make an entry terse yet clear, make it longer |
| and clear---not terse and confusing. If many of the entries are several |
| words long, the index may look better if you use a different convention: |
| to capitalize the first word of each entry. But do not capitalize a |
| case-sensitive name such as a C or Lisp function name or a shell |
| command; that would be a spelling error. |
| |
| Whichever case convention you use, please use it consistently! |
| |
| @ignore |
| Concept index entries consist of English text. The usual convention |
| is to capitalize the first word of each such index entry, unless that |
| word is the name of a function, variable, or other such entity that |
| should not be capitalized. However, if your concept index entries are |
| consistently short (one or two words each) it may look better for each |
| regular entry to start with a lower case letter, aside from proper |
| names and acronyms that always call for upper case letters. Whichever |
| convention you adapt, please be consistent! |
| @end ignore |
| |
| Entries in indices other than the concept index are symbol names in |
| programming languages, or program names; these names are usually |
| case-sensitive, so use upper and lower case as required for them. |
| |
| By default, entries for a concept index are printed in a small roman |
| font and entries for the other indices are printed in a small |
| @code{@@code} font. You may change the way part of an entry is |
| printed with the usual Texinfo commands, such as @code{@@file} for |
| file names and @code{@@emph} for emphasis (@pxref{Marking |
| Text}).@refill |
| @cindex Index font types |
| |
| @cindex Predefined indexing commands |
| @cindex Indexing commands, predefined |
| The six indexing commands for predefined indices are: |
| |
| @table @code |
| @item @@cindex @var{concept} |
| @findex cindex |
| Make an entry in the concept index for @var{concept}.@refill |
| |
| @item @@findex @var{function} |
| @findex findex |
| Make an entry in the function index for @var{function}.@refill |
| |
| @item @@vindex @var{variable} |
| @findex vindex |
| Make an entry in the variable index for @var{variable}.@refill |
| |
| @item @@kindex @var{keystroke} |
| @findex kindex |
| Make an entry in the key index for @var{keystroke}.@refill |
| |
| @item @@pindex @var{program} |
| @findex pindex |
| Make an entry in the program index for @var{program}.@refill |
| |
| @item @@tindex @var{data type} |
| @findex tindex |
| Make an entry in the data type index for @var{data type}.@refill |
| @end table |
| |
| @quotation |
| @strong{Caution:} Do not use a colon in an index entry. In Info, a |
| colon separates the menu entry name from the node name. An extra |
| colon confuses Info. |
| @xref{Menu Parts, , The Parts of a Menu}, |
| for more information about the structure of a menu entry.@refill |
| @end quotation |
| |
| If you write several identical index entries in different places in a |
| Texinfo file, the index in the printed manual will list all the pages to |
| which those entries refer. However, the index in the Info file will |
| list @strong{only} the node that references the @strong{first} of those |
| index entries. Therefore, it is best to write indices in which each |
| entry refers to only one place in the Texinfo file. Fortunately, this |
| constraint is a feature rather than a loss since it means that the index |
| will be easy to use. Otherwise, you could create an index that lists |
| several pages for one entry and your reader would not know to which page |
| to turn. If you have two identical entries for one topic, change the |
| topics slightly, or qualify them to indicate the difference.@refill |
| |
| You are not actually required to use the predefined indices for their |
| canonical purposes. For example, suppose you wish to index some C |
| preprocessor macros. You could put them in the function index along |
| with actual functions, just by writing @code{@@findex} commands for |
| them; then, when you print the ``Function Index'' as an unnumbered |
| chapter, you could give it the title `Function and Macro Index' and |
| all will be consistent for the reader. Or you could put the macros in |
| with the data types by writing @code{@@tindex} commands for them, and |
| give that index a suitable title so the reader will understand. |
| (@xref{Printing Indices & Menus}.)@refill |
| |
| @node Combining Indices, New Indices, Indexing Commands, Indices |
| @comment node-name, next, previous, up |
| @section Combining Indices |
| @cindex Combining indices |
| @cindex Indices, combining them |
| |
| Sometimes you will want to combine two disparate indices such as functions |
| and concepts, perhaps because you have few enough of one of them that |
| a separate index for them would look silly.@refill |
| |
| You could put functions into the concept index by writing |
| @code{@@cindex} commands for them instead of @code{@@findex} commands, |
| and produce a consistent manual by printing the concept index with the |
| title `Function and Concept Index' and not printing the `Function |
| Index' at all; but this is not a robust procedure. It works only if |
| your document is never included as part of another |
| document that is designed to have a separate function index; if your |
| document were to be included with such a document, the functions from |
| your document and those from the other would not end up together. |
| Also, to make your function names appear in the right font in the |
| concept index, you would need to enclose every one of them between |
| the braces of @code{@@code}.@refill |
| |
| @menu |
| * syncodeindex:: How to merge two indices, using @code{@@code} |
| font for the merged-from index. |
| * synindex:: How to merge two indices, using the |
| default font of the merged-to index. |
| @end menu |
| |
| @node syncodeindex, synindex, Combining Indices, Combining Indices |
| @subsection @code{@@syncodeindex} |
| @findex syncodeindex |
| |
| When you want to combine functions and concepts into one index, you |
| should index the functions with @code{@@findex} and index the concepts |
| with @code{@@cindex}, and use the @code{@@syncodeindex} command to |
| redirect the function index entries into the concept index.@refill |
| @findex syncodeindex |
| |
| The @code{@@syncodeindex} command takes two arguments; they are the name |
| of the index to redirect, and the name of the index to redirect it to. |
| The template looks like this:@refill |
| |
| @example |
| @@syncodeindex @var{from} @var{to} |
| @end example |
| |
| @cindex Predefined names for indices |
| @cindex Two letter names for indices |
| @cindex Indices, two letter names |
| @cindex Names for indices |
| For this purpose, the indices are given two-letter names:@refill |
| |
| @table @samp |
| @item cp |
| concept index |
| @item fn |
| function index |
| @item vr |
| variable index |
| @item ky |
| key index |
| @item pg |
| program index |
| @item tp |
| data type index |
| @end table |
| |
| Write an @code{@@syncodeindex} command before or shortly after the |
| end-of-header line at the beginning of a Texinfo file. For example, |
| to merge a function index with a concept index, write the |
| following:@refill |
| |
| @example |
| @@syncodeindex fn cp |
| @end example |
| |
| @noindent |
| This will cause all entries designated for the function index to merge |
| in with the concept index instead.@refill |
| |
| To merge both a variables index and a function index into a concept |
| index, write the following:@refill |
| |
| @example |
| @group |
| @@syncodeindex vr cp |
| @@syncodeindex fn cp |
| @end group |
| @end example |
| |
| @cindex Fonts for indices |
| The @code{@@syncodeindex} command puts all the entries from the `from' |
| index (the redirected index) into the @code{@@code} font, overriding |
| whatever default font is used by the index to which the entries are |
| now directed. This way, if you direct function names from a function |
| index into a concept index, all the function names are printed in the |
| @code{@@code} font as you would expect.@refill |
| |
| @node synindex, , syncodeindex, Combining Indices |
| @subsection @code{@@synindex} |
| @findex synindex |
| |
| The @code{@@synindex} command is nearly the same as the |
| @code{@@syncodeindex} command, except that it does not put the |
| `from' index entries into the @code{@@code} font; rather it puts |
| them in the roman font. Thus, you use @code{@@synindex} when you |
| merge a concept index into a function index.@refill |
| |
| @xref{Printing Indices & Menus}, for information about printing an index |
| at the end of a book or creating an index menu in an Info file.@refill |
| |
| @node New Indices, , Combining Indices, Indices |
| @section Defining New Indices |
| @cindex Defining new indices |
| @cindex Indices, defining new |
| @cindex New index defining |
| @findex defindex |
| @findex defcodeindex |
| |
| In addition to the predefined indices, you may use the |
| @code{@@defindex} and @code{@@defcodeindex} commands to define new |
| indices. These commands create new indexing @@-commands with which |
| you mark index entries. The @code{@@defindex }command is used like |
| this:@refill |
| |
| @example |
| @@defindex @var{name} |
| @end example |
| |
| The name of an index should be a two letter word, such as @samp{au}. |
| For example:@refill |
| |
| @example |
| @@defindex au |
| @end example |
| |
| This defines a new index, called the @samp{au} index. At the same |
| time, it creates a new indexing command, @code{@@auindex}, that you |
| can use to make index entries. Use the new indexing command just as |
| you would use a predefined indexing command.@refill |
| |
| For example, here is a section heading followed by a concept index |
| entry and two @samp{au} index entries.@refill |
| |
| @example |
| @@section Cognitive Semantics |
| @@cindex kinesthetic image schemas |
| @@auindex Johnson, Mark |
| @@auindex Lakoff, George |
| @end example |
| |
| @noindent |
| (Evidently, @samp{au} serves here as an abbreviation for ``author''.) |
| Texinfo constructs the new indexing command by concatenating the name |
| of the index with @samp{index}; thus, defining an @samp{au} index |
| leads to the automatic creation of an @code{@@auindex} command.@refill |
| |
| Use the @code{@@printindex} command to print the index, as you do with |
| the predefined indices. For example:@refill |
| |
| @example |
| @group |
| @@node Author Index, Subject Index, , Top |
| @@unnumbered Author Index |
| |
| @@printindex au |
| @end group |
| @end example |
| |
| The @code{@@defcodeindex} is like the @code{@@defindex} command, except |
| that, in the printed output, it prints entries in an @code{@@code} font |
| instead of a roman font. Thus, it parallels the @code{@@findex} command |
| rather than the @code{@@cindex} command.@refill |
| |
| You should define new indices within or right after the end-of-header |
| line of a Texinfo file, before any @code{@@synindex} or |
| @code{@@syncodeindex} commands (@pxref{Header}).@refill |
| |
| @node Insertions, Glyphs, Indices, Top |
| @comment node-name, next, previous, up |
| @chapter Special Insertions |
| @cindex Inserting special characters and symbols |
| @cindex Special insertions |
| |
| Texinfo provides several commands for formatting dimensions, for |
| inserting single characters that have special meaning in Texinfo, such |
| as braces, and for inserting special graphic symbols that do not |
| correspond to characters, such as dots and bullets.@refill |
| |
| @iftex |
| These are: |
| |
| @itemize @bullet |
| @item |
| Braces, @samp{@@} and periods. |
| |
| @item |
| Format a dimension, such as @samp{12@dmn{pt}}. |
| |
| @item |
| Dots and bullets. |
| |
| @item |
| The @TeX{} logo and the copyright symbol. |
| |
| @item |
| A minus sign. |
| @end itemize |
| @end iftex |
| |
| @menu |
| * Braces Atsigns:: How to insert braces, @samp{@@}. |
| * Inserting Space:: How to insert the right amount of space |
| within a sentence. |
| * Inserting Accents:: How to insert accents and special characters. |
| * Dots Bullets:: How to insert dots and bullets. |
| * TeX and copyright:: How to insert the @TeX{} logo |
| and the copyright symbol. |
| * pounds:: How to insert the pounds currency symbol. |
| * minus:: How to insert a minus sign. |
| * math:: How to format a mathematical expression. |
| @end menu |
| |
| |
| @node Braces Atsigns, Inserting Space, Insertions, Insertions |
| @section Inserting @@ and Braces |
| @cindex Inserting @@, braces |
| @cindex Braces, inserting |
| @cindex Special characters, commands to insert |
| @cindex Commands to insert special characters |
| |
| @samp{@@} and curly braces are special characters in Texinfo. To insert |
| these characters so they appear in text, you must put an @samp{@@} in |
| front of these characters to prevent Texinfo from misinterpreting |
| them. |
| |
| Do not put braces after any of these commands; they are not |
| necessary. |
| |
| @menu |
| * Inserting An Atsign:: How to insert @samp{@@}. |
| * Inserting Braces:: How to insert @samp{@{} and @samp{@}}. |
| @end menu |
| |
| @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns |
| @subsection Inserting @samp{@@} with @@@@ |
| @findex @@ @r{(single @samp{@@})} |
| |
| @code{@@@@} stands for a single @samp{@@} in either printed or Info |
| output. |
| |
| Do not put braces after an @code{@@@@} command. |
| |
| @node Inserting Braces, , Inserting An Atsign, Braces Atsigns |
| @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} |
| @findex @{ @r{(single @samp{@{})} |
| @findex @} @r{(single @samp{@}})} |
| |
| @code{@@@{} stands for a single @samp{@{} in either printed or Info |
| output. |
| |
| @code{@@@}} stands for a single @samp{@}} in either printed or Info |
| output. |
| |
| Do not put braces after either an @code{@@@{} or an @code{@@@}} |
| command. |
| |
| |
| @node Inserting Space, Inserting Accents, Braces Atsigns, Insertions |
| @section Inserting Space |
| |
| @cindex Inserting space |
| @cindex Spacing, inserting |
| @cindex Whitespace, inserting |
| The following sections describe commands that control spacing of various |
| kinds within and after sentences. |
| |
| @menu |
| * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. |
| * Ending a Sentence:: Sometimes it does. |
| * Multiple Spaces:: Inserting multiple spaces. |
| * dmn:: How to format a dimension. |
| @end menu |
| |
| @node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space |
| @subsection Not Ending a Sentence |
| |
| @cindex Not ending a sentence |
| @cindex Sentence non-ending punctuation |
| @cindex Periods, inserting |
| Depending on whether a period or exclamation point or question mark is |
| inside or at the end of a sentence, less or more space is inserted after |
| a period in a typeset manual. Since it is not always possible for |
| Texinfo to determine when a period ends a sentence and when it is used |
| in an abbreviation, special commands are needed in some circumstances. |
| (Usually, Texinfo can guess how to handle periods, so you do not need to |
| use the special commands; you just enter a period as you would if you |
| were using a typewriter, which means you put two spaces after the |
| period, question mark, or exclamation mark that ends a sentence.) |
| |
| @findex : @r{(suppress widening)} |
| Use the @code{@@:}@: command after a period, question mark, |
| exclamation mark, or colon that should not be followed by extra space. |
| For example, use @code{@@:}@: after periods that end abbreviations |
| which are not at the ends of sentences. @code{@@:}@: has no effect on |
| the Info file output. |
| |
| @need 700 |
| For example, |
| |
| @example |
| The s.o.p.@@: has three parts @dots{} |
| The s.o.p. has three parts @dots{} |
| @end example |
| |
| @noindent |
| @ifinfo |
| produces |
| @end ifinfo |
| @iftex |
| produces the following. If you look carefully at this printed output, |
| you will see a little more whitespace after @samp{s.o.p.} in the second |
| line.@refill |
| @end iftex |
| |
| @quotation |
| The s.o.p.@: has three parts @dots{}@* |
| The s.o.p. has three parts @dots{} |
| @end quotation |
| |
| @noindent |
| @kbd{@@:} has no effect on the Info output. (@samp{s.o.p.} is an |
| abbreviation for ``Standard Operating Procedure''.) |
| |
| Do not put braces after @code{@@:}. |
| |
| |
| @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space |
| @subsection Ending a Sentence |
| |
| @cindex Ending a Sentence |
| @cindex Sentence ending punctuation |
| |
| @findex . @r{(end of sentence)} |
| @findex ! @r{(end of sentence)} |
| @findex ? @r{(end of sentence)} |
| Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an |
| exclamation point, and @code{@@?}@: instead of a question mark at the end |
| of a sentence that ends with a single capital letter. Otherwise, @TeX{} |
| will think the letter is an abbreviation and will not insert the correct |
| end-of-sentence spacing. Here is an example: |
| |
| @example |
| Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. |
| Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. |
| @end example |
| |
| @noindent |
| @ifinfo |
| produces |
| @end ifinfo |
| @iftex |
| produces the following. If you look carefully at this printed output, |
| you will see a little more whitespace after the @samp{W} in the first |
| line. |
| @end iftex |
| |
| @quotation |
| Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* |
| Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. |
| @end quotation |
| |
| In the Info file output, @code{@@.}@: is equivalent to a simple |
| @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. |
| |
| The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to |
| work well with the Emacs sentence motion commands (@pxref{Sentences,,, |
| emacs, GNU Emacs}). This made it necessary for them to be incompatible |
| with some other formatting systems that use @@-commands. |
| |
| Do not put braces after any of these commands. |
| |
| |
| @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space |
| @subsection Multiple Spaces |
| |
| @cindex Multiple spaces |
| @cindex Whitespace, inserting |
| @findex (space) |
| @findex (tab) |
| @findex (newline) |
| |
| Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, |
| and newline) into a single space. (Info output, on the other hand, |
| preserves whitespace as you type it, except for changing a newline into |
| a space; this is why it is important to put two spaces at the end of |
| sentences in Texinfo documents.) |
| |
| Occasionally, you may want to actually insert several consecutive |
| spaces, either for purposes of example (what your program does with |
| multiple spaces as input), or merely for purposes of appearance in |
| headings or lists. Texinfo supports three commands: @code{@@ }, |
| @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of which insert a single |
| space into the output. (Here, @kbd{TAB} and @kbd{NL} represent the tab |
| character and end-of-line, i.e., when @samp{@@} is the last character on |
| a line.) |
| |
| For example, |
| @example |
| Spacey@@ @@ @@ @@ |
| example. |
| @end example |
| |
| @noindent produces |
| |
| @example |
| Spacey@ @ @ @ |
| example. |
| @end example |
| |
| Other possible uses of @code{@@ } have been subsumed by @code{@@multitable} |
| (@pxref{Multi-column Tables}). |
| |
| Do not follow any of these commands with braces. |
| |
| |
| @node dmn, , Multiple Spaces, Inserting Space |
| @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension |
| @cindex Thin space between number, dimension |
| @cindex Dimension formatting |
| @cindex Format a dimension |
| @findex dmn |
| |
| At times, you may want to write @samp{12@dmn{pt}} or |
| @samp{8.5@dmn{in}} with little or no space between the number and the |
| abbreviation for the dimension. You can use the @code{@@dmn} command |
| to do this. On seeing the command, @TeX{} inserts just enough space |
| for proper typesetting; the Info formatting commands insert no space |
| at all, since the Info file does not require it.@refill |
| |
| To use the @code{@@dmn} command, write the number and then follow it |
| immediately, with no intervening space, by @code{@@dmn}, and then by |
| the dimension within braces.@refill |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| A4 paper is 8.27@@dmn@{in@} wide. |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| A4 paper is 8.27@dmn{in} wide. |
| @end quotation |
| |
| Not everyone uses this style. Instead of writing |
| @w{@samp{8.27@@dmn@{in@}}} in the Texinfo file, you may write |
| @w{@samp{8.27 in.}} or @w{@samp{8.27 inches}}. (In these cases, the |
| formatters may insert a line break between the number and the |
| dimension. Also, if you write a period after an abbreviation within a |
| sentence, you should write @samp{@@:} after the period to prevent |
| @TeX{} from inserting extra whitespace. @xref{Inserting Space}. |
| |
| |
| @node Inserting Accents, Dots Bullets, Inserting Space, Insertions |
| @section Inserting Accents |
| |
| @cindex Inserting accents |
| @cindex Accents, inserting |
| @cindex Floating accents, inserting |
| |
| Here is a table with the commands Texinfo provides for inserting |
| floating accents. The commands with non-alphabetic names do not take |
| braces around their argument (which is taken to be the next character). |
| (Exception: @code{@@,} @emph{does} take braces around its argument.) |
| This is so as to make the source as convenient to type and read as |
| possible, since accented characters are very common in some languages. |
| |
| @findex " |
| @cindex Umlaut accent |
| @findex ' |
| @cindex Acute accent |
| @findex = |
| @cindex Macron accent |
| @findex ^ |
| @cindex Circumflex accent |
| @findex ` |
| @cindex Grave accent |
| @findex ~ |
| @cindex Tilde accent |
| @findex , |
| @cindex Cedilla accent |
| @findex dotaccent |
| @cindex Dot accent |
| @findex H |
| @cindex Hungariam umlaut accent |
| @findex ringaccent |
| @cindex Ring accent |
| @findex tieaccent |
| @cindex Tie-after accent |
| @findex u |
| @cindex Breve accent |
| @findex ubaraccent |
| @cindex Underbar accent |
| @findex udotaccent |
| @cindex Underdot accent |
| @findex v |
| @cindex Check accent |
| @multitable {@@questiondown@{@}} {Output} {macron/overbar accent} |
| @item Command @tab Output @tab What |
| @item @t{@@"o} @tab @"o @tab umlaut accent |
| @item @t{@@'o} @tab @'o @tab acute accent |
| @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent |
| @item @t{@@=o} @tab @=o @tab macron/overbar accent |
| @item @t{@@^o} @tab @^o @tab circumflex accent |
| @item @t{@@`o} @tab @`o @tab grave accent |
| @item @t{@@~o} @tab @~o @tab tilde accent |
| @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent |
| @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut |
| @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent |
| @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent |
| @item @t{@@u@{o@}} @tab @u{o} @tab breve accent |
| @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent |
| @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent |
| @item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent |
| @end multitable |
| |
| This table lists the Texinfo commands for inserting other characters |
| commonly used in languages other than English. |
| |
| @findex questiondown |
| @cindex @questiondown{} |
| @findex exclamdown |
| @cindex @exclamdown{} |
| @findex aa |
| @cindex @aa{} |
| @findex AA |
| @cindex @AA{} |
| @findex ae |
| @cindex @ae{} |
| @findex AE |
| @cindex @AE{} |
| @findex dotless |
| @cindex @dotless{i} |
| @cindex @dotless{j} |
| @cindex Dotless i, j |
| @findex l |
| @cindex @l{} |
| @findex L |
| @cindex @L{} |
| @findex o |
| @cindex @o{} |
| @findex O |
| @cindex @O{} |
| @findex oe |
| @cindex @oe{} |
| @findex OE |
| @cindex @OE{} |
| @findex ss |
| @cindex @ss{} |
| @cindex Es-zet |
| @cindex Sharp S |
| @cindex German S |
| @multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S} |
| @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! |
| @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? |
| @item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle |
| @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures |
| @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i |
| @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j |
| @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l |
| @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash |
| @item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures |
| @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S |
| @end multitable |
| |
| |
| @node Dots Bullets, TeX and copyright, Inserting Accents, Insertions |
| @section Inserting Ellipsis, Dots, and Bullets |
| @cindex Dots, inserting |
| @cindex Bullets, inserting |
| @cindex Ellipsis, inserting |
| @cindex Inserting ellipsis |
| @cindex Inserting dots |
| @cindex Special typesetting commands |
| @cindex Typesetting commands for dots, etc. |
| |
| An @dfn{ellipsis} (a line of dots) is not typeset as a string of |
| periods, so a special command is used for ellipsis in Texinfo. The |
| @code{@@bullet} command is special, too. Each of these commands is |
| followed by a pair of braces, @samp{@{@}}, without any whitespace |
| between the name of the command and the braces. (You need to use braces |
| with these commands because you can use them next to other text; without |
| the braces, the formatters would be confused. @xref{Command Syntax, , |
| @@-Command Syntax}, for further information.)@refill |
| |
| @menu |
| * dots:: How to insert dots @dots{} |
| * bullet:: How to insert a bullet. |
| @end menu |
| |
| @node dots, bullet, Dots Bullets, Dots Bullets |
| @comment node-name, next, previous, up |
| @subsection @code{@@dots}@{@} |
| @findex dots |
| @cindex Inserting dots |
| @cindex Dots, inserting |
| |
| Use the @code{@@dots@{@}} command to generate an ellipsis, which is |
| three dots in a row, appropriately spaced, like this: `@dots{}'. Do |
| not simply write three periods in the input file; that would work for |
| the Info file output, but would produce the wrong amount of space |
| between the periods in the printed manual. |
| |
| Similarly, the @code{@@enddots@{@}} command generates an |
| end-of-sentence ellipsis (four dots) @enddots{} |
| |
| @iftex |
| Here is an ellipsis: @dots{} |
| Here are three periods in a row: ... |
| |
| In printed output, the three periods in a row are closer together than |
| the dots in the ellipsis. |
| @end iftex |
| |
| @node bullet, , dots, Dots Bullets |
| @comment node-name, next, previous, up |
| @subsection @code{@@bullet}@{@} |
| @findex bullet |
| |
| Use the @code{@@bullet@{@}} command to generate a large round dot, or |
| the closest possible thing to one. In Info, an asterisk is used.@refill |
| |
| Here is a bullet: @bullet{} |
| |
| When you use @code{@@bullet} in @code{@@itemize}, you do not need to |
| type the braces, because @code{@@itemize} supplies them. |
| (@xref{itemize, , @code{@@itemize}}.)@refill |
| |
| @node TeX and copyright, pounds, Dots Bullets, Insertions |
| @comment node-name, next, previous, up |
| @section Inserting @TeX{} and the Copyright Symbol |
| |
| The logo `@TeX{}' is typeset in a special fashion and it needs an |
| @@-command. The copyright symbol, `@copyright{}', is also special. |
| Each of these commands is followed by a pair of braces, @samp{@{@}}, |
| without any whitespace between the name of the command and the |
| braces.@refill |
| |
| @menu |
| * tex:: How to insert the @TeX{} logo. |
| * copyright symbol:: How to use @code{@@copyright}@{@}. |
| @end menu |
| |
| @node tex, copyright symbol, TeX and copyright, TeX and copyright |
| @comment node-name, next, previous, up |
| @subsection @code{@@TeX}@{@} |
| @findex tex (command) |
| |
| Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed |
| manual, this is a special logo that is different from three ordinary |
| letters. In Info, it just looks like @samp{TeX}. The |
| @code{@@TeX@{@}} command is unique among Texinfo commands in that the |
| @kbd{T} and the @kbd{X} are in upper case.@refill |
| |
| @node copyright symbol, , tex, TeX and copyright |
| @comment node-name, next, previous, up |
| @subsection @code{@@copyright}@{@} |
| @findex copyright |
| |
| Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In |
| a printed manual, this is a @samp{c} inside a circle, and in Info, |
| this is @samp{(C)}.@refill |
| |
| @node pounds, minus, TeX and copyright, Insertions |
| @section @code{@@pounds}@{@} |
| @findex pounds |
| |
| Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a |
| printed manual, this is the symbol for the currency pounds sterling. |
| In Info, it is a @samp{#}. Other currency symbols are unfortunately not |
| available. |
| |
| @node minus, math, pounds, Insertions |
| @section @code{@@minus}@{@}: Inserting a Minus Sign |
| @findex minus |
| |
| Use the @code{@@minus@{@}} command to generate a minus sign. In a |
| fixed-width font, this is a single hyphen, but in a proportional font, |
| the symbol is the customary length for a minus sign---a little longer |
| than a hyphen.@refill |
| |
| You can compare the two forms: |
| |
| @display |
| @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, |
| |
| `-' is a hyphen generated with the character @samp{-}. |
| @end display |
| |
| @noindent |
| In the fixed-width font used by Info, @code{@@minus@{@}} is the same |
| as a hyphen.@refill |
| |
| You should not use @code{@@minus@{@}} inside @code{@@code} or |
| @code{@@example} because the width distinction is not made in the |
| fixed-width font they use.@refill |
| |
| When you use @code{@@minus} to specify the mark beginning each entry in |
| an itemized list, you do not need to type the braces |
| (@pxref{itemize, , @code{@@itemize}}.)@refill |
| |
| @node math, , minus, Insertions |
| @comment node-name, next, previous, up |
| @section @code{@@math}: Inserting Mathematical Expressions |
| @findex math |
| @cindex Mathematical expressions |
| |
| You can write a short mathematical expression with the @code{@@math} |
| command. Write the mathematical expression between braces, like this: |
| |
| @example |
| @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} |
| @end example |
| |
| @iftex |
| @need 1000 |
| @noindent |
| This produces the following in @TeX{}: |
| |
| @display |
| @math{(a + b)(a + b) = a^2 + 2ab + b^2} |
| @end display |
| |
| @noindent |
| and the following in Info: |
| @end iftex |
| @ifinfo |
| @noindent |
| This produces the following in Info: |
| @end ifinfo |
| |
| @example |
| (a + b)(a + b) = a^2 + 2ab + b^2 |
| @end example |
| |
| The @code{@@math} command has no effect on the Info output. Currently, |
| it has limited effect on typeset output. However, this may change since |
| @TeX{} itself is designed for mathematical typesetting and does a |
| splendid job. |
| |
| Certainly, for complex mathematical expressions, you could use @TeX{} |
| directly. @xref{Using Ordinary TeX Commands, , Using Ordinary @TeX{} |
| Commands}. When you use @TeX{} directly, remember to write the |
| mathematical expression between one or two @samp{$} (dollar-signs) as |
| appropriate. |
| |
| @node Glyphs, Breaks, Insertions, Top |
| @comment node-name, next, previous, up |
| @chapter Glyphs for Examples |
| @cindex Glyphs |
| |
| In Texinfo, code is often illustrated in examples that are delimited |
| by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and |
| @code{@@end lisp}. In such examples, you can indicate the results of |
| evaluation or an expansion using @samp{@result{}} or |
| @samp{@expansion{}}. Likewise, there are commands to insert glyphs |
| to indicate |
| printed output, error messages, equivalence of expressions, and the |
| location of point.@refill |
| |
| The glyph-insertion commands do not need to be used within an example, but |
| most often they are. Every glyph-insertion command is followed by a pair of |
| left- and right-hand braces.@refill |
| |
| @menu |
| * Glyphs Summary:: |
| * result:: How to show the result of expression. |
| * expansion:: How to indicate an expansion. |
| * Print Glyph:: How to indicate printed output. |
| * Error Glyph:: How to indicate an error message. |
| * Equivalence:: How to indicate equivalence. |
| * Point Glyph:: How to indicate the location of point. |
| @end menu |
| |
| @node Glyphs Summary, result, Glyphs, Glyphs |
| @ifinfo |
| @heading Glyphs Summary |
| |
| Here are the different glyph commands:@refill |
| @end ifinfo |
| |
| @table @asis |
| @item @result{} |
| @code{@@result@{@}} points to the result of an expression.@refill |
| |
| @item @expansion{} |
| @code{@@expansion@{@}} shows the results of a macro expansion.@refill |
| |
| @item @print{} |
| @code{@@print@{@}} indicates printed output.@refill |
| |
| @item @error{} |
| @code{@@error@{@}} indicates that the following text is an error |
| message.@refill |
| |
| @item @equiv{} |
| @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill |
| |
| @item @point{} |
| @code{@@point@{@}} shows the location of point.@refill |
| @end table |
| |
| @node result, expansion, Glyphs Summary, Glyphs |
| @section @result{}: Indicating Evaluation |
| @cindex Result of an expression |
| @cindex Indicating evaluation |
| @cindex Evaluation glyph |
| @cindex Value of an expression, indicating |
| |
| Use the @code{@@result@{@}} command to indicate the result of |
| evaluating an expression.@refill |
| |
| @iftex |
| The @code{@@result@{@}} command is displayed as @samp{=>} in Info and |
| as @samp{@result{}} in the printed output. |
| @end iftex |
| @ifinfo |
| The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info |
| and as a double stemmed arrow in the printed output.@refill |
| @end ifinfo |
| |
| Thus, the following, |
| |
| @lisp |
| (cdr '(1 2 3)) |
| @result{} (2 3) |
| @end lisp |
| |
| @noindent |
| may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. |
| |
| @node expansion, Print Glyph, result, Glyphs |
| @section @expansion{}: Indicating an Expansion |
| @cindex Expansion, indicating it |
| |
| When an expression is a macro call, it expands into a new expression. |
| You can indicate the result of the expansion with the |
| @code{@@expansion@{@}} command.@refill |
| |
| @iftex |
| The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and |
| as @samp{@expansion{}} in the printed output. |
| @end iftex |
| @ifinfo |
| The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} |
| in Info and as a long arrow with a flat base in the printed output.@refill |
| @end ifinfo |
| |
| @need 700 |
| For example, the following |
| |
| @example |
| @group |
| @@lisp |
| (third '(a b c)) |
| @@expansion@{@} (car (cdr (cdr '(a b c)))) |
| @@result@{@} c |
| @@end lisp |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @lisp |
| @group |
| (third '(a b c)) |
| @expansion{} (car (cdr (cdr '(a b c)))) |
| @result{} c |
| @end group |
| @end lisp |
| |
| @noindent |
| which may be read as: |
| |
| @quotation |
| @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; |
| the result of evaluating the expression is @code{c}. |
| @end quotation |
| |
| @noindent |
| Often, as in this case, an example looks better if the |
| @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented |
| five spaces.@refill |
| |
| @node Print Glyph, Error Glyph, expansion, Glyphs |
| @section @print{}: Indicating Printed Output |
| @cindex Printed output, indicating it |
| |
| Sometimes an expression will print output during its execution. You |
| can indicate the printed output with the @code{@@print@{@}} command.@refill |
| |
| @iftex |
| The @code{@@print@{@}} command is displayed as @samp{-|} in Info and |
| as @samp{@print{}} in the printed output. |
| @end iftex |
| @ifinfo |
| The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info |
| and similarly, as a horizontal dash butting against a vertical bar, in |
| the printed output.@refill |
| @end ifinfo |
| |
| In the following example, the printed text is indicated with |
| @samp{@print{}}, and the value of the expression follows on the |
| last line.@refill |
| |
| @lisp |
| @group |
| (progn (print 'foo) (print 'bar)) |
| @print{} foo |
| @print{} bar |
| @result{} bar |
| @end group |
| @end lisp |
| |
| @noindent |
| In a Texinfo source file, this example is written as follows: |
| |
| @lisp |
| @group |
| @@lisp |
| (progn (print 'foo) (print 'bar)) |
| @@print@{@} foo |
| @@print@{@} bar |
| @@result@{@} bar |
| @@end lisp |
| @end group |
| @end lisp |
| |
| @node Error Glyph, Equivalence, Print Glyph, Glyphs |
| @section @error{}: Indicating an Error Message |
| @cindex Error message, indicating it |
| |
| A piece of code may cause an error when you evaluate it. You can |
| designate the error message with the @code{@@error@{@}} command.@refill |
| |
| @iftex |
| The @code{@@error@{@}} command is displayed as @samp{error-->} in Info |
| and as @samp{@error{}} in the printed output. |
| @end iftex |
| @ifinfo |
| The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info |
| and as the word `error' in a box in the printed output.@refill |
| @end ifinfo |
| |
| @need 700 |
| Thus, |
| |
| @example |
| @@lisp |
| (+ 23 'x) |
| @@error@{@} Wrong type argument: integer-or-marker-p, x |
| @@end lisp |
| @end example |
| |
| @noindent |
| produces |
| |
| @lisp |
| (+ 23 'x) |
| @error{} Wrong type argument: integer-or-marker-p, x |
| @end lisp |
| |
| @noindent |
| This indicates that the following error message is printed |
| when you evaluate the expression: |
| |
| @lisp |
| Wrong type argument: integer-or-marker-p, x |
| @end lisp |
| |
| Note that @samp{@error{}} itself is not part of the error |
| message. |
| |
| @node Equivalence, Point Glyph, Error Glyph, Glyphs |
| @section @equiv{}: Indicating Equivalence |
| @cindex Equivalence, indicating it |
| |
| Sometimes two expressions produce identical results. You can indicate the |
| exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill |
| |
| @iftex |
| The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and |
| as @samp{@equiv{}} in the printed output. |
| @end iftex |
| @ifinfo |
| The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info |
| and as a three parallel horizontal lines in the printed output.@refill |
| @end ifinfo |
| |
| Thus, |
| |
| @example |
| @@lisp |
| (make-sparse-keymap) @@equiv@{@} (list 'keymap) |
| @@end lisp |
| @end example |
| |
| @noindent |
| produces |
| |
| @lisp |
| (make-sparse-keymap) @equiv{} (list 'keymap) |
| @end lisp |
| |
| @noindent |
| This indicates that evaluating @code{(make-sparse-keymap)} produces |
| identical results to evaluating @code{(list 'keymap)}. |
| |
| @c Cannot write point command here because it causes trouble with TOC. |
| @node Point Glyph, , Equivalence, Glyphs |
| @section Indicating Point in a Buffer |
| @cindex Point, indicating it in a buffer |
| |
| Sometimes you need to show an example of text in an Emacs buffer. In |
| such examples, the convention is to include the entire contents of the |
| buffer in question between two lines of dashes containing the buffer |
| name.@refill |
| |
| You can use the @samp{@@point@{@}} command to show the location of point |
| in the text in the buffer. (The symbol for point, of course, is not |
| part of the text in the buffer; it indicates the place @emph{between} |
| two characters where point is located.)@refill |
| |
| @iftex |
| The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and |
| as @samp{@point{}} in the printed output. |
| @end iftex |
| @ifinfo |
| The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info |
| and as a small five pointed star in the printed output.@refill |
| @end ifinfo |
| |
| The following example shows the contents of buffer @file{foo} before |
| and after evaluating a Lisp command to insert the word @code{changed}.@refill |
| |
| @example |
| @group |
| ---------- Buffer: foo ---------- |
| This is the @point{}contents of foo. |
| ---------- Buffer: foo ---------- |
| |
| @end group |
| @end example |
| |
| @example |
| @group |
| (insert "changed ") |
| @result{} nil |
| ---------- Buffer: foo ---------- |
| This is the changed @point{}contents of foo. |
| ---------- Buffer: foo ---------- |
| |
| @end group |
| @end example |
| |
| In a Texinfo source file, the example is written like this:@refill |
| |
| @example |
| @@example |
| ---------- Buffer: foo ---------- |
| This is the @@point@{@}contents of foo. |
| ---------- Buffer: foo ---------- |
| |
| (insert "changed ") |
| @@result@{@} nil |
| ---------- Buffer: foo ---------- |
| This is the changed @@point@{@}contents of foo. |
| ---------- Buffer: foo ---------- |
| @@end example |
| @end example |
| |
| @node Breaks, Definition Commands, Glyphs, Top |
| @comment node-name, next, previous, up |
| @chapter Making and Preventing Breaks |
| @cindex Making line and page breaks |
| @cindex Preventing line and page breaks |
| |
| Usually, a Texinfo file is processed both by @TeX{} and by one of the |
| Info formatting commands. Line, paragraph, or page breaks sometimes |
| occur in the `wrong' place in one or other form of output. You must |
| ensure that text looks right both in the printed manual and in the |
| Info file.@refill |
| |
| For example, in a printed manual, page breaks may occur awkwardly in |
| the middle of an example; to prevent this, you can hold text together |
| using a grouping command that keeps the text from being split across |
| two pages. Conversely, you may want to force a page break where none |
| would occur normally. Fortunately, problems like these do not often |
| arise. When they do, use the break, break prevention, or pagination |
| commands.@refill |
| |
| @menu |
| * Break Commands:: Cause and prevent splits. |
| * Line Breaks:: How to force a single line to use two lines. |
| * - and hyphenation:: How to tell TeX about hyphenation points. |
| * w:: How to prevent unwanted line breaks. |
| * sp:: How to insert blank lines. |
| * page:: How to force the start of a new page. |
| * group:: How to prevent unwanted page breaks. |
| * need:: Another way to prevent unwanted page breaks. |
| @end menu |
| |
| @ifinfo |
| @node Break Commands, Line Breaks, Breaks, Breaks |
| @heading The Break Commands |
| @end ifinfo |
| @iftex |
| @sp 1 |
| @end iftex |
| |
| The break commands create or allow line and paragraph breaks:@refill |
| |
| @table @code |
| @item @@* |
| Force a line break. |
| |
| @item @@sp @var{n} |
| Skip @var{n} blank lines.@refill |
| |
| @item @@- |
| Insert a discretionary hyphen. |
| |
| @item @@hyphenation@{@var{hy-phen-a-ted words}@} |
| Define hyphen points in @var{hy-phen-a-ted words}. |
| @end table |
| |
| The line-break-prevention command holds text together all on one |
| line:@refill |
| |
| @table @code |
| @item @@w@{@var{text}@} |
| Prevent @var{text} from being split and hyphenated across two lines.@refill |
| @end table |
| @iftex |
| @sp 1 |
| @end iftex |
| |
| The pagination commands apply only to printed output, since Info |
| files do not have pages.@refill |
| |
| @table @code |
| @item @@page |
| Start a new page in the printed manual.@refill |
| |
| @item @@group |
| Hold text together that must appear on one printed page.@refill |
| |
| @item @@need @var{mils} |
| Start a new printed page if not enough space on this one.@refill |
| @end table |
| |
| @node Line Breaks, - and hyphenation, Break Commands, Breaks |
| @comment node-name, next, previous, up |
| @section @code{@@*}: Generate Line Breaks |
| @findex * @r{(force line break)} |
| @cindex Line breaks |
| @cindex Breaks in a line |
| |
| The @code{@@*} command forces a line break in both the printed manual and |
| in Info.@refill |
| |
| @need 700 |
| For example, |
| |
| @example |
| This line @@* is broken @@*in two places. |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| This line |
| is broken |
| in two places. |
| @end group |
| @end example |
| |
| @noindent |
| (Note that the space after the first @code{@@*} command is faithfully |
| carried down to the next line.)@refill |
| |
| @need 800 |
| The @code{@@*} command is often used in a file's copyright page:@refill |
| |
| @example |
| @group |
| This is edition 2.0 of the Texinfo documentation,@@* |
| and is for @dots{} |
| @end group |
| @end example |
| |
| @noindent |
| In this case, the @code{@@*} command keeps @TeX{} from stretching the |
| line across the whole page in an ugly manner.@refill |
| |
| @quotation |
| @strong{Please note:} Do not write braces after an @code{@@*} command; |
| they are not needed.@refill |
| |
| Do not write an @code{@@refill} command at the end of a paragraph |
| containing an @code{@@*} command; it will cause the paragraph to be |
| refilled after the line break occurs, negating the effect of the line |
| break.@refill |
| @end quotation |
| |
| @node - and hyphenation, w, Line Breaks, Breaks |
| @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate |
| |
| @findex - |
| @findex hyphenation |
| @cindex Hyphenation, helping @TeX{} do |
| @cindex Fine-tuning, and hyphenation |
| |
| Although @TeX{}'s hyphenation algorithm is generally pretty good, it |
| does miss useful hyphenation points from time to time. (Or, far more |
| rarely, insert an incorrect hyphenation.) So, for documents with an |
| unusual vocabulary or when fine-tuning for a printed edition, you may |
| wish to help @TeX{} out. Texinfo supports two commands for this: |
| |
| @table @code |
| @item @@- |
| Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does |
| not have to) hyphenate. This is especially useful when you notice |
| an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull |
| hboxes}). @TeX{} will not insert any hyphenation points in a word |
| containing @code{@@-}. |
| |
| @item @@hyphenation@{@var{hy-phen-a-ted words}@} |
| Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you |
| put a @samp{-} at each hyphenation point. For example: |
| @example |
| @@hyphenation@{man-u-script man-u-scripts@} |
| @end example |
| @noindent @TeX{} only uses the specified hyphenation points when the |
| words match exactly, so give all necessary variants. |
| @end table |
| |
| Info output is not hyphenated, so these commands have no effect there. |
| |
| @node w, sp, - and hyphenation, Breaks |
| @comment node-name, next, previous, up |
| @section @code{@@w}@{@var{text}@}: Prevent Line Breaks |
| @findex w @r{(prevent line break)} |
| @cindex Line breaks, preventing |
| @cindex Hyphenation, preventing |
| |
| @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks |
| within @var{text}.@refill |
| |
| You can use the @code{@@w} command to prevent @TeX{} from automatically |
| hyphenating a long name or phrase that accidentally falls near the end |
| of a line.@refill |
| |
| @example |
| You can copy GNU software from @@w@{@@file@{prep.ai.mit.edu@}@}. |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| You can copy GNU software from @w{@file{prep.ai.mit.edu}}. |
| @end quotation |
| |
| @quotation |
| @strong{Caution:} Do not write an @code{@@refill} command at the end |
| of a paragraph containing an @code{@@w} command; it will cause the |
| paragraph to be refilled and may thereby negate the effect of the |
| @code{@@w} command.@refill |
| @end quotation |
| |
| @node sp, page, w, Breaks |
| @comment node-name, next, previous, up |
| @section @code{@@sp} @var{n}: Insert Blank Lines |
| @findex sp @r{(line spacing)} |
| @cindex Spaces (blank lines) |
| @cindex Blank lines |
| @cindex Line spacing |
| |
| A line beginning with and containing only @code{@@sp @var{n}} |
| generates @var{n} blank lines of space in both the printed manual and |
| the Info file. @code{@@sp} also forces a paragraph break. For |
| example,@refill |
| |
| @example |
| @@sp 2 |
| @end example |
| |
| @noindent |
| generates two blank lines. |
| |
| The @code{@@sp} command is most often used in the title page.@refill |
| |
| @ignore |
| @c node br, page, sp, Breaks |
| @comment node-name, next, previous, up |
| @c section @code{@@br}: Generate Paragraph Breaks |
| @findex br @r{(paragraph breaks)} |
| @cindex Paragraph breaks |
| @cindex Breaks in a paragraph |
| |
| The @code{@@br} command forces a paragraph break. It inserts a blank |
| line. You can use the command within or at the end of a line. If |
| used within a line, the @code{@@br@{@}} command must be followed by |
| left and right braces (as shown here) to mark the end of the |
| command.@refill |
| |
| @need 700 |
| For example, |
| |
| @example |
| @group |
| This line @@br@{@}contains and is ended by paragraph breaks@@br |
| and is followed by another line. |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| @group |
| This line |
| |
| contains and is ended by paragraph breaks |
| |
| and is followed by another line. |
| @end group |
| @end example |
| |
| The @code{@@br} command is seldom used. |
| @end ignore |
| |
| @node page, group, sp, Breaks |
| @comment node-name, next, previous, up |
| @section @code{@@page}: Start a New Page |
| @cindex Page breaks |
| @findex page |
| |
| A line containing only @code{@@page} starts a new page in a printed |
| manual. The command has no effect on Info files since they are not |
| paginated. An @code{@@page} command is often used in the @code{@@titlepage} |
| section of a Texinfo file to start the copyright page.@refill |
| |
| @node group, need, page, Breaks |
| @comment node-name, next, previous, up |
| @section @code{@@group}: Prevent Page Breaks |
| @cindex Group (hold text together vertically) |
| @cindex Holding text together vertically |
| @cindex Vertically holding text together |
| @findex group |
| |
| The @code{@@group} command (on a line by itself) is used inside an |
| @code{@@example} or similar construct to begin an unsplittable vertical |
| group, which will appear entirely on one page in the printed output. |
| The group is terminated by a line containing only @code{@@end group}. |
| These two lines produce no output of their own, and in the Info file |
| output they have no effect at all.@refill |
| |
| @c Once said that these environments |
| @c turn off vertical spacing between ``paragraphs''. |
| @c Also, quotation used to work, but doesn't in texinfo-2.72 |
| Although @code{@@group} would make sense conceptually in a wide |
| variety of contexts, its current implementation works reliably only |
| within @code{@@example} and variants, and within @code{@@display}, |
| @code{@@format}, @code{@@flushleft} and @code{@@flushright}. |
| @xref{Quotations and Examples}. (What all these commands have in |
| common is that each line of input produces a line of output.) In |
| other contexts, @code{@@group} can cause anomalous vertical |
| spacing.@refill |
| |
| @need 750 |
| This formatting requirement means that you should write: |
| |
| @example |
| @group |
| @@example |
| @@group |
| @dots{} |
| @@end group |
| @@end example |
| @end group |
| @end example |
| |
| @noindent |
| with the @code{@@group} and @code{@@end group} commands inside the |
| @code{@@example} and @code{@@end example} commands. |
| |
| The @code{@@group} command is most often used to hold an example |
| together on one page. In this Texinfo manual, more than 100 examples |
| contain text that is enclosed between @code{@@group} and @code{@@end |
| group}. |
| |
| If you forget to end a group, you may get strange and unfathomable |
| error messages when you run @TeX{}. This is because @TeX{} keeps |
| trying to put the rest of the Texinfo file onto the one page and does |
| not start to generate error messages until it has processed |
| considerable text. It is a good rule of thumb to look for a missing |
| @code{@@end group} if you get incomprehensible error messages in |
| @TeX{}.@refill |
| |
| @node need, , group, Breaks |
| @comment node-name, next, previous, up |
| @section @code{@@need @var{mils}}: Prevent Page Breaks |
| @cindex Need space at page bottom |
| @findex need |
| |
| A line containing only @code{@@need @var{n}} starts |
| a new page in a printed manual if fewer than @var{n} mils (thousandths |
| of an inch) remain on the current page. Do not use |
| braces around the argument @var{n}. The @code{@@need} command has no |
| effect on Info files since they are not paginated.@refill |
| |
| @need 800 |
| This paragraph is preceded by an @code{@@need} command that tells |
| @TeX{} to start a new page if fewer than 800 mils (eight-tenths |
| inch) remain on the page. It looks like this:@refill |
| |
| @example |
| @group |
| @@need 800 |
| This paragraph is preceded by @dots{} |
| @end group |
| @end example |
| |
| The @code{@@need} command is useful for preventing orphans (single |
| lines at the bottoms of printed pages).@refill |
| |
| @node Definition Commands, Footnotes, Breaks, Top |
| @chapter Definition Commands |
| @cindex Definition commands |
| |
| The @code{@@deffn} command and the other @dfn{definition commands} |
| enable you to describe functions, variables, macros, commands, user |
| options, special forms and other such artifacts in a uniform |
| format.@refill |
| |
| In the Info file, a definition causes the entity |
| category---`Function', `Variable', or whatever---to appear at the |
| beginning of the first line of the definition, followed by the |
| entity's name and arguments. In the printed manual, the command |
| causes @TeX{} to print the entity's name and its arguments on the left |
| margin and print the category next to the right margin. In both |
| output formats, the body of the definition is indented. Also, the |
| name of the entity is entered into the appropriate index: |
| @code{@@deffn} enters the name into the index of functions, |
| @code{@@defvr} enters it into the index of variables, and so |
| on.@refill |
| |
| A manual need not and should not contain more than one definition for |
| a given name. An appendix containing a summary should use |
| @code{@@table} rather than the definition commands.@refill |
| |
| @menu |
| * Def Cmd Template:: How to structure a description using a |
| definition command. |
| * Optional Arguments:: How to handle optional and repeated arguments. |
| * deffnx:: How to group two or more `first' lines. |
| * Def Cmds in Detail:: All the definition commands. |
| * Def Cmd Conventions:: Conventions for writing definitions. |
| * Sample Function Definition:: |
| @end menu |
| |
| @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands |
| @section The Template for a Definition |
| @cindex Definition template |
| @cindex Template for a definition |
| |
| The @code{@@deffn} command is used for definitions of entities that |
| resemble functions. To write a definition using the @code{@@deffn} |
| command, write the @code{@@deffn} command at the beginning of a line |
| and follow it on the same line by the category of the entity, the name |
| of the entity itself, and its arguments (if any). Then write the body |
| of the definition on succeeding lines. (You may embed examples in the |
| body.) Finally, end the definition with an @code{@@end deffn} command |
| written on a line of its own. (The other definition commands follow |
| the same format.)@refill |
| |
| The template for a definition looks like this: |
| |
| @example |
| @group |
| @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| @var{body-of-definition} |
| @@end deffn |
| @end group |
| @end example |
| |
| @need 700 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| @@deffn Command forward-word count |
| This command moves point forward @@var@{count@} words |
| (or backward if @@var@{count@} is negative). @dots{} |
| @@end deffn |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| @deffn Command forward-word count |
| This function moves point forward @var{count} words |
| (or backward if @var{count} is negative). @dots{} |
| @end deffn |
| @end quotation |
| |
| Capitalize the category name like a title. If the name of the |
| category contains spaces, as in the phrase `Interactive Command', |
| write braces around it. For example:@refill |
| |
| @example |
| @group |
| @@deffn @{Interactive Command@} isearch-forward |
| @dots{} |
| @@end deffn |
| @end group |
| @end example |
| |
| @noindent |
| Otherwise, the second word will be mistaken for the name of the |
| entity.@refill |
| |
| Some of the definition commands are more general than others. The |
| @code{@@deffn} command, for example, is the general definition command |
| for functions and the like---for entities that may take arguments. When |
| you use this command, you specify the category to which the entity |
| belongs. The @code{@@deffn} command possesses three predefined, |
| specialized variations, @code{@@defun}, @code{@@defmac}, and |
| @code{@@defspec}, that specify the category for you: ``Function'', |
| ``Macro'', and ``Special Form'' respectively. The @code{@@defvr} |
| command also is accompanied by several predefined, specialized |
| variations for describing particular kinds of variables.@refill |
| |
| The template for a specialized definition, such as @code{@@defun}, is |
| similar to the template for a generalized definition, except that you |
| do not need to specify the category:@refill |
| |
| @example |
| @group |
| @@defun @var{name} @var{arguments}@dots{} |
| @var{body-of-definition} |
| @@end defun |
| @end group |
| @end example |
| |
| @noindent |
| Thus, |
| |
| @example |
| @group |
| @@defun buffer-end flag |
| This function returns @@code@{(point-min)@} if @@var@{flag@} |
| is less than 1, @@code@{(point-max)@} otherwise. |
| @dots{} |
| @@end defun |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @quotation |
| @defun buffer-end flag |
| This function returns @code{(point-min)} if @var{flag} is less than 1, |
| @code{(point-max)} otherwise. @dots{} |
| @end defun |
| @end quotation |
| |
| @noindent |
| @xref{Sample Function Definition, Sample Function Definition, A Sample |
| Function Definition}, for a more detailed example of a function |
| definition, including the use of @code{@@example} inside the |
| definition.@refill |
| |
| The other specialized commands work like @code{@@defun}.@refill |
| |
| @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands |
| @section Optional and Repeated Arguments |
| @cindex Optional and repeated arguments |
| @cindex Repeated and optional arguments |
| @cindex Arguments, repeated and optional |
| @cindex Syntax, optional & repeated arguments |
| @cindex Meta-syntactic chars for arguments |
| |
| Some entities take optional or repeated arguments, which may be |
| specified by a distinctive glyph that uses square brackets and |
| ellipses. For @w{example}, a special form often breaks its argument list |
| into separate arguments in more complicated ways than a |
| straightforward function.@refill |
| |
| @iftex |
| An argument enclosed within square brackets is optional. |
| Thus, the phrase |
| @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that |
| @var{optional-arg} is optional. |
| An argument followed by an ellipsis is optional |
| and may be repeated more than once. |
| @c This is consistent with Emacs Lisp Reference manual |
| Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments. |
| Parentheses are used when several arguments are grouped |
| into additional levels of list structure in Lisp. |
| @end iftex |
| @c The following looks better in Info (no `r', `samp' and `code'): |
| @ifinfo |
| An argument enclosed within square brackets is optional. |
| Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. |
| An argument followed by an ellipsis is optional |
| and may be repeated more than once. |
| @c This is consistent with Emacs Lisp Reference manual |
| Thus, @var{repeated-args}@dots{} stands for zero or more arguments. |
| Parentheses are used when several arguments are grouped |
| into additional levels of list structure in Lisp. |
| @end ifinfo |
| |
| Here is the @code{@@defspec} line of an example of an imaginary |
| special form:@refill |
| |
| @quotation |
| @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} |
| @end defspec |
| @tex |
| \vskip \parskip |
| @end tex |
| @end quotation |
| |
| @noindent |
| In this example, the arguments @var{from} and @var{to} are optional, |
| but must both be present or both absent. If they are present, |
| @var{inc} may optionally be specified as well. These arguments are |
| grouped with the argument @var{var} into a list, to distinguish them |
| from @var{body}, which includes all remaining elements of the |
| form.@refill |
| |
| In a Texinfo source file, this @code{@@defspec} line is written like |
| this (except it would not be split over two lines, as it is in this |
| example).@refill |
| |
| @example |
| @group |
| @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} |
| [@@var@{inc@}]]) @@var@{body@}@@dots@{@} |
| @end group |
| @end example |
| |
| @noindent |
| The function is listed in the Command and Variable Index under |
| @samp{foobar}.@refill |
| |
| @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands |
| @section Two or More `First' Lines |
| @cindex Two `First' Lines for @code{@@deffn} |
| @cindex Grouping two definitions together |
| @cindex Definitions grouped together |
| @findex deffnx |
| |
| To create two or more `first' or header lines for a definition, follow |
| the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. |
| The @code{@@deffnx} command works exactly like @code{@@deffn} |
| except that it does not generate extra vertical white space between it |
| and the preceding line.@refill |
| |
| @need 1000 |
| For example, |
| |
| @example |
| @group |
| @@deffn @{Interactive Command@} isearch-forward |
| @@deffnx @{Interactive Command@} isearch-backward |
| These two search commands are similar except @dots{} |
| @@end deffn |
| @end group |
| @end example |
| |
| @noindent |
| produces |
| |
| @deffn {Interactive Command} isearch-forward |
| @deffnx {Interactive Command} isearch-backward |
| These two search commands are similar except @dots{} |
| @end deffn |
| |
| Each of the other definition commands has an `x' form: @code{@@defunx}, |
| @code{@@defvrx}, @code{@@deftypefunx}, etc. |
| |
| The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. |
| |
| @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands |
| @section The Definition Commands |
| |
| Texinfo provides more than a dozen definition commands, all of which |
| are described in this section.@refill |
| |
| The definition commands automatically enter the name of the entity in |
| the appropriate index: for example, @code{@@deffn}, @code{@@defun}, |
| and @code{@@defmac} enter function names in the index of functions; |
| @code{@@defvr} and @code{@@defvar} enter variable names in the index |
| of variables.@refill |
| |
| Although the examples that follow mostly illustrate Lisp, the commands |
| can be used for other programming languages.@refill |
| |
| @menu |
| * Functions Commands:: Commands for functions and similar entities. |
| * Variables Commands:: Commands for variables and similar entities. |
| * Typed Functions:: Commands for functions in typed languages. |
| * Typed Variables:: Commands for variables in typed languages. |
| * Abstract Objects:: Commands for object-oriented programming. |
| * Data Types:: The definition command for data types. |
| @end menu |
| |
| @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail |
| @subsection Functions and Similar Entities |
| |
| This section describes the commands for describing functions and similar |
| entities:@refill |
| |
| @table @code |
| @findex deffn |
| @item @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| The @code{@@deffn} command is the general definition command for |
| functions, interactive commands, and similar entities that may take |
| arguments. You must choose a term to describe the category of entity |
| being defined; for example, ``Function'' could be used if the entity is |
| a function. The @code{@@deffn} command is written at the beginning of a |
| line and is followed on the same line by the category of entity being |
| described, the name of this particular entity, and its arguments, if |
| any. Terminate the definition with @code{@@end deffn} on a line of its |
| own.@refill |
| |
| @need 750 |
| For example, here is a definition: |
| |
| @example |
| @group |
| @@deffn Command forward-char nchars |
| Move point forward @@var@{nchars@} characters. |
| @@end deffn |
| @end group |
| @end example |
| |
| @noindent |
| This shows a rather terse definition for a ``command'' named |
| @code{forward-char} with one argument, @var{nchars}. |
| |
| @code{@@deffn} prints argument names such as @var{nchars} in italics or |
| upper case, as if @code{@@var} had been used, because we think of these |
| names as metasyntactic variables---they stand for the actual argument |
| values. Within the text of the description, write an argument name |
| explicitly with @code{@@var} to refer to the value of the argument. In |
| the example above, we used @samp{@@var@{nchars@}} in this way. |
| |
| The template for @code{@@deffn} is: |
| |
| @example |
| @group |
| @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| @var{body-of-definition} |
| @@end deffn |
| @end group |
| @end example |
| |
| @findex defun |
| @item @@defun @var{name} @var{arguments}@dots{} |
| The @code{@@defun} command is the definition command for functions. |
| @code{@@defun} is equivalent to @samp{@@deffn Function |
| @dots{}}.@refill |
| |
| @need 800 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| @@defun set symbol new-value |
| Change the value of the symbol @@var@{symbol@} |
| to @@var@{new-value@}. |
| @@end defun |
| @end group |
| @end example |
| |
| @noindent |
| shows a rather terse definition for a function @code{set} whose |
| arguments are @var{symbol} and @var{new-value}. The argument names on |
| the @code{@@defun} line automatically appear in italics or upper case as |
| if they were enclosed in @code{@@var}. Terminate the definition with |
| @code{@@end defun} on a line of its own.@refill |
| |
| The template is: |
| |
| @example |
| @group |
| @@defun @var{function-name} @var{arguments}@dots{} |
| @var{body-of-definition} |
| @@end defun |
| @end group |
| @end example |
| |
| @code{@@defun} creates an entry in the index of functions. |
| |
| @findex defmac |
| @item @@defmac @var{name} @var{arguments}@dots{} |
| The @code{@@defmac} command is the definition command for macros. |
| @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and |
| works like @code{@@defun}.@refill |
| |
| @findex defspec |
| @item @@defspec @var{name} @var{arguments}@dots{} |
| The @code{@@defspec} command is the definition command for special |
| forms. (In Lisp, a special form is an entity much like a function.) |
| @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} |
| @dots{}} and works like @code{@@defun}.@refill |
| @end table |
| |
| @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail |
| @subsection Variables and Similar Entities |
| |
| Here are the commands for defining variables and similar |
| entities:@refill |
| |
| @table @code |
| @findex defvr |
| @item @@defvr @var{category} @var{name} |
| The @code{@@defvr} command is a general definition command for |
| something like a variable---an entity that records a value. You must |
| choose a term to describe the category of entity being defined; for |
| example, ``Variable'' could be used if the entity is a variable. |
| Write the @code{@@defvr} command at the beginning of a line and |
| followed it on the same line by the category of the entity and the |
| name of the entity.@refill |
| |
| Capitalize the category name like a title. If the name of the |
| category contains spaces, as in the name `User Option', write braces |
| around it. Otherwise, the second word will be mistaken for the name |
| of the entity, for example: |
| |
| @example |
| @group |
| @@defvr @{User Option@} fill-column |
| This buffer-local variable specifies |
| the maximum width of filled lines. |
| @dots{} |
| @@end defvr |
| @end group |
| @end example |
| |
| Terminate the definition with @code{@@end defvr} on a line of its |
| own.@refill |
| |
| The template is: |
| |
| @example |
| @group |
| @@defvr @var{category} @var{name} |
| @var{body-of-definition} |
| @@end defvr |
| @end group |
| @end example |
| |
| @code{@@defvr} creates an entry in the index of variables for @var{name}. |
| |
| @findex defvar |
| @item @@defvar @var{name} |
| The @code{@@defvar} command is the definition command for variables. |
| @code{@@defvar} is equivalent to @samp{@@defvr Variable |
| @dots{}}.@refill |
| |
| @need 750 |
| For example: |
| |
| @example |
| @group |
| @@defvar kill-ring |
| @dots{} |
| @@end defvar |
| @end group |
| @end example |
| |
| The template is: |
| |
| @example |
| @group |
| @@defvar @var{name} |
| @var{body-of-definition} |
| @@end defvar |
| @end group |
| @end example |
| |
| @code{@@defvar} creates an entry in the index of variables for |
| @var{name}.@refill |
| |
| @findex defopt |
| @item @@defopt @var{name} |
| The @code{@@defopt} command is the definition command for user |
| options. @code{@@defopt} is equivalent to @samp{@@defvr @{User |
| Option@} @dots{}} and works like @code{@@defvar}.@refill |
| @end table |
| |
| @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail |
| @subsection Functions in Typed Languages |
| |
| The @code{@@deftypefn} command and its variations are for describing |
| functions in C or any other language in which you must declare types |
| of variables and functions.@refill |
| |
| @table @code |
| @findex deftypefn |
| @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} |
| The @code{@@deftypefn} command is the general definition command for |
| functions and similar entities that may take arguments and that are |
| typed. The @code{@@deftypefn} command is written at the beginning of |
| a line and is followed on the same line by the category of entity |
| being described, the type of the returned value, the name of this |
| particular entity, and its arguments, if any.@refill |
| |
| @need 800 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| @@deftypefn @{Library Function@} int foobar |
| (int @@var@{foo@}, float @@var@{bar@}) |
| @dots{} |
| @@end deftypefn |
| @end group |
| @end example |
| |
| @need 1000 |
| @noindent |
| (where the text before the ``@dots{}'', shown above as two lines, would |
| actually be a single line in a real Texinfo file) produces the following |
| in Info: |
| |
| @smallexample |
| @group |
| -- Library Function: int foobar (int FOO, float BAR) |
| @dots{} |
| @end group |
| @end smallexample |
| @iftex |
| |
| In a printed manual, it produces: |
| |
| @quotation |
| @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) |
| @dots{} |
| @end deftypefn |
| @end quotation |
| @end iftex |
| |
| This means that @code{foobar} is a ``library function'' that returns an |
| @code{int}, and its arguments are @var{foo} (an @code{int}) and |
| @var{bar} (a @code{float}).@refill |
| |
| The argument names that you write in @code{@@deftypefn} are not subject |
| to an implicit @code{@@var}---since the actual names of the arguments in |
| @code{@@deftypefn} are typically scattered among data type names and |
| keywords, Texinfo cannot find them without help. Instead, you must write |
| @code{@@var} explicitly around the argument names. In the example |
| above, the argument names are @samp{foo} and @samp{bar}.@refill |
| |
| The template for @code{@@deftypefn} is:@refill |
| |
| @example |
| @group |
| @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} |
| @var{body-of-description} |
| @@end deftypefn |
| @end group |
| @end example |
| |
| @noindent |
| Note that if the @var{category} or @var{data type} is more than one |
| word then it must be enclosed in braces to make it a single argument.@refill |
| |
| If you are describing a procedure in a language that has packages, |
| such as Ada, you might consider using @code{@@deftypefn} in a manner |
| somewhat contrary to the convention described in the preceding |
| paragraphs.@refill |
| |
| @need 800 |
| @noindent |
| For example: |
| |
| @example |
| @group |
| @@deftypefn stacks private push |
| (@@var@{s@}:in out stack; |
| @@var@{n@}:in integer) |
| @dots{} |
| @@end deftypefn |
| @end group |
| @end example |
| |
| @noindent |
| (The @code{@@deftypefn} arguments are shown split into three lines, but |
| would be a single line in a real Texinfo file.) |
| |
| In this instance, the procedure is classified as belonging to the |
| package @code{stacks} rather than classified as a `procedure' and its |
| data type is described as @code{private}. (The name of the procedure |
| is @code{push}, and its arguments are @var{s} and @var{n}.)@refill |
| |
| @code{@@deftypefn} creates an entry in the index of functions for |
| @var{name}.@refill |
| |
| @findex deftypefun |
| @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} |
| The @code{@@deftypefun} command is the specialized definition command |
| for functions in typed languages. The command is equivalent to |
| @samp{@@deftypefn Function @dots{}}.@refill |
| |
| @need 800 |
| @noindent |
| Thus, |
| |
| @smallexample |
| @group |
| @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@}) |
| @dots{} |
| @@end deftypefun |
| @end group |
| @end smallexample |
| |
| @noindent |
| produces the following in Info: |
| |
| @example |
| @group |
| -- Function: int foobar (int FOO, float BAR) |
| @dots{} |
| @end group |
| @end example |
| @iftex |
| |
| @need 800 |
| @noindent |
| and the following in a printed manual: |
| |
| @quotation |
| @deftypefun int foobar (int @var{foo}, float @var{bar}) |
| @dots{} |
| @end deftypefun |
| @end quotation |
| @end iftex |
| |
| @need 800 |
| The template is: |
| |
| @example |
| @group |
| @@deftypefun @var{type} @var{name} @var{arguments}@dots{} |
| @var{body-of-description} |
| @@end deftypefun |
| @end group |
| @end example |
| |
| @code{@@deftypefun} creates an entry in the index of functions for |
| @var{name}.@refill |
| @end table |
| |
| @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail |
| @subsection Variables in Typed Languages |
| |
| Variables in typed languages are handled in a manner similar to |
| functions in typed languages. @xref{Typed Functions}. The general |
| definition command @code{@@deftypevr} corresponds to |
| @code{@@deftypefn} and the specialized definition command |
| @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill |
| |
| @table @code |
| @findex deftypevr |
| @item @@deftypevr @var{category} @var{data-type} @var{name} |
| The @code{@@deftypevr} command is the general definition command for |
| something like a variable in a typed language---an entity that records |
| a value. You must choose a term to describe the category of the |
| entity being defined; for example, ``Variable'' could be used if the |
| entity is a variable.@refill |
| |
| The @code{@@deftypevr} command is written at the beginning of a line |
| and is followed on the same line by the category of the entity |
| being described, the data type, and the name of this particular |
| entity.@refill |
| |
| @need 800 |
| @noindent |
| For example: |
| |
| @example |
| @group |
| @@deftypevr @{Global Flag@} int enable |
| @dots{} |
| @@end deftypevr |
| @end group |
| @end example |
| |
| @noindent |
| produces the following in Info: |
| |
| @example |
| @group |
| -- Global Flag: int enable |
| @dots{} |
| @end group |
| @end example |
| @iftex |
| |
| @noindent |
| and the following in a printed manual: |
| |
| @quotation |
| @deftypevr {Global Flag} int enable |
| @dots{} |
| @end deftypevr |
| @end quotation |
| @end iftex |
| |
| @need 800 |
| The template is: |
| |
| @example |
| @@deftypevr @var{category} @var{data-type} @var{name} |
| @var{body-of-description} |
| @@end deftypevr |
| @end example |
| |
| @code{@@deftypevr} creates an entry in the index of variables for |
| @var{name}.@refill |
| |
| @findex deftypevar |
| @item @@deftypevar @var{data-type} @var{name} |
| The @code{@@deftypevar} command is the specialized definition command |
| for variables in typed languages. @code{@@deftypevar} is equivalent |
| to @samp{@@deftypevr Variable @dots{}}.@refill |
| |
| @need 800 |
| @noindent |
| For example: |
| |
| @example |
| @group |
| @@deftypevar int fubar |
| @dots{} |
| @@end deftypevar |
| @end group |
| @end example |
| |
| @noindent |
| produces the following in Info: |
| |
| @example |
| @group |
| -- Variable: int fubar |
| @dots{} |
| @end group |
| @end example |
| @iftex |
| |
| @need 800 |
| @noindent |
| and the following in a printed manual: |
| |
| @quotation |
| @deftypevar int fubar |
| @dots{} |
| @end deftypevar |
| @end quotation |
| @end iftex |
| |
| @need 800 |
| @noindent |
| The template is: |
| |
| @example |
| @group |
| @@deftypevar @var{data-type} @var{name} |
| @var{body-of-description} |
| @@end deftypevar |
| @end group |
| @end example |
| |
| @code{@@deftypevar} creates an entry in the index of variables for |
| @var{name}.@refill |
| @end table |
| |
| @node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail |
| @subsection Object-Oriented Programming |
| |
| Here are the commands for formatting descriptions about abstract |
| objects, such as are used in object-oriented programming. A class is |
| a defined type of abstract object. An instance of a class is a |
| particular object that has the type of the class. An instance |
| variable is a variable that belongs to the class but for which each |
| instance has its own value.@refill |
| |
| In a definition, if the name of a class is truly a name defined in the |
| programming system for a class, then you should write an @code{@@code} |
| around it. Otherwise, it is printed in the usual text font.@refill |
| |
| @table @code |
| @findex defcv |
| @item @@defcv @var{category} @var{class} @var{name} |
| The @code{@@defcv} command is the general definition command for |
| variables associated with classes in object-oriented programming. The |
| @code{@@defcv} command is followed by three arguments: the category of |
| thing being defined, the class to which it belongs, and its |
| name. Thus,@refill |
| |
| @example |
| @group |
| @@defcv @{Class Option@} Window border-pattern |
| @dots{} |
| @@end defcv |
| @end group |
| @end example |
| |
| @noindent |
| illustrates how you would write the first line of a definition of the |
| @code{border-pattern} class option of the class @code{Window}.@refill |
| |
| The template is |
| |
| @example |
| @group |
| @@defcv @var{category} @var{class} @var{name} |
| @dots{} |
| @@end defcv |
| @end group |
| @end example |
| |
| @code{@@defcv} creates an entry in the index of variables. |
| |
| @findex defivar |
| @item @@defivar @var{class} @var{name} |
| The @code{@@defivar} command is the definition command for instance |
| variables in object-oriented programming. @code{@@defivar} is |
| equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill |
| |
| The template is: |
| |
| @example |
| @group |
| @@defivar @var{class} @var{instance-variable-name} |
| @var{body-of-definition} |
| @@end defivar |
| @end group |
| @end example |
| |
| @code{@@defivar} creates an entry in the index of variables. |
| |
| @findex defop |
| @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| The @code{@@defop} command is the general definition command for |
| entities that may resemble methods in object-oriented programming. |
| These entities take arguments, as functions do, but are associated |
| with particular classes of objects.@refill |
| |
| For example, some systems have constructs called @dfn{wrappers} that |
| are associated with classes as methods are, but that act more like |
| macros than like functions. You could use @code{@@defop Wrapper} to |
| describe one of these.@refill |
| |
| Sometimes it is useful to distinguish methods and @dfn{operations}. |
| You can think of an operation as the specification for a method. |
| Thus, a window system might specify that all window classes have a |
| method named @code{expose}; we would say that this window system |
| defines an @code{expose} operation on windows in general. Typically, |
| the operation has a name and also specifies the pattern of arguments; |
| all methods that implement the operation must accept the same |
| arguments, since applications that use the operation do so without |
| knowing which method will implement it.@refill |
| |
| Often it makes more sense to document operations than methods. For |
| example, window application developers need to know about the |
| @code{expose} operation, but need not be concerned with whether a |
| given class of windows has its own method to implement this operation. |
| To describe this operation, you would write:@refill |
| |
| @example |
| @@defop Operation windows expose |
| @end example |
| |
| The @code{@@defop} command is written at the beginning of a line and |
| is followed on the same line by the overall name of the category of |
| operation, the name of the class of the operation, the name of the |
| operation, and its arguments, if any.@refill |
| |
| @need 800 |
| @noindent |
| The template is: |
| |
| @example |
| @group |
| @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| @var{body-of-definition} |
| @@end defop |
| @end group |
| @end example |
| |
| @code{@@defop} creates an entry, such as `@code{expose} on |
| @code{windows}', in the index of functions.@refill |
| |
| @findex defmethod |
| @item @@defmethod @var{class} @var{name} @var{arguments}@dots{} |
| The @code{@@defmethod} command is the definition command for methods |
| in object-oriented programming. A method is a kind of function that |
| implements an operation for a particular class of objects and its |
| subclasses. In the Lisp Machine, methods actually were functions, but |
| they were usually defined with @code{defmethod}. |
| |
| @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. |
| The command is written at the beginning of a line and is followed by |
| the name of the class of the method, the name of the method, and its |
| arguments, if any.@refill |
| |
| @need 800 |
| @noindent |
| For example, |
| |
| @example |
| @group |
| @@defmethod @code{bar-class} bar-method argument |
| @dots{} |
| @@end defmethod |
| @end group |
| @end example |
| |
| @noindent |
| illustrates the definition for a method called @code{bar-method} of |
| the class @code{bar-class}. The method takes an argument.@refill |
| |
| The template is: |
| |
| @example |
| @group |
| @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} |
| @var{body-of-definition} |
| @@end defmethod |
| @end group |
| @end example |
| |
| @code{@@defmethod} creates an entry, such as `@code{bar-method} on |
| @code{bar-class}', in the index of functions.@refill |
| @end table |
| |
| @node Data Types, , Abstract Objects, Def Cmds in Detail |
| @subsection Data Types |
| |
| Here is the command for data types:@refill |
| |
| @table @code |
| @findex deftp |
| @item @@deftp @var{category} @var{name} @var{attributes}@dots{} |
| The @code{@@deftp} command is the generic definition command for data |
| types. The command is written at the beginning of a line and is |
| followed on the same line by the category, by the name of the type |
| (which is a word like @code{int} or @code{float}), and then by names of |
| attributes of objects of that type. Thus, you could use this command |
| for describing @code{int} or @code{float}, in which case you could use |
| @code{data type} as the category. (A data type is a category of |
| certain objects for purposes of deciding which operations can be |
| performed on them.)@refill |
| |
| In Lisp, for example, @dfn{pair} names a particular data |
| type, and an object of that type has two slots called the |
| @sc{car} and the @sc{cdr}. Here is how you would write the first line |
| of a definition of @code{pair}.@refill |
| |
| @example |
| @group |
| @@deftp @{Data type@} pair car cdr |
| @dots{} |
| @@end deftp |
| @end group |
| @end example |
| |
| @need 950 |
| The template is: |
| |
| @example |
| @group |
| @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} |
| @var{body-of-definition} |
| @@end deftp |
| @end group |
| @end example |
| |
| @code{@@deftp} creates an entry in the index of data types. |
| @end table |
| |
| @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands |
| @section Conventions for Writing Definitions |
| @cindex Definition conventions |
| @cindex Conventions for writing definitions |
| |
| When you write a definition using @code{@@deffn}, @code{@@defun}, or |
| one of the other definition commands, please take care to use |
| arguments that indicate the meaning, as with the @var{count} argument |
| to the @code{forward-word} function. Also, if the name of an argument |
| contains the name of a type, such as @var{integer}, take care that the |
| argument actually is of that type.@refill |
| |
| @node Sample Function Definition, , Def Cmd Conventions, Definition Commands |
| @section A Sample Function Definition |
| @cindex Function definitions |
| @cindex Command definitions |
| @cindex Macro definitions |
| @cindex Sample function definition |
| |
| A function definition uses the @code{@@defun} and @code{@@end defun} |
| commands. The name of the function follows immediately after the |
| @code{@@defun} command and it is followed, on the same line, by the |
| parameter list.@refill |
| |
| Here is a definition from @cite{The GNU Emacs Lisp Reference Manual}. |
| (@xref{Calling Functions, , Calling Functions, elisp, The GNU Emacs |
| Lisp Reference Manual}.) |
| |
| @quotation |
| @defun apply function &rest arguments |
| @code{apply} calls @var{function} with @var{arguments}, just |
| like @code{funcall} but with one difference: the last of |
| @var{arguments} is a list of arguments to give to |
| @var{function}, rather than a single argument. We also say |
| that this list is @dfn{appended} to the other arguments. |
| |
| @code{apply} returns the result of calling @var{function}. |
| As with @code{funcall}, @var{function} must either be a Lisp |
| function or a primitive function; special forms and macros |
| do not make sense in @code{apply}. |
| |
| @example |
| (setq f 'list) |
| @result{} list |
| (apply f 'x 'y 'z) |
| @error{} Wrong type argument: listp, z |
| (apply '+ 1 2 '(3 4)) |
| @result{} 10 |
| (apply '+ '(1 2 3 4)) |
| @result{} 10 |
| |
| (apply 'append '((a b c) nil (x y z) nil)) |
| @result{} (a b c x y z) |
| @end example |
| |
| An interesting example of using @code{apply} is found in the description |
| of @code{mapcar}.@refill |
| @end defun |
| @end quotation |
| |
| @need 1200 |
| In the Texinfo source file, this example looks like this: |
| |
| @example |
| @group |
| @@defun apply function &rest arguments |
| |
| @@code@{apply@} calls @@var@{function@} with |
| @@var@{arguments@}, just like @@code@{funcall@} but with one |
| difference: the last of @@var@{arguments@} is a list of |
| arguments to give to @@var@{function@}, rather than a single |
| argument. We also say that this list is @@dfn@{appended@} |
| to the other arguments. |
| @end group |
| |
| @group |
| @@code@{apply@} returns the result of calling |
| @@var@{function@}. As with @@code@{funcall@}, |
| @@var@{function@} must either be a Lisp function or a |
| primitive function; special forms and macros do not make |
| sense in @@code@{apply@}. |
| @end group |
| |
| @group |
| @@example |
| (setq f 'list) |
| @@result@{@} list |
| (apply f 'x 'y 'z) |
| @@error@{@} Wrong type argument: listp, z |
| (apply '+ 1 2 '(3 4)) |
| @@result@{@} 10 |
| (apply '+ '(1 2 3 4)) |
| @@result@{@} 10 |
| |
| (apply 'append '((a b c) nil (x y z) nil)) |
| @@result@{@} (a b c x y z) |
| @@end example |
| @end group |
| |
| @group |
| An interesting example of using @@code@{apply@} is found |
| in the description of @@code@{mapcar@}.@@refill |
| @@end defun |
| @end group |
| @end example |
| |
| @noindent |
| In this manual, this function is listed in the Command and Variable |
| Index under @code{apply}.@refill |
| |
| Ordinary variables and user options are described using a format like |
| that for functions except that variables do not take arguments. |
| |
| @node Footnotes, Conditionals, Definition Commands, Top |
| @comment node-name, next, previous, up |
| @chapter Footnotes |
| @cindex Footnotes |
| @findex footnote |
| |
| A @dfn{footnote} is for a reference that documents or elucidates the |
| primary text.@footnote{A footnote should complement or expand upon |
| the primary text, but a reader should not need to read a footnote to |
| understand the primary text. For a thorough discussion of footnotes, |
| see @cite{The Chicago Manual of Style}, which is published by the |
| University of Chicago Press.}@refill |
| |
| @menu |
| * Footnote Commands:: How to write a footnote in Texinfo. |
| * Footnote Styles:: Controlling how footnotes appear in Info. |
| @end menu |
| |
| @node Footnote Commands, Footnote Styles, Footnotes, Footnotes |
| @section Footnote Commands |
| |
| In Texinfo, footnotes are created with the @code{@@footnote} command. |
| This command is followed immediately by a left brace, then by the text |
| of the footnote, and then by a terminating right brace. The template |
| is: |
| |
| @example |
| @@footnote@{@var{text}@} |
| @end example |
| |
| Footnotes may be of any length, but are usually short.@refill |
| |
| For example, this clause is followed by a sample |
| footnote@footnote{Here is the sample footnote.}; in the Texinfo |
| source, it looks like this:@refill |
| |
| @example |
| @dots{}a sample footnote @@footnote@{Here is the sample |
| footnote.@}; in the Texinfo source@dots{} |
| @end example |
| |
| @strong{Warning:} Don't use footnotes in the argument of the |
| @code{@@item} command for a @code{@@table} table. This doesn't work; |
| because of limitations of @TeX{}, there is no way to fix it. To avoid |
| the problem, move the footnote into the body text of the table. |
| |
| In a printed manual or book, the reference mark for a footnote is a |
| small, superscripted number; the text of the footnote appears at the |
| bottom of the page, below a horizontal line.@refill |
| |
| In Info, the reference mark for a footnote is a pair of parentheses |
| with the footnote number between them, like this: @samp{(1)}.@refill |
| |
| @node Footnote Styles, , Footnote Commands, Footnotes |
| @section Footnote Styles |
| |
| Info has two footnote styles, which determine where the text of the |
| footnote is located:@refill |
| |
| @itemize @bullet |
| @cindex @samp{@r{End}} node footnote style |
| @item |
| In the `End' node style, all the footnotes for a single node |
| are placed at the end of that node. The footnotes are separated from |
| the rest of the node by a line of dashes with the word |
| @samp{Footnotes} within it. Each footnote begins with an |
| @samp{(@var{n})} reference mark.@refill |
| |
| @need 700 |
| @noindent |
| Here is an example of a single footnote in the end of node style:@refill |
| |
| @example |
| @group |
| --------- Footnotes --------- |
| |
| (1) Here is a sample footnote. |
| @end group |
| @end example |
| |
| @cindex @samp{@r{Separate}} footnote style |
| @item |
| In the `Separate' node style, all the footnotes for a single |
| node are placed in an automatically constructed node of |
| their own. In this style, a ``footnote reference'' follows |
| each @samp{(@var{n})} reference mark in the body of the |
| node. The footnote reference is actually a cross reference |
| which you use to reach the footnote node.@refill |
| |
| The name of the node containing the footnotes is constructed |
| by appending @w{@samp{-Footnotes}} to the name of the node |
| that contains the footnotes. (Consequently, the footnotes' |
| node for the @file{Footnotes} node is |
| @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an |
| `Up' node pointer that leads back to its parent node.@refill |
| |
| @noindent |
| Here is how the first footnote in this manual looks after being |
| formatted for Info in the separate node style:@refill |
| |
| @smallexample |
| @group |
| File: texinfo.info Node: Overview-Footnotes, Up: Overview |
| |
| (1) Note that the first syllable of "Texinfo" is |
| pronounced like "speck", not "hex". @dots{} |
| @end group |
| @end smallexample |
| @end itemize |
| |
| A Texinfo file may be formatted into an Info file with either footnote |
| style.@refill |
| |
| @findex footnotestyle |
| Use the @code{@@footnotestyle} command to specify an Info file's |
| footnote style. Write this command at the beginning of a line followed |
| by an argument, either @samp{end} for the end node style or |
| @samp{separate} for the separate node style. |
| |
| @need 700 |
| For example, |
| |
| @example |
| @@footnotestyle end |
| @end example |
| @noindent |
| or |
| @example |
| @@footnotestyle separate |
| @end example |
| |
| Write an @code{@@footnotestyle} command before or shortly after the |
| end-of-header line at the beginning of a Texinfo file. (If you |
| include the @code{@@footnotestyle} command between the start-of-header |
| and end-of-header lines, the region formatting commands will format |
| footnotes as specified.)@refill |
| |
| If you do not specify a footnote style, the formatting commands use |
| their default style. Currently, @code{texinfo-format-buffer} and |
| @code{texinfo-format-region} use the `separate' style and |
| @code{makeinfo} uses the `end' style.@refill |
| |
| @c !!! note: makeinfo's --footnote-style option overrides footnotestyle |
| @ignore |
| If you use @code{makeinfo} to create the Info file, the |
| @samp{--footnote-style} option determines which style is used, |
| @samp{end} for the end of node style or @samp{separate} for the |
| separate node style. Thus, to format the Texinfo manual in the |
| separate node style, you would use the following shell command:@refill |
| |
| @example |
| makeinfo --footnote-style=separate texinfo.texi |
| @end example |
| |
| @noindent |
| To format the Texinfo manual in the end of node style, you would |
| type:@refill |
| |
| @example |
| makeinfo --footnote-style=end texinfo.texi |
| @end example |
| @end ignore |
| @ignore |
| If you use @code{texinfo-format-buffer} or |
| @code{texinfo-format-region} to create the Info file, the value of the |
| @code{texinfo-footnote-style} variable controls the footnote style. |
| It can be either @samp{"separate"} for the separate node style or |
| @samp{"end"} for the end of node style. (You can change the value of |
| this variable with the @kbd{M-x edit-options} command (@pxref{Edit |
| Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or |
| with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining |
| and Setting Variables, emacs, The GNU Emacs Manual}).@refill |
| |
| The @code{texinfo-footnote-style} variable also controls the style if |
| you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} |
| command in Emacs.@refill |
| @end ignore |
| This chapter contains two footnotes.@refill |
| |
| @node Conditionals, Macros, Footnotes, Top |
| @comment node-name, next, previous, up |
| @chapter Conditionally Visible Text |
| @cindex Conditionally visible text |
| @cindex Text, conditionally visible |
| @cindex Visibility of conditional text |
| @cindex If text conditionally visible |
| @findex ifhtml |
| @findex ifinfo |
| @findex iftex |
| |
| Sometimes it is good to use different text for a printed manual and |
| its corresponding Info file. In this case, you can use the |
| @dfn{conditional commands} to specify which text is for the printed manual |
| and which is for the Info file.@refill |
| |
| @menu |
| * Conditional Commands:: How to specify text for HTML, Info, or @TeX{}. |
| * Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. |
| * set clear value:: How to designate which text to format (for |
| both Info and @TeX{}); and how to set a |
| flag to a string that you can insert. |
| @end menu |
| |
| @node Conditional Commands, Using Ordinary TeX Commands, Conditionals, Conditionals |
| @ifinfo |
| @heading Using @code{@@ifinfo} and @code{@@iftex} |
| @end ifinfo |
| |
| @code{@@ifinfo} begins segments of text that should be ignored |
| by @TeX{} when it |
| typesets the printed manual. The segment of text appears only |
| in the Info file. |
| The @code{@@ifinfo} command should appear on a line by itself; end |
| the Info-only text with a line containing @code{@@end ifinfo} by |
| itself. At the beginning of a Texinfo file, the Info permissions are |
| contained within a region marked by @code{@@ifinfo} and @code{@@end |
| ifinfo}. (@xref{Info Summary and Permissions}.)@refill |
| |
| The @code{@@iftex} and @code{@@end iftex} commands are similar to the |
| @code{@@ifinfo} and @code{@@end ifinfo} commands, except that they |
| specify text that will appear in the printed manual but not in the Info |
| file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which |
| specify text to appear only in HTML output.@refill |
| |
| @need 700 |
| For example, |
| |
| @example |
| @@iftex |
| This text will appear only in the printed manual. |
| @@end iftex |
| |
| @@ifinfo |
| However, this text will appear only in Info. |
| @@end ifinfo |
| @end example |
| |
| @noindent |
| The preceding example produces the following line: |
| |
| @iftex |
| This text will appear only in the printed manual. |
| @end iftex |
| |
| @ifinfo |
| However, this text will appear only in Info. |
| @end ifinfo |
| |
| @noindent |
| Note how you only see one of the two lines, depending on whether you |
| are reading the Info version or the printed version of this |
| manual.@refill |
| |
| The @code{@@titlepage} command is a special variant of @code{@@iftex} that |
| is used for making the title and copyright pages of the printed |
| manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill |
| |
| @node Using Ordinary TeX Commands, set clear value, Conditional Commands, Conditionals |
| @comment node-name, next, previous, up |
| @section Using Ordinary @TeX{} Commands |
| @cindex @TeX{} commands, using ordinary |
| @cindex Ordinary @TeX{} commands, using |
| @cindex Commands using ordinary @TeX{} |
| @cindex plain @TeX{} |
| |
| Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, |
| you can embed some plain @TeX{} commands. Info will ignore these |
| commands since they are only in that part of the file which is seen by |
| @TeX{}. You can write the @TeX{} commands as you would write them in |
| a normal @TeX{} file, except that you must replace the @samp{\} used |
| by @TeX{} with an @samp{@@}. For example, in the @code{@@titlepage} |
| section of a Texinfo file, you can use the @TeX{} command |
| @code{@@vskip} to format the copyright page. (The @code{@@titlepage} |
| command causes Info to ignore the region automatically, as it does |
| with the @code{@@iftex} command.)@refill |
| |
| However, many features of plain @TeX{} will not work, as they are |
| overridden by features of Texinfo. |
| |
| @findex tex |
| You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} |
| commands, by delineating a region with the @code{@@tex} and @code{@@end |
| tex} commands. (The @code{@@tex} command also causes Info to ignore the |
| region, like the @code{@@iftex} |
| command.)@refill |
| |
| @cindex Mathematical expressions |
| For example, here is a mathematical expression written in |
| plain @TeX{}:@refill |
| |
| @example |
| @@tex |
| $$ \chi^2 = \sum_@{i=1@}^N |
| \left (y_i - (a + b x_i) |
| \over \sigma_i\right)^2 $$ |
| @@end tex |
| @end example |
| |
| @noindent |
| The output of this example will appear only in a printed manual. If |
| you are reading this in Info, you will not see anything after this |
| paragraph. |
| @iftex |
| In a printed manual, the above expression looks like |
| this: |
| @end iftex |
| |
| @tex |
| $$ \chi^2 = \sum_{i=1}^N |
| \left(y_i - (a + b x_i) |
| \over \sigma_i\right)^2 $$ |
| @end tex |
| |
| @node set clear value, , Using Ordinary TeX Commands, Conditionals |
| @comment node-name, next, previous, up |
| @section @code{@@set}, @code{@@clear}, and @code{@@value} |
| |
| You can direct the Texinfo formatting commands to format or ignore parts |
| of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, |
| and @code{@@ifclear} commands.@refill |
| |
| In addition, you can use the @code{@@set @var{flag}} command to set the |
| value of @var{flag} to a string of characters; and use |
| @code{@@value@{@var{flag}@}} to insert that string. You can use |
| @code{@@set}, for example, to set a date and use @code{@@value} to |
| insert the date in several places in the Texinfo file.@refill |
| |
| @menu |
| * ifset ifclear:: Format a region if a flag is set. |
| * value:: Replace a flag with a string. |
| * value Example:: An easy way to update edition information. |
| @end menu |
| |
| @node ifset ifclear, value, set clear value, set clear value |
| @subsection @code{@@ifset} and @code{@@ifclear} |
| |
| @findex ifset |
| When a @var{flag} is set, the Texinfo formatting commands format text |
| between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end |
| ifset} commands. When the @var{flag} is cleared, the Texinfo formatting |
| commands do @emph{not} format the text. |
| |
| Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a |
| @var{flag}; a @dfn{flag} can be any single word. The format for the |
| command looks like this:@refill |
| @findex set |
| |
| @example |
| @@set @var{flag} |
| @end example |
| |
| Write the conditionally formatted text between @code{@@ifset @var{flag}} |
| and @code{@@end ifset} commands, like this:@refill |
| |
| @example |
| @group |
| @@ifset @var{flag} |
| @var{conditional-text} |
| @@end ifset |
| @end group |
| @end example |
| |
| For example, you can create one document that has two variants, such as |
| a manual for a `large' and `small' model:@refill |
| |
| @example |
| You can use this machine to dig up shrubs |
| without hurting them. |
| |
| @@set large |
| |
| @@ifset large |
| It can also dig up fully grown trees. |
| @@end ifset |
| |
| Remember to replant promptly @dots{} |
| @end example |
| |
| @noindent |
| In the example, the formatting commands will format the text between |
| @code{@@ifset large} and @code{@@end ifset} because the @code{large} |
| flag is set.@refill |
| |
| @findex clear |
| Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear}, |
| a flag. Clearing a flag is the opposite of setting a flag. The |
| command looks like this:@refill |
| |
| @example |
| @@clear @var{flag} |
| @end example |
| |
| @noindent |
| Write the command on a line of its own. |
| |
| When @var{flag} is cleared, the Texinfo formatting commands do |
| @emph{not} format the text between @code{@@ifset @var{flag}} and |
| @code{@@end ifset}; that text is ignored and does not appear in either |
| printed or Info output.@refill |
| |
| For example, if you clear the flag of the preceding example by writing |
| an @code{@@clear large} command after the @code{@@set large} command |
| (but before the conditional text), then the Texinfo formatting commands |
| ignore the text between the @code{@@ifset large} and @code{@@end ifset} |
| commands. In the formatted output, that text does not appear; in both |
| printed and Info output, you see only the lines that say, ``You can use |
| this machine to dig up shrubs without hurting them. Remember to replant |
| promptly @dots{}''. |
| |
| @findex ifclear |
| If a flag is cleared with an @code{@@clear @var{flag}} command, then |
| the formatting commands format text between subsequent pairs of |
| @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag |
| is set with @code{@@set @var{flag}}, then the formatting commands do |
| @emph{not} format text between an @code{@@ifclear} and an @code{@@end |
| ifclear} command; rather, they ignore that text. An @code{@@ifclear} |
| command looks like this:@refill |
| |
| @example |
| @@ifclear @var{flag} |
| @end example |
| |
| @need 700 |
| In brief, the commands are:@refill |
| |
| @table @code |
| @item @@set @var{flag} |
| Tell the Texinfo formatting commands that @var{flag} is set.@refill |
| |
| @item @@clear @var{flag} |
| Tell the Texinfo formatting commands that @var{flag} is cleared.@refill |
| |
| @item @@ifset @var{flag} |
| If @var{flag} is set, tell the Texinfo formatting commands to format |
| the text up to the following @code{@@end ifset} command.@refill |
| |
| If @var{flag} is cleared, tell the Texinfo formatting commands to |
| ignore text up to the following @code{@@end ifset} command.@refill |
| |
| @item @@ifclear @var{flag} |
| If @var{flag} is set, tell the Texinfo formatting commands to ignore |
| the text up to the following @code{@@end ifclear} command.@refill |
| |
| If @var{flag} is cleared, tell the Texinfo formatting commands to |
| format the text up to the following @code{@@end ifclear} |
| command.@refill |
| @end table |
| |
| @node value, value Example, ifset ifclear, set clear value |
| @subsection @code{@@value} |
| @findex value |
| |
| You can use the @code{@@set} command to specify a value for a flag, |
| which is expanded by the @code{@@value} command. The value is a string |
| a characters. |
| |
| Write the @code{@@set} command like this: |
| |
| @example |
| @@set foo This is a string. |
| @end example |
| |
| @noindent |
| This sets the value of @code{foo} to ``This is a string.'' |
| |
| The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with |
| the string to which @var{flag} is set.@refill |
| |
| Thus, when @code{foo} is set as shown above, the Texinfo formatters convert |
| |
| @example |
| @group |
| @@value@{foo@} |
| @exdent @r{to} |
| This is a string. |
| @end group |
| @end example |
| |
| You can write an @code{@@value} command within a paragraph; but you |
| must write an @code{@@set} command on a line of its own. |
| |
| If you write the @code{@@set} command like this: |
| |
| @example |
| @@set foo |
| @end example |
| |
| @noindent |
| without specifying a string, the value of @code{foo} is an empty string. |
| |
| If you clear a previously set flag with an @code{@@clear @var{flag}} |
| command, a subsequent @code{@@value@{flag@}} command is invalid and the |
| string is replaced with an error message that says @samp{@{No value for |
| "@var{flag}"@}}. |
| |
| For example, if you set @code{foo} as follows:@refill |
| |
| @example |
| @@set how-much very, very, very |
| @end example |
| |
| @noindent |
| then the formatters transform |
| |
| @example |
| @group |
| It is a @@value@{how-much@} wet day. |
| @exdent @r{into} |
| It is a very, very, very wet day. |
| @end group |
| @end example |
| |
| If you write |
| |
| @example |
| @@clear how-much |
| @end example |
| |
| @noindent |
| then the formatters transform |
| |
| @example |
| @group |
| It is a @@value@{how-much@} wet day. |
| @exdent @r{into} |
| It is a @{No value for "how-much"@} wet day. |
| @end group |
| @end example |
| |
| @node value Example, , value, set clear value |
| @subsection @code{@@value} Example |
| |
| You can use the @code{@@value} command to limit the number of places you |
| need to change when you record an update to a manual. |
| Here is how it is done in @cite{The GNU Make Manual}: |
| |
| @need 1000 |
| @noindent |
| Set the flags: |
| |
| @example |
| @group |
| @@set EDITION 0.35 Beta |
| @@set VERSION 3.63 Beta |
| @@set UPDATED 14 August 1992 |
| @@set UPDATE-MONTH August 1992 |
| @end group |
| @end example |
| |
| @need 750 |
| @noindent |
| Write text for the first @code{@@ifinfo} section, for people reading the |
| Texinfo file: |
| |
| @example |
| @group |
| This is Edition @@value@{EDITION@}, |
| last updated @@value@{UPDATED@}, |
| of @@cite@{The GNU Make Manual@}, |
| for @@code@{make@}, Version @@value@{VERSION@}. |
| @end group |
| @end example |
| |
| @need 1000 |
| @noindent |
| Write text for the title page, for people reading the printed manual: |
| @c List only the month and the year since that looks less fussy on a |
| @c printed cover than a date that lists the day as well. |
| |
| @example |
| @group |
| @@title GNU Make |
| @@subtitle A Program for Directing Recompilation |
| @@subtitle Edition @@value@{EDITION@}, @dots{} |
| @@subtitle @@value@{UPDATE-MONTH@} |
| @end group |
| @end example |
| |
| @noindent |
| (On a printed cover, a date listing the month and the year looks less |
| fussy than a date listing the day as well as the month and year.) |
| |
| @need 750 |
| @noindent |
| Write text for the Top node, for people reading the Info file: |
| |
| @example |
| @group |
| This is Edition @@value@{EDITION@} |
| of the @@cite@{GNU Make Manual@}, |
| last updated @@value@{UPDATED@} |
| for @@code@{make@} Version @@value@{VERSION@}. |
| @end group |
| @end example |
| |
| @need 950 |
| After you format the manual, the text in the first @code{@@ifinfo} |
| section looks like this: |
| |
| @example |
| @group |
| This is Edition 0.35 Beta, last updated 14 August 1992, |
| of `The GNU Make Manual', for `make', Version 3.63 Beta. |
| @end group |
| @end example |
| |
| When you update the manual, change only the values of the flags; you do |
| not need to rewrite the three sections. |
| |
| |
| @node Macros, Format/Print Hardcopy, Conditionals, Top |
| @chapter Macros: Defining New Texinfo Commands |
| @cindex Macros |
| @cindex Defining new Texinfo commands |
| @cindex New Texinfo commands, defining |
| @cindex Texinfo commands, defining new |
| @cindex User-defined Texinfo commands |
| |
| A Texinfo @dfn{macro} allows you to define a new Texinfo command as any |
| sequence of text and/or existing commands (including other macros). The |
| macro can have any number of @dfn{parameters}---text you supply each |
| time you use the macro. (This has nothing to do with the |
| @code{@@defmac} command, which is for documenting macros in the subject |
| of the manual; @pxref{Def Cmd Template}.) |
| |
| @menu |
| * Defining Macros:: Both defining and undefining new commands. |
| * Invoking Macros:: Using a macro, once you've defined it. |
| @end menu |
| |
| |
| @node Defining Macros, Invoking Macros, Macros, Macros |
| @section Defining Macros |
| @cindex Defining macros |
| @cindex Macro definitions |
| |
| @findex macro |
| You use the Texinfo @code{@@macro} command to define a macro. For example: |
| |
| @example |
| @@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@} |
| @var{text} @dots{} \@var{param1}\ @dots{} |
| @@end macro |
| @end example |
| |
| The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to |
| arguments supplied when the macro is subsequently used in the document |
| (see the next section). |
| |
| If a macro needs no parameters, you can define it either with an empty |
| list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro |
| foo}). |
| |
| @cindex Body of a macro |
| @cindex Mutually recursive macros |
| @cindex Recursion, mutual |
| The definition or @dfn{body} of the macro can contain any Texinfo |
| commands, including previously-defined macros. (It is not possible to |
| have mutually recursive Texinfo macros.) In the body, instances of a |
| parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in |
| the example above, are replaced by the corresponding argument from the |
| macro invocation. |
| |
| @findex unmacro |
| @cindex Macros, undefining |
| @cindex Undefining macros |
| You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. |
| It is not an error to undefine a macro that is already undefined. |
| For example: |
| |
| @example |
| @@unmacro foo |
| @end example |
| |
| |
| @node Invoking Macros, , Defining Macros, Macros |
| @section Invoking Macros |
| @cindex Invoking macros |
| @cindex Macro invocation |
| |
| After a macro is defined (see the previous section), you can use |
| (@dfn{invoke}) it in your document like this: |
| |
| @example |
| @@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@} |
| @end example |
| |
| @noindent and the result will be just as if you typed the body of |
| @var{macro-name} at that spot. For example: |
| |
| @example |
| @@macro foo @{p, q@} |
| Together: \p\ & \q\. |
| @@end macro |
| @@foo@{a, b@} |
| @end example |
| |
| @noindent produces: |
| |
| @display |
| Together: a & b. |
| @end display |
| |
| @cindex Backslash, and macros |
| Thus, the arguments and parameters are separated by commas and delimited |
| by braces; any whitespace after (but not before) a comma is ignored. To |
| insert a comma, brace, or backslash in an argument, prepend a backslash, |
| as in |
| |
| @example |
| @@@var{macro-name} @{\\\@{\@}\,@} |
| @end example |
| |
| @noindent |
| which will pass the (almost certainly error-producing) argument |
| @samp{\@{@},} to @var{macro-name}. |
| |
| If the macro is defined to take a single argument, and is invoked |
| without any braces, the entire rest of the line after the macro name is |
| supplied as the argument. For example: |
| |
| @example |
| @@macro bar @{p@} |
| Twice: \p\, \p\. |
| @@end macro |
| @@bar aah |
| @end example |
| |
| @noindent produces: |
| |
| @display |
| Twice: aah, aah. |
| @end display |
| |
| |
| @node Format/Print Hardcopy, Create an Info File, Macros, Top |
| @comment node-name, next, previous, up |
| @chapter Format and Print Hardcopy |
| @cindex Format and print hardcopy |
| @cindex Hardcopy, printing it |
| @cindex Making a printed manual |
| @cindex Sorting indices |
| @cindex Indices, sorting |
| @cindex @TeX{} index sorting |
| @pindex 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.@refill |
| |
| 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.@refill |
| |
| @menu |
| * Use TeX:: Use @TeX{} to format for hardcopy. |
| * Format with tex/texindex:: How to format in a shell. |
| * Format with texi2dvi:: A simpler way to use the shell. |
| * 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 you need to do to 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 European A4 paper. |
| * Cropmarks and Magnification:: How to print marks to indicate the size |
| of pages and how to print scaled up output. |
| @end menu |
| |
| @node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy |
| @ifinfo |
| @heading Use @TeX{} |
| @end ifinfo |
| |
| The typesetting program called @TeX{} is used for formatting a Texinfo |
| file. @TeX{} is a very powerful typesetting program and, if used right, |
| does an exceptionally good job. @xref{Obtaining TeX, , How to Obtain |
| @TeX{}}, for information on how to obtain @TeX{}.@refill |
| |
| The @code{makeinfo}, @code{texinfo-format-region}, 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; see @ref{Create an Info File}.@refill |
| |
| @node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Format using @code{tex} and @code{texindex} |
| @cindex Shell formatting with @code{tex} and @code{texindex} |
| @cindex Formatting with @code{tex} and @code{texindex} |
| @cindex DVI file |
| |
| Format the Texinfo file with the shell command @code{tex} followed by |
| the name of the Texinfo file. This command produces a formatted |
| @sc{dvi} file as well as several auxiliary files containing indices, |
| cross references, etc. The @sc{dvi} file (for @dfn{DeVice Independent} |
| file) can be printed on a wide variety of printers.@refill |
| |
| The @code{tex} formatting command itself does not sort the indices; it |
| writes an output file of unsorted index data. This is a misfeature of |
| @TeX{}. (The @code{texi2dvi} command automatically generates indices; |
| see @ref{Format with texi2dvi, , Format using @code{texi2dvi}}.) To |
| generate a printed index after running the @code{tex} command, you first |
| need a sorted index to work from. The @code{texindex} command sorts |
| indices. (The source file @file{texindex.c} comes as part of the |
| standard GNU distribution and is usually installed when Emacs is |
| installed.)@refill |
| @pindex texindex |
| @ignore |
| Usage: texindex [-k] [-T tempdir] infile [-o outfile] ... |
| |
| Each infile arg can optionally be followed by a `-o outfile' arg; |
| for each infile that is not followed by a -o arg, the infile name with |
| `s' (for `sorted') appended is used for the outfile. |
| |
| -T dir is the directory to put temp files in, instead of /tmp. |
| -k means `keep tempfiles', for debugging. |
| @end ignore |
| |
| The @code{tex} formatting command outputs unsorted index files under |
| names that obey a standard convention. These names are the name of |
| your main input file to the @code{tex} formatting command, with |
| everything after the first period thrown away, and the two letter |
| names of indices added at the end. For example, the raw index output |
| files for the input file @file{foo.texinfo} would be @file{foo.cp}, |
| @file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and |
| @file{foo.ky}. Those are exactly the arguments to give to |
| @code{texindex}.@refill |
| |
| @need 1000 |
| Or else, you can use @samp{??} as ``wild-cards'' and give the command in |
| this form:@refill |
| |
| @example |
| texindex foo.?? |
| @end example |
| |
| @noindent |
| 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.)@refill |
| |
| 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 |
| @code{@@printindex} command knows to look for a file of that name. |
| @code{texindex} does not alter the raw index output file.@refill |
| |
| After you have sorted the indices, you need to rerun the @code{tex} |
| formatting command on the Texinfo file. This regenerates a formatted |
| @sc{dvi} file with up-to-date index entries.@footnote{If you use more |
| than one index and have cross references to an index other than the |
| first, you must run @code{tex} @emph{three times} to get correct output: |
| once to generate raw index data; again (after @code{texindex}) to output |
| the text of the indices and determine their true page numbers; and a |
| third time to output correct page numbers in cross references to them. |
| However, cross references to indices are rare.}@refill |
| |
| To summarize, this is a three step process: |
| |
| @enumerate |
| @item |
| Run the @code{tex} formatting command on the Texinfo file. This |
| generates the formatted @sc{dvi} file as well as the raw index files |
| with two letter extensions.@refill |
| |
| @item |
| Run the shell command @code{texindex} on the raw index files to sort |
| them. This creates the corresponding sorted index files.@refill |
| |
| @item |
| Rerun the @code{tex} formatting command on the Texinfo file. This |
| regenerates a formatted @sc{dvi} file with the index entries in the |
| correct order. This second run also corrects the page numbers for |
| the cross references. (The tables of contents are always correct.)@refill |
| @end enumerate |
| |
| You need not run @code{texindex} each time after you run the |
| @code{tex} formatting. 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 @code{texindex}. This is usually |
| @sc{ok} while you are debugging.@refill |
| |
| @node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Format using @code{texi2dvi} |
| @pindex texi2dvi @r{(shell script)} |
| |
| The @code{texi2dvi} command is a shell script that automatically runs |
| both @code{tex} and @code{texindex} as many times as necessary to |
| produce a @sc{dvi} file with up-to-date, sorted indices. It simplifies |
| the @code{tex}---@code{texindex}---@code{tex} sequence described in the |
| previous section. |
| |
| @need 1000 |
| The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is the |
| shell prompt):@refill |
| |
| @example |
| prompt$ @kbd{texi2dvi @var{filename}@dots{}} |
| @end example |
| |
| @node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Shell Print Using @code{lpr -d} |
| @pindex lpr @r{(@sc{dvi} print command)} |
| |
| You can print a @sc{dvi} file with the @sc{dvi} print command. The |
| precise printing command to use depends on your system; @samp{lpr -d} is |
| common. The @sc{dvi} print command may require a file name without any |
| extension or with a @samp{.dvi} extension.@refill |
| |
| @need 1200 |
| The following commands, for example, sort the indices, format, and |
| print the @cite{Bison Manual} (where @samp{%} is the shell |
| prompt):@refill |
| |
| @example |
| @group |
| % tex bison.texinfo |
| % texindex bison.?? |
| % tex bison.texinfo |
| % lpr -d bison.dvi |
| @end group |
| @end example |
| |
| @noindent |
| (Remember that the shell commands may be different at your site; but |
| these are commonly used versions.)@refill |
| |
| @need 1000 |
| Using the @code{texi2dvi} shell script, you simply need type:@refill |
| |
| @example |
| @group |
| % texi2dvi bison.texinfo |
| % lpr -d bison.dvi |
| @end group |
| @end example |
| |
| @node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section From an Emacs Shell @dots{} |
| @cindex Print, format from Emacs shell |
| @cindex Format, print from Emacs shell |
| @cindex Shell, format, print from |
| @cindex Emacs shell, format, print from |
| @cindex GNU Emacs shell, format, print from |
| |
| You can give formatting and printing commands from a shell within GNU |
| Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this |
| shell, you can format and print the document. @xref{Format/Print |
| Hardcopy, , Format and Print Hardcopy}, for details.@refill |
| |
| You can switch to and from the shell buffer while @code{tex} is |
| running and do other editing. If you are formatting a long document |
| on a slow machine, this can be very convenient.@refill |
| |
| You can also use @code{texi2dvi} from an Emacs shell. For example, |
| here is how to use @code{texi2dvi} to format and print @cite{Using and |
| Porting GNU CC} from a shell within Emacs (where @samp{%} is the shell |
| prompt):@refill |
| |
| @example |
| @group |
| % texi2dvi gcc.texinfo |
| % lpr -d gcc.dvi |
| @end group |
| @end example |
| @ifinfo |
| |
| @xref{Texinfo Mode Printing}, for more information about formatting |
| and printing in Texinfo mode.@refill |
| @end ifinfo |
| |
| @node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy |
| @section Formatting and Printing in Texinfo Mode |
| @cindex Region printing in Texinfo mode |
| @cindex Format and print in Texinfo mode |
| @cindex Print and format in Texinfo mode |
| |
| Texinfo mode provides several predefined key commands for @TeX{} |
| formatting and printing. These include commands for sorting indices, |
| looking at the printer queue, killing the formatting job, and |
| recentering the display of the buffer in which the operations |
| occur.@refill |
| |
| @table @kbd |
| @item C-c C-t C-b |
| @itemx M-x texinfo-tex-buffer |
| Run @code{texi2dvi} on the current buffer.@refill |
| |
| @item C-c C-t C-r |
| @itemx M-x texinfo-tex-region |
| Run @TeX{} on the current region.@refill |
| |
| @item C-c C-t C-i |
| @itemx M-x texinfo-texindex |
| Sort the indices of a Texinfo file formatted with |
| @code{texinfo-tex-region}.@refill |
| |
| @item C-c C-t C-p |
| @itemx M-x texinfo-tex-print |
| Print a @sc{dvi} file that was made with @code{texinfo-tex-region} or |
| @code{texinfo-tex-buffer}.@refill |
| |
| @item C-c C-t C-q |
| @itemx M-x tex-show-print-queue |
| Show the print queue.@refill |
| |
| @item C-c C-t C-d |
| @itemx M-x texinfo-delete-from-print-queue |
| Delete a job from the print queue; you will be prompted for the job |
| number shown by a preceding @kbd{C-c C-t C-q} command |
| (@code{texinfo-show-tex-print-queue}).@refill |
| |
| @item C-c C-t C-k |
| @itemx M-x tex-kill-job |
| Kill the currently running @TeX{} job started by |
| @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other |
| process running in the Texinfo shell buffer.@refill |
| |
| @item C-c C-t C-x |
| @itemx M-x texinfo-quit-job |
| Quit a @TeX{} formatting job that has stopped because of an error by |
| sending an @key{x} to it. When you do this, @TeX{} preserves a record |
| of what it did in a @file{.log} file.@refill |
| |
| @item C-c C-t C-l |
| @itemx M-x tex-recenter-output-buffer |
| Redisplay the shell buffer in which the @TeX{} printing and formatting |
| commands are run to show its most recent output.@refill |
| @end table |
| |
| @need 1000 |
| Thus, the usual sequence of commands for formatting a buffer is as |
| follows (with comments to the right):@refill |
| |
| @example |
| @group |
| C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} |
| C-c C-t C-p @r{Print the @sc{dvi} file.} |
| C-c C-t C-q @r{Display the printer queue.} |
| @end group |
| @end example |
| |
| The Texinfo mode @TeX{} formatting commands start a subshell in Emacs |
| called the @file{*tex-shell*}. The @code{texinfo-tex-command}, |
| @code{texinfo-texindex-command}, and @code{tex-dvi-print-command} |
| commands are all run in this shell. |
| |
| You can watch the commands operate in the @samp{*tex-shell*} buffer, |
| and you can switch to and from and use the @samp{*tex-shell*} buffer |
| as you would any other shell buffer.@refill |
| |
| @need 1500 |
| The formatting and print commands depend on the values of several variables. |
| The default values are:@refill |
| |
| @example |
| @group |
| @r{Variable} @r{Default value} |
| |
| texinfo-texi2dvi-command "texi2dvi" |
| texinfo-tex-command "tex" |
| texinfo-texindex-command "texindex" |
| texinfo-delete-from-print-queue-command "lprm" |
| texinfo-tex-trailer "@@bye" |
| tex-start-of-header "%**start" |
| tex-end-of-header "%**end" |
| tex-dvi-print-command "lpr -d" |
| tex-show-queue-command "lpq" |
| @end group |
| @end example |
| |
| You can change the values of these variables with the @kbd{M-x |
| edit-options} command (@pxref{Edit Options, , Editing Variable Values, |
| emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command |
| (@pxref{Examining, , Examining and Setting Variables, emacs, The GNU |
| Emacs Manual}), or with your @file{.emacs} initialization file |
| (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill |
| |
| @node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Using the Local Variables List |
| @cindex Local variables |
| @cindex Compile command for formatting |
| @cindex Format with the compile command |
| |
| Yet another way to apply the @TeX{} formatting command to a Texinfo file |
| is to put that command in a @dfn{local variables list} at the end of the |
| Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} |
| commands as a @code{compile-command} and have Emacs run it by typing |
| @kbd{M-x compile}. This creates a special shell called the |
| @file{*compilation*} buffer in which Emacs runs the compile command. |
| For example, at the end of the @file{gdb.texinfo} file, after the |
| @code{@@bye}, you could put the following:@refill |
| |
| @example |
| @group |
| @@c Local Variables: |
| @@c compile-command: "texi2dvi gdb.texinfo" |
| @@c End: |
| @end group |
| @end example |
| |
| @noindent |
| This technique is most often used by programmers who also compile programs |
| this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill |
| |
| @node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section @TeX{} Formatting Requirements Summary |
| @cindex Requirements for formatting |
| @cindex Formatting requirements |
| |
| Every Texinfo file that is to be input to @TeX{} must begin with a |
| @code{\input} command and must contain an @code{@@setfilename} command and |
| an @code{@@settitle} command:@refill |
| |
| @example |
| \input texinfo |
| @@setfilename @var{arg-not-used-by-@TeX{}} |
| @@settitle @var{name-of-manual} |
| @end example |
| |
| @noindent |
| The first command instructs @TeX{} to load the macros it needs to |
| process a Texinfo file, the second command opens auxiliary files, and |
| the third specifies the title of printed manual. |
| |
| @need 1000 |
| Every Texinfo file must end with a line that terminates @TeX{} |
| processing and forces out unfinished pages:@refill |
| |
| @example |
| @@bye |
| @end example |
| |
| Strictly speaking, these four lines are all a Texinfo file needs for |
| @TeX{}, besides the body. (The @code{@@setfilename} line is the only |
| line that a Texinfo file needs for Info formatting.)@refill |
| |
| Usually, the file's first line contains an @samp{@@c -*-texinfo-*-} |
| comment that causes Emacs to switch to Texinfo mode when you edit the |
| file. In addition, the beginning usually includes an |
| @code{@@setchapternewpage} command, a title page, a copyright page, and |
| permissions. Besides an @code{@@bye}, the end of a file usually |
| includes indices and a table of contents.@refill |
| |
| @iftex |
| For more information, see |
| @ref{setchapternewpage, , @code{@@setchapternewpage}}, |
| @ref{Headings, ,Page Headings}, |
| @ref{Titlepage & Copyright Page}, |
| @ref{Printing Indices & Menus}, and |
| @ref{Contents}. |
| @end iftex |
| @noindent |
| @ifinfo |
| For more information, see@* |
| @ref{setchapternewpage, , @code{@@setchapternewpage}},@* |
| @ref{Headings, ,Page Headings},@* |
| @ref{Titlepage & Copyright Page},@* |
| @ref{Printing Indices & Menus}, and@* |
| @ref{Contents}. |
| @end ifinfo |
| |
| @node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Preparing to Use @TeX{} |
| @cindex Preparing to use @TeX{} |
| @cindex @TeX{} input initialization |
| @cindex @code{TEXINPUTS} environment variable |
| @vindex TEXINPUTS |
| @cindex @b{.profile} initialization file |
| @cindex @b{.cshrc} initialization file |
| @cindex Initialization file for @TeX{} input |
| |
| @TeX{} needs to know where to find the @file{texinfo.tex} file |
| that you have told it to input with the @samp{\input texinfo} command |
| at the beginning of the first line. The @file{texinfo.tex} file tells |
| @TeX{} how to handle @@-commands. (@file{texinfo.tex} is |
| included in the standard GNU distributions.)@refill |
| |
| Usually, the @file{texinfo.tex} file is put in the default directory |
| that contains @TeX{} macros (the @file{/usr/lib/tex/macros} |
| directory) when GNU Emacs or other GNU software is installed. |
| In this case, @TeX{} will |
| find the file and you do not need to do anything special. |
| Alternatively, you can put @file{texinfo.tex} in the directory in |
| which the Texinfo source file is located, and @TeX{} will find it |
| there.@refill |
| |
| However, you may want to specify the location of the @code{\input} file |
| yourself. One way to do this is to write the complete path for the file |
| after the @code{\input} command. Another way is to set the |
| @code{TEXINPUTS} environment variable in your @file{.cshrc} or |
| @file{.profile} file. The @code{TEXINPUTS} environment variable will tell |
| @TeX{} where to find the @file{texinfo.tex} file and any other file that |
| you might want @TeX{} to use.@refill |
| |
| Whether you use a @file{.cshrc} or @file{.profile} file depends on |
| whether you use @code{csh}, @code{sh}, or @code{bash} for your shell |
| command interpreter. When you use @code{csh}, it looks to the |
| @file{.cshrc} file for initialization information, and when you use |
| @code{sh} or @code{bash}, it looks to the @file{.profile} file.@refill |
| |
| @need 1000 |
| In a @file{.cshrc} file, you could use the following @code{csh} command |
| sequence:@refill |
| |
| @example |
| setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros |
| @end example |
| |
| @need 1000 |
| In a @file{.profile} file, you could use the following @code{sh} command |
| sequence: |
| |
| @example |
| @group |
| TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros |
| export TEXINPUTS |
| @end group |
| @end example |
| |
| @noindent |
| This would cause @TeX{} to look for @file{\input} file first in the current |
| directory, indicated by the @samp{.}, then in a hypothetical user's |
| @file{me/mylib} directory, and finally in the system library.@refill |
| |
| @node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Overfull ``hboxes'' |
| @cindex Overfull @samp{hboxes} |
| @cindex @samp{hboxes}, overfull |
| @cindex Final output |
| |
| @TeX{} is sometimes unable to typeset a line without extending it into |
| the right margin. This can occur when @TeX{} comes upon what it |
| interprets as a long word that it cannot hyphenate, such as an |
| electronic mail network address or a very long title. When this |
| happens, @TeX{} prints an error message like this:@refill |
| |
| @example |
| Overfull \hbox (20.76302pt too wide) |
| @end example |
| |
| @noindent |
| (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. |
| The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill |
| |
| @TeX{} also provides the line number in the Texinfo source file and |
| the text of the offending line, which is marked at all the places that |
| @TeX{} knows how to hyphenate words. |
| @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, |
| for more information about typesetting errors.@refill |
| |
| If the Texinfo file has an overfull hbox, you can rewrite the sentence |
| so the overfull hbox does not occur, or you can decide to leave it. A |
| small excursion into the right margin often does not matter and may not |
| even be noticeable.@refill |
| |
| @cindex Black rectangle in hardcopy |
| @cindex Rectangle, ugly, black in hardcopy |
| However, unless told otherwise, @TeX{} will print a large, ugly, black |
| rectangle beside the line that contains the overfull hbox. This is so |
| you will notice the location of the problem if you are correcting a |
| draft.@refill |
| |
| @need 1000 |
| @findex finalout |
| To prevent such a monstrosity from marring your final printout, write |
| the following in the beginning of the Texinfo file on a line of its own, |
| before the @code{@@titlepage} command:@refill |
| |
| @example |
| @@finalout |
| @end example |
| |
| @node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Printing ``Small'' Books |
| @findex smallbook |
| @cindex Small book size |
| @cindex Book, printing small |
| @cindex Page sizes for books |
| @cindex Size of printed book |
| |
| By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch |
| format. However, you can direct @TeX{} to typeset a document in a 7 by |
| 9.25 inch format that is suitable for bound books by inserting the |
| following command on a line by itself at the beginning of the Texinfo |
| file, before the title page:@refill |
| |
| @example |
| @@smallbook |
| @end example |
| |
| @noindent |
| (Since regular sized books are often about 7 by 9.25 inches, this |
| command might better have been called the @code{@@regularbooksize} |
| command, but it came to be called the @code{@@smallbook} command by |
| comparison to the 8.5 by 11 inch format.)@refill |
| |
| If you write the @code{@@smallbook} command between the |
| start-of-header and end-of-header lines, the Texinfo mode @TeX{} |
| region formatting command, @code{texinfo-tex-region}, will format the |
| region in ``small'' book size (@pxref{Start of Header}).@refill |
| |
| The Free Software Foundation distributes printed copies of @cite{The GNU |
| Emacs Manual} and other manuals in the ``small'' book size. |
| @xref{smallexample & smalllisp, , @code{@@smallexample} and |
| @code{@@smalllisp}}, for information about commands that make it easier |
| to produce examples for a smaller manual.@refill |
| |
| @node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Printing on A4 Paper |
| @cindex A4 paper, printing on |
| @cindex Paper size, European A4 |
| @cindex European A4 paper |
| @findex afourpaper |
| |
| You can tell @TeX{} to typeset a document for printing on European size |
| A4 paper with the @code{@@afourpaper} command. Write the command on a |
| line by itself between @code{@@iftex} and @code{@@end iftex} lines near |
| the beginning of the Texinfo file, before the title page:@refill |
| |
| For example, this is how you would write the header for this manual:@refill |
| |
| @example |
| @group |
| \input texinfo @@c -*-texinfo-*- |
| @@c %**start of header |
| @@setfilename texinfo |
| @@settitle Texinfo |
| @@syncodeindex vr fn |
| @@iftex |
| @@afourpaper |
| @@end iftex |
| @@c %**end of header |
| @end group |
| @end example |
| |
| @node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy |
| @comment node-name, next, previous, up |
| @section Cropmarks and Magnification |
| |
| @findex cropmarks |
| @cindex Cropmarks for printing |
| @cindex Printing cropmarks |
| You can attempt to direct @TeX{} to print cropmarks at the corners of |
| pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} |
| command on a line by itself between @code{@@iftex} and @code{@@end |
| iftex} lines near the beginning of the Texinfo file, before the title |
| page, like this:@refill |
| |
| @example |
| @group |
| @@iftex |
| @@cropmarks |
| @@end iftex |
| @end group |
| @end example |
| |
| This command is mainly for printers that typeset several pages on one |
| sheet of film; but you can attempt to use it to mark the corners of a |
| book set to 7 by 9.25 inches with the @code{@@smallbook} command. |
| (Printers will not produce cropmarks for regular sized output that is |
| printed on regular sized paper.) Since different printing machines work |
| in different ways, you should explore the use of this command with a |
| spirit of adventure. You may have to redefine the command in the |
| @file{texinfo.tex} definitions file.@refill |
| |
| @findex mag @r{(@TeX{} command)} |
| @cindex Magnified printing |
| @cindex Larger or smaller pages |
| You can attempt to direct @TeX{} to typeset pages larger or smaller than |
| usual with the @code{\mag} @TeX{} command. Everything that is typeset |
| is scaled proportionally larger or smaller. (@code{\mag} stands for |
| ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a |
| plain @TeX{} command that is prefixed with a backslash. You have to |
| write this command between @code{@@tex} and @code{@@end tex} |
| (@pxref{Using Ordinary TeX Commands, , Using Ordinary @TeX{} |
| Commands}).@refill |
| |
| Follow the @code{\mag} command with an @samp{=} and then a number that |
| is 1000 times the magnification you desire. For example, to print pages |
| at 1.2 normal size, write the following near the beginning of the |
| Texinfo file, before the title page:@refill |
| |
| @example |
| @group |
| @@tex |
| \mag=1200 |
| @@end tex |
| @end group |
| @end example |
| |
| With some printing technologies, you can print normal-sized copies that |
| look better than usual by using a larger-than-normal master.@refill |
| |
| Depending on your system, @code{\mag} may not work or may work only at |
| certain magnifications. Be prepared to experiment.@refill |
| |
| @node Create an Info File, Install an Info File, Format/Print Hardcopy, Top |
| @comment node-name, next, previous, up |
| @chapter Creating an Info File |
| @cindex Creating an Info file |
| @cindex Info, creating an on-line file |
| @cindex Formatting a file for Info |
| |
| @code{makeinfo} is a utility that converts a Texinfo file into an Info |
| file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are |
| GNU Emacs functions that do the same.@refill |
| |
| A Texinfo file must possess an @code{@@setfilename} line near its |
| beginning, otherwise the Info formatting commands will fail.@refill |
| |
| For information on installing the Info file in the Info system, see |
| @ref{Install an Info File}.@refill |
| |
| @menu |
| * makeinfo advantages:: @code{makeinfo} provides better error checking. |
| * Invoking makeinfo:: How to run @code{makeinfo} from a shell. |
| * makeinfo options:: Specify fill-column and other options. |
| * Pointer Validation:: How to check that pointers point somewhere. |
| * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. |
| * texinfo-format commands:: Two Info formatting commands written |
| in Emacs Lisp are an alternative |
| to @code{makeinfo}. |
| * Batch Formatting:: How to format for Info in Emacs Batch mode. |
| * Tag and Split Files:: How tagged and split files help Info |
| to run better. |
| @end menu |
| |
| @node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File |
| @ifinfo |
| @heading @code{makeinfo} Preferred |
| @end ifinfo |
| |
| The @code{makeinfo} utility creates an Info file from a Texinfo source |
| file more quickly than either of the Emacs formatting commands and |
| provides better error messages. We recommend it. @code{makeinfo} is a |
| C program that is independent of Emacs. You do not need to run Emacs to |
| use @code{makeinfo}, which means you can use @code{makeinfo} on machines |
| that are too small to run Emacs. You can run @code{makeinfo} in |
| any one of three ways: from an operating system shell, from a shell |
| inside Emacs, or by typing a key command in Texinfo mode in Emacs. |
| @refill |
| |
| The @code{texinfo-format-region} and the @code{texinfo-format-buffer} |
| commands are useful if you cannot run @code{makeinfo}. Also, in some |
| circumstances, they format short regions or buffers more quickly than |
| @code{makeinfo}.@refill |
| |
| @node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File |
| @section Running @code{makeinfo} from a Shell |
| |
| To create an Info file from a Texinfo file, type @code{makeinfo} |
| followed by the name of the Texinfo file. Thus, to create the Info |
| file for Bison, type the following at the shell prompt (where @samp{%} |
| is the prompt):@refill |
| |
| @example |
| % makeinfo bison.texinfo |
| @end example |
| |
| (You can run a shell inside Emacs by typing @kbd{M-x |
| shell}.)@refill |
| |
| @ifinfo |
| Sometimes you will want to specify options. For example, if you wish |
| to discover which version of @code{makeinfo} you are using, |
| type:@refill |
| |
| @example |
| % makeinfo --version |
| @end example |
| |
| @xref{makeinfo options}, for more information. |
| @end ifinfo |
| |
| @node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File |
| @comment node-name, next, previous, up |
| @section Options for @code{makeinfo} |
| @cindex @code{makeinfo} options |
| @cindex Options for @code{makeinfo} |
| |
| The @code{makeinfo} command takes a number of options. Most often, |
| options are used to set the value of the fill column and specify the |
| footnote style. Each command line option is a word preceded by |
| @samp{--}@footnote{@samp{--} has replaced @samp{+}, the old introductory |
| character, to maintain POSIX.2 compatibility without losing long-named |
| options.} or a letter preceded by @samp{-}. You can use abbreviations |
| for the option names as long as they are unique.@refill |
| |
| For example, you could use the following command to create an Info |
| file for @file{bison.texinfo} in which each line is filled to only 68 |
| columns (where @samp{%} is the prompt):@refill |
| |
| @example |
| % makeinfo --fill-column=68 bison.texinfo |
| @end example |
| |
| You can write two or more options in sequence, like this:@refill |
| |
| @example |
| % makeinfo --no-split --fill-column=70 @dots{} |
| @end example |
| |
| @noindent |
| This would keep the Info file together as one possibly very long |
| file and would also set the fill column to 70.@refill |
| |
| @iftex |
| If you wish to discover which version of @code{makeinfo} |
| you are using, type:@refill |
| |
| @example |
| % makeinfo --version |
| @end example |
| @end iftex |
| |
| The options are:@refill |
| |
| @need 100 |
| @table @code |
| @item -D @var{var} |
| Cause @var{var} to be defined. This is equivalent to |
| @code{@@set @var{var}} in the Texinfo file. |
| |
| @need 150 |
| @item --error-limit @var{limit} |
| Set the maximum number of errors that @code{makeinfo} will report |
| before exiting (on the assumption that continuing would be useless). |
| The default number of errors that can be reported before |
| @code{makeinfo} gives up is 100.@refill |
| |
| @need 150 |
| @item --fill-column @var{width} |
| Specify the maximum number of columns in a line; this is the right-hand |
| edge of a line. Paragraphs that are filled will be filled to this |
| width. (Filling is the process of breaking up and connecting lines so |
| that lines are the same length as or shorter than the number specified |
| as the fill column. Lines are broken between words.) The default value |
| for @code{fill-column} is 72. |
| @refill |
| |
| @item --footnote-style @var{style} |
| Set the footnote style to @var{style}, either @samp{end} for the end |
| node style or @samp{separate} for the separate node style. The value |
| set by this option overrides the value set in a Texinfo file by an |
| @code{@@footnotestyle} command. When the footnote style is |
| @samp{separate}, @code{makeinfo} makes a new node containing the |
| footnotes found in the current node. When the footnote style is |
| @samp{end}, @code{makeinfo} places the footnote references at the end |
| of the current node.@refill |
| |
| @need 150 |
| @item -I @var{dir} |
| Add @code{dir} to the directory search list for finding files that are |
| included using the @code{@@include} command. By default, |
| @code{makeinfo} searches only the current directory. |
| |
| @need 150 |
| @item --no-headers |
| Do not include menus or node lines in the output. This results in an |
| @sc{ascii} file that you cannot read in Info since it does not contain |
| the requisite nodes or menus; but you can print such a file in a |
| single, typewriter-like font and produce acceptable output. |
| |
| @need 150 |
| @item --no-split |
| Suppress the splitting stage of @code{makeinfo}. Normally, large |
| output files (where the size is greater than 70k bytes) are split into |
| smaller subfiles, each one approximately 50k bytes. If you specify |
| @samp{--no-split}, @code{makeinfo} will not split up the output |
| file.@refill |
| |
| @need 100 |
| @item --no-pointer-validate |
| @item --no-validate |
| Suppress the pointer-validation phase of @code{makeinfo}. Normally, |
| after a Texinfo file is processed, some consistency checks are made to |
| ensure that cross references can be resolved, etc. |
| @xref{Pointer Validation}.@refill |
| |
| @need 150 |
| @item --no-warn |
| Suppress the output of warning messages. This does @emph{not} |
| suppress the output of error messages, only warnings. You might |
| want this if the file you are creating has examples of Texinfo cross |
| references within it, and the nodes that are referenced do not actually |
| exist.@refill |
| |
| @item --no-number-footnotes |
| Suppress automatic footnote numbering. By default, @code{makeinfo} |
| numbers each footnote sequentially in a single node, resetting the |
| current footnote number to 1 at the start of each node. |
| |
| @need 150 |
| @item --output @var{file} |
| @itemx -o @var{file} |
| Specify that the output should be directed to @var{file} and not to the |
| file name specified in the @code{@@setfilename} command found in the Texinfo |
| source. @var{file} can be the special token @samp{-}, which specifies |
| standard output. |
| |
| @need 150 |
| @item --paragraph-indent @var{indent} |
| Set the paragraph indentation style to @var{indent}. The value set by |
| this option overrides the value set in a Texinfo file by an |
| @code{@@paragraphindent} command. The value of @var{indent} is |
| interpreted as follows:@refill |
| |
| @itemize @bullet |
| @item |
| If the value of @var{indent} is @samp{asis}, do not change the |
| existing indentation at the starts of paragraphs.@refill |
| |
| @item |
| If the value of @var{indent} is zero, delete any existing |
| indentation.@refill |
| |
| @item |
| If the value of @var{indent} is greater than zero, indent each |
| paragraph by that number of spaces.@refill |
| @end itemize |
| |
| @need 100 |
| @item --reference-limit @var{limit} |
| Set the value of the number of references to a node that |
| @code{makeinfo} will make without reporting a warning. If a node has more |
| than this number of references in it, @code{makeinfo} will make the |
| references but also report a warning.@refill |
| |
| @need 150 |
| @item -U @var{var} |
| Cause @var{var} to be undefined. This is equivalent to |
| @code{@@clear @var{var}} in the Texinfo file. |
| |
| @need 100 |
| @item --verbose |
| Cause @code{makeinfo} to display messages saying what it is doing. |
| Normally, @code{makeinfo} only outputs messages if there are errors or |
| warnings.@refill |
| |
| @need 100 |
| @item --version |
| Report the version number of this copy of @code{makeinfo}.@refill |
| @end table |
| |
| @node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File |
| @section Pointer Validation |
| @cindex Pointer validation with @code{makeinfo} |
| @cindex Validation of pointers |
| |
| If you do not suppress pointer-validation, @code{makeinfo} will check |
| the validity of the final Info file. Mostly, this means ensuring that |
| nodes you have referenced really exist. Here is a complete list of what |
| is checked:@refill |
| |
| @enumerate |
| @item |
| If a `Next', `Previous', or `Up' node reference is a reference to a |
| node in the current file and is not an external reference such as to |
| @file{(dir)}, then the referenced node must exist.@refill |
| |
| @item |
| In every node, if the `Previous' node is different from the `Up' node, |
| then the `Previous' node must also be pointed to by a `Next' node.@refill |
| |
| @item |
| Every node except the `Top' node must have an `Up' pointer.@refill |
| |
| @item |
| The node referenced by an `Up' pointer must contain a reference to the |
| current node in some manner other than through a `Next' reference. |
| This includes menu entries and cross references.@refill |
| |
| @item |
| If the `Next' reference of a node is not the same as the `Next' reference |
| of the `Up' reference, then the node referenced by the `Next' pointer |
| must have a `Previous' pointer that points back to the current node. |
| This rule allows the last node in a section to point to the first node |
| of the next chapter.@refill |
| @end enumerate |
| |
| @node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File |
| @section Running @code{makeinfo} inside Emacs |
| @cindex Running @code{makeinfo} in Emacs |
| @cindex @code{makeinfo} inside Emacs |
| @cindex Shell, running @code{makeinfo} in |
| |
| You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the |
| @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In |
| Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c |
| C-m C-b} by default.@refill |
| |
| @table @kbd |
| @item C-c C-m C-r |
| @itemx M-x makeinfo-region |
| Format the current region for Info.@refill |
| @findex makeinfo-region |
| |
| @item C-c C-m C-b |
| @itemx M-x makeinfo-buffer |
| Format the current buffer for Info.@refill |
| @findex makeinfo-buffer |
| @end table |
| |
| When you invoke either @code{makeinfo-region} or |
| @code{makeinfo-buffer}, Emacs prompts for a file name, offering the |
| name of the visited file as the default. You can edit the default |
| file name in the minibuffer if you wish, before typing @key{RET} to |
| start the @code{makeinfo} process.@refill |
| |
| The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands |
| run the @code{makeinfo} program in a temporary shell buffer. If |
| @code{makeinfo} finds any errors, Emacs displays the error messages in |
| the temporary buffer.@refill |
| |
| @cindex Errors, parsing |
| @cindex Parsing errors |
| @findex next-error |
| You can parse the error messages by typing @kbd{C-x `} |
| (@code{next-error}). This causes Emacs to go to and position the |
| cursor on the line in the Texinfo source that @code{makeinfo} thinks |
| caused the error. @xref{Compilation, , Running @code{make} or |
| Compilers Generally, emacs, The GNU Emacs Manual}, for more |
| information about using the @code{next-error} command.@refill |
| |
| In addition, you can kill the shell in which the @code{makeinfo} |
| command is running or make the shell buffer display its most recent |
| output.@refill |
| |
| @table @kbd |
| @item C-c C-m C-k |
| @itemx M-x makeinfo-kill-job |
| @findex makeinfo-kill-job |
| Kill the current running @code{makeinfo} job created by |
| @code{makeinfo-region} or @code{makeinfo-buffer}.@refill |
| |
| @item C-c C-m C-l |
| @itemx M-x makeinfo-recenter-output-buffer |
| @findex makeinfo-recenter-output-buffer |
| Redisplay the @code{makeinfo} shell buffer to display its most recent |
| output.@refill |
| @end table |
| |
| @noindent |
| (Note that the parallel commands for killing and recentering a @TeX{} |
| job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode |
| Printing}.)@refill |
| |
| You can specify options for @code{makeinfo} by setting the |
| @code{makeinfo-options} variable with either the @kbd{M-x |
| edit-options} or the @kbd{M-x set-variable} command, or by setting the |
| variable in your @file{.emacs} initialization file.@refill |
| |
| For example, you could write the following in your @file{.emacs} file:@refill |
| |
| @example |
| @group |
| (setq makeinfo-options |
| "--paragraph-indent=0 --no-split |
| --fill-column=70 --verbose") |
| @end group |
| @end example |
| |
| @c If you write these three cross references using xref, you see |
| @c three references to the same named manual, which looks strange. |
| @iftex |
| For more information, see @ref{makeinfo options, , Options for |
| @code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and |
| Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs |
| Manual}. |
| @end iftex |
| @noindent |
| @ifinfo |
| For more information, see@* |
| @ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* |
| @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* |
| @ref{Init File, , , emacs, The GNU Emacs Manual}, and@* |
| @ref{makeinfo options, , Options for @code{makeinfo}}. |
| @end ifinfo |
| |
| @node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File |
| @comment node-name, next, previous, up |
| @section The @code{texinfo-format@dots{}} Commands |
| @findex texinfo-format-region |
| @findex texinfo-format-buffer |
| |
| In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo |
| file with the @code{texinfo-format-region} command. This formats the |
| current region and displays the formatted text in a temporary buffer |
| called @samp{*Info Region*}.@refill |
| |
| Similarly, you can format a buffer with the |
| @code{texinfo-format-buffer} command. This command creates a new |
| buffer and generates the Info file in it. Typing @kbd{C-x C-s} will |
| save the Info file under the name specified by the |
| @code{@@setfilename} line which must be near the beginning of the |
| Texinfo file.@refill |
| |
| @table @kbd |
| @item C-c C-e C-r |
| @itemx @code{texinfo-format-region} |
| Format the current region for Info. |
| @findex texinfo-format-region |
| |
| @item C-c C-e C-b |
| @itemx @code{texinfo-format-buffer} |
| Format the current buffer for Info. |
| @findex texinfo-format-buffer |
| @end table |
| |
| The @code{texinfo-format-region} and @code{texinfo-format-buffer} |
| commands provide you with some error checking, and other functions can |
| provide you with further help in finding formatting errors. These |
| procedures are described in an appendix; see @ref{Catching Mistakes}. |
| However, the @code{makeinfo} program is often faster and |
| provides better error checking (@pxref{makeinfo in Emacs}).@refill |
| |
| @node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File |
| @comment node-name, next, previous, up |
| @section Batch Formatting |
| @cindex Batch formatting for Info |
| @cindex Info batch formatting |
| |
| You can format Texinfo files for Info using @code{batch-texinfo-format} |
| and Emacs Batch mode. You can run Emacs in Batch mode from any shell, |
| including a shell inside of Emacs. (@xref{Command Switches, , Command |
| Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill |
| |
| Here is the command to format all the files that end in @file{.texinfo} |
| in the current directory (where @samp{%} is the shell prompt):@refill |
| |
| @example |
| % emacs -batch -funcall batch-texinfo-format *.texinfo |
| @end example |
| |
| @noindent |
| Emacs processes all the files listed on the command line, even if an |
| error occurs while attempting to format some of them.@refill |
| |
| Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; |
| it is not interactive. It kills the Batch mode Emacs on completion.@refill |
| |
| @code{batch-texinfo-format} is convenient if you lack @code{makeinfo} |
| and want to format several Texinfo files at once. When you use Batch |
| mode, you create a new Emacs process. This frees your current Emacs, so |
| you can continue working in it. (When you run |
| @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot |
| use that Emacs for anything else until the command finishes.)@refill |
| |
| @node Tag and Split Files, , Batch Formatting, Create an Info File |
| @comment node-name, next, previous, up |
| @section Tag Files and Split Files |
| @cindex Making a tag table automatically |
| @cindex Tag table, making automatically |
| |
| If a Texinfo file has more than 30,000 bytes, |
| @code{texinfo-format-buffer} automatically creates a tag table |
| for its Info file; @code{makeinfo} always creates a tag table. With |
| a @dfn{tag table}, Info can jump to new nodes more quickly than it can |
| otherwise.@refill |
| |
| @cindex Indirect subfiles |
| In addition, if the Texinfo file contains more than about 70,000 |
| bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the |
| large Info file into shorter @dfn{indirect} subfiles of about 50,000 |
| bytes each. Big files are split into smaller files so that Emacs does |
| not need to make a large buffer to hold the whole of a large Info |
| file; instead, Emacs allocates just enough memory for the small, split |
| off file that is needed at the time. This way, Emacs avoids wasting |
| memory when you run Info. (Before splitting was implemented, Info |
| files were always kept short and @dfn{include files} were designed as |
| a way to create a single, large printed manual out of the smaller Info |
| files. @xref{Include Files}, for more information. Include files are |
| still used for very large documents, such as @cite{The Emacs Lisp |
| Reference Manual}, in which each chapter is a separate file.)@refill |
| |
| When a file is split, Info itself makes use of a shortened version of |
| the original file that contains just the tag table and references to |
| the files that were split off. The split off files are called |
| @dfn{indirect} files.@refill |
| |
| The split off files have names that are created by appending @w{@samp{-1}}, |
| @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the |
| @code{@@setfilename} command. The shortened version of the original file |
| continues to have the name specified by @code{@@setfilename}.@refill |
| |
| At one stage in writing this document, for example, the Info file was saved |
| as @file{test-texinfo} and that file looked like this:@refill |
| |
| @example |
| @group |
| Info file: test-texinfo, -*-Text-*- |
| produced by texinfo-format-buffer |
| from file: new-texinfo-manual.texinfo |
| |
| ^_ |
| Indirect: |
| test-texinfo-1: 102 |
| test-texinfo-2: 50422 |
| @end group |
| @group |
| test-texinfo-3: 101300 |
| ^_^L |
| Tag table: |
| (Indirect) |
| Node: overview^?104 |
| Node: info file^?1271 |
| @end group |
| @group |
| Node: printed manual^?4853 |
| Node: conventions^?6855 |
| @dots{} |
| @end group |
| @end example |
| |
| @noindent |
| (But @file{test-texinfo} had far more nodes than are shown here.) Each of |
| the split off, indirect files, @file{test-texinfo-1}, |
| @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file |
| after the line that says @samp{Indirect:}. The tag table is listed after |
| the line that says @samp{Tag table:}. @refill |
| |
| In the list of indirect files, the number following the file name |
| records the cumulative number of bytes in the preceding indirect files, |
| not counting the file list itself, the tag table, or the permissions |
| text in each file. In the tag table, the number following the node name |
| records the location of the beginning of the node, in bytes from the |
| beginning.@refill |
| |
| If you are using @code{texinfo-format-buffer} to create Info files, |
| you may want to run the @code{Info-validate} command. (The |
| @code{makeinfo} command does such a good job on its own, you do not |
| need @code{Info-validate}.) However, you cannot run the @kbd{M-x |
| Info-validate} node-checking command on indirect files. For |
| information on how to prevent files from being split and how to |
| validate the structure of the nodes, see @ref{Using |
| Info-validate}.@refill |
| |
| |
| @node Install an Info File, Command List, Create an Info File, Top |
| @comment node-name, next, previous, up |
| @chapter Installing an Info File |
| @cindex Installing an Info file |
| @cindex Info file installation |
| @cindex @file{dir} directory for Info installation |
| |
| Info files are usually kept in the @file{info} directory. You can read |
| Info files using the standalone Info program or the Info reader built |
| into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) |
| |
| @menu |
| * Directory file:: The top level menu for all Info files. |
| * New Info File:: Listing a new info file. |
| * Other Info Directories:: How to specify Info files that are |
| located in other directories. |
| * Installing Dir Entries:: How to specify what menu entry to add |
| to the Info directory. |
| * Invoking install-info:: @code{install-info} options. |
| @end menu |
| |
| @node Directory file, New Info File, Install an Info File, Install an Info File |
| @ifinfo |
| @heading The @file{dir} File |
| @end ifinfo |
| |
| For Info to work, the @file{info} directory must contain a file that |
| serves as a top level directory for the Info system. By convention, |
| this file is called @file{dir}. (You can find the location of this file |
| within Emacs by typing @kbd{C-h i} to enter Info and then typing |
| @kbd{C-x C-f} to see the pathname to the @file{info} directory.) |
| |
| The @file{dir} file is itself an Info file. It contains the top level |
| menu for all the Info files in the system. The menu looks like |
| this:@refill |
| |
| @example |
| @group |
| * Menu: |
| |
| * Info: (info). Documentation browsing system. |
| * Emacs: (emacs). The extensible, self-documenting |
| text editor. |
| * Texinfo: (texinfo). With one source file, make |
| either a printed manual using |
| TeX or an Info file. |
| @dots{} |
| @end group |
| @end example |
| |
| Each of these menu entries points to the `Top' node of the Info file |
| that is named in parentheses. (The menu entry does not need to |
| specify the `Top' node, since Info goes to the `Top' node if no node |
| name is mentioned. @xref{Other Info Files, , Nodes in Other Info |
| Files}.)@refill |
| |
| Thus, the @samp{Info} entry points to the `Top' node of the |
| @file{info} file and the @samp{Emacs} entry points to the `Top' node |
| of the @file{emacs} file.@refill |
| |
| In each of the Info files, the `Up' pointer of the `Top' node refers |
| back to the @code{dir} file. For example, the line for the `Top' |
| node of the Emacs manual looks like this in Info:@refill |
| |
| @example |
| File: emacs Node: Top, Up: (DIR), Next: Distrib |
| @end example |
| |
| @noindent |
| (Note that in this case, the @file{dir} file name is written in upper |
| case letters---it can be written in either upper or lower case. Info |
| has a feature that it will change the case of the file name to lower |
| case if it cannot find the name as written.)@refill |
| @c !!! Can any file name be written in upper or lower case, |
| @c or is dir a special case? |
| @c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 |
| |
| |
| @node New Info File, Other Info Directories, Directory file, Install an Info File |
| @section Listing a New Info File |
| @cindex Adding a new info file |
| @cindex Listing a new info file |
| @cindex New info file, listing it in @file{dir} file |
| @cindex Info file, listing new one |
| @cindex @file{dir} file listing |
| |
| To add a new Info file to your system, you must write a menu entry to |
| add to the menu in the @file{dir} file in the @file{info} directory. |
| For example, if you were adding documentation for GDB, you would write |
| the following new entry:@refill |
| |
| @example |
| * GDB: (gdb). The source-level C debugger. |
| @end example |
| |
| @noindent |
| The first part of the menu entry is the menu entry name, followed by a |
| colon. The second part is the name of the Info file, in parentheses, |
| followed by a period. The third part is the description. |
| |
| The name of an Info file often has a @file{.info} extension. Thus, the |
| Info file for GDB might be called either @file{gdb} or @file{gdb.info}. |
| The Info reader programs automatically try the file name both with and |
| without @file{.info}; so it is better to avoid clutter and not to write |
| @samp{.info} explicitly in the menu entry. For example, the GDB menu |
| entry should use just @samp{gdb} for the file name, not @samp{gdb.info}. |
| |
| |
| @node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File |
| @comment node-name, next, previous, up |
| @section Info Files in Other Directories |
| @cindex Installing Info in another directory |
| @cindex Info installed in another directory |
| @cindex Another Info directory |
| |
| If an Info file is not in the @file{info} directory, there are three |
| ways to specify its location:@refill |
| |
| @itemize @bullet |
| @item |
| Write the pathname in the @file{dir} file as the second part of the |
| menu.@refill |
| |
| @item |
| If you are using Emacs, list the name of the file in a second @file{dir} |
| file, in its directory; and then add the name of that directory to the |
| @code{Info-directory-list} variable in your personal or site |
| initialization file. |
| |
| This tells Emacs's Info reader where to look for @file{dir} |
| files. Emacs merges the files named @file{dir} from each of the listed |
| directories. (In Emacs Version 18, you can set the |
| @code{Info-directory} variable to the name of only one |
| directory.)@refill |
| |
| @item |
| Specify the @file{info} directory name in the @code{INFOPATH} |
| environment variable in your @file{.profile} or @file{.cshrc} |
| initialization file. (Only you and others who set this environment |
| variable will be able to find Info files whose location is specified |
| this way.)@refill |
| @end itemize |
| |
| For example, to reach a test file in the @file{~bob/manuals} |
| directory, you could add an entry like this to the menu in the |
| @file{dir} file:@refill |
| |
| @example |
| * Test: (/home/bob/manuals/info-test). Bob's own test file. |
| @end example |
| |
| @noindent |
| In this case, the absolute file name of the @file{info-test} file is |
| written as the second part of the menu entry.@refill |
| |
| @vindex Info-directory-list |
| Alternatively, you could write the following in your @file{.emacs} |
| file:@refill |
| |
| @example |
| @group |
| (setq Info-directory-list |
| '("/home/bob/manuals" |
| "/usr/local/emacs/info")) |
| @end group |
| @end example |
| |
| @c reworded to avoid overfill hbox |
| This tells Emacs to merge the @file{dir} file from the |
| @file{/home/bob/manuals} directory with the @file{dir} file from the |
| @file{"/usr/local/emacs/info}" directory. Info will list the |
| @file{/home/bob/manuals/info-test} file as a menu entry in the |
| @file{/home/bob/manuals/dir} file.@refill |
| |
| @vindex INFOPATH |
| Finally, you can tell Info where to look by setting the |
| @code{INFOPATH} environment variable in your @file{.cshrc} or |
| @file{.profile} file.@refill |
| |
| If you use @code{sh} or @code{bash} for your shell command interpreter, |
| you must set the @code{INFOPATH} environment variable in the |
| @file{.profile} initialization file; but if you use @code{csh}, you must |
| set the variable in the @file{.cshrc} initialization file. The two |
| files use slightly different command formats.@refill |
| |
| @itemize @bullet |
| @item |
| In a @file{.cshrc} file, you could set the @code{INFOPATH} |
| variable as follows:@refill |
| |
| @smallexample |
| setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info |
| @end smallexample |
| |
| @item |
| In a @file{.profile} file, you would achieve the same effect by |
| writing:@refill |
| |
| @smallexample |
| INFOPATH=.:~bob/manuals:/usr/local/emacs/info |
| export INFOPATH |
| @end smallexample |
| @end itemize |
| |
| @noindent |
| The @samp{.} indicates the current directory. Emacs uses the |
| @code{INFOPATH} environment variable to initialize the value of Emacs's |
| own @code{Info-directory-list} variable. |
| |
| |
| @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File |
| @section Installing Info Directory Files |
| |
| When you install an Info file onto your system, you can use the program |
| @code{install-info} to update the Info directory file @file{dir}. |
| Normally the makefile for the package runs @code{install-info}, just |
| after copying the Info file into its proper installed location. |
| |
| @findex dircategory |
| @findex direntry |
| In order for the Info file to work with @code{install-info}, you should |
| use the commands @code{@@dircategory} and @code{@@direntry} in the |
| Texinfo source file. Use @code{@@direntry} to specify the menu entry to |
| add to the Info directory file, and use @code{@@dircategory} to specify |
| which part of the Info directory to put it in. Here is how these |
| commands are used in this manual: |
| |
| @smallexample |
| @@dircategory Texinfo documentation system |
| @@direntry |
| * Texinfo: (texinfo). The GNU documentation format. |
| * install-info: (texinfo)Invoking install-info. @dots{} |
| @dots{} |
| @@end direntry |
| @end smallexample |
| |
| Here's what this produces in the Info file: |
| |
| @smallexample |
| INFO-DIR-SECTION Texinfo documentation system |
| START-INFO-DIR-ENTRY |
| * Texinfo: (texinfo). The GNU documentation format. |
| * install-info: (texinfo)Invoking install-info. @dots{} |
| @dots{} |
| END-INFO-DIR-ENTRY |
| @end smallexample |
| |
| @noindent |
| The @code{install-info} program sees these lines in the Info file, and |
| that is how it knows what to do. |
| |
| Always use the @code{@@direntry} and @code{@@dircategory} commands near |
| the beginning of the Texinfo input, before the first @code{@@node} |
| command. If you use them later on in the input, @code{install-info} |
| will not notice them. |
| |
| If you use @code{@@dircategory} more than once in the Texinfo source, |
| each usage specifies one category; the new menu entry is added to the |
| Info directory file in each of the categories you specify. If you use |
| @code{@@direntry} more than once, each usage specifies one menu entry; |
| each of these menu entries is added to the directory in each of the |
| specified categories. |
| |
| |
| @node Invoking install-info, , Installing Dir Entries, Install an Info File |
| @section Invoking install-info |
| |
| @pindex install-info |
| |
| @code{install-info} inserts menu entries from an Info file into the |
| top-level @file{dir} file in the Info system (see the previous sections |
| for an explanation of how the @file{dir} file works). It's most often |
| run as part of software installation, or when constructing a dir file |
| for all manuals on a system. Synopsis: |
| |
| @example |
| install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] |
| @end example |
| |
| If @var{info-file} or @var{dir-file} are not specified, the various |
| options (described below) that define them must be. There are no |
| compile-time defaults, and standard input is never used. |
| @code{install-info} can read only one info file and write only one dir |
| file per invocation. |
| |
| Options: |
| |
| @table @samp |
| @item --delete |
| @opindex --delete |
| Only delete existing entries in @var{info-file}; don't insert any new |
| entries. |
| |
| @item --dir-file=@var{name} |
| @opindex --dir-file=@var{name} |
| Specify file name of the Info directory file. This is equivalent to |
| using the @var{dir-file} argument. |
| |
| @item --entry=@var{text} |
| @opindex --entry=@var{text} |
| Insert @var{text} as an Info directory entry; @var{text} should have the |
| form of an Info menu item line plus zero or more extra lines starting |
| with whitespace. If you specify more than one entry, they are all |
| added. If you don't specify any entries, they are determined from |
| information in the Info file itself. |
| |
| @item --help |
| @opindex --help |
| Display a usage message listing basic usage and all available options, |
| then exit successfully. |
| |
| @item --info-file=@var{file} |
| @opindex --info-file=@var{file} |
| Specify Info file to install in the directory. |
| This is equivalent to using the @var{info-file} argument. |
| |
| @item --info-dir=@var{dir} |
| @opindex --info-dir=@var{dir} |
| Equivalent to @samp{--dir-file=@var{dir}/dir}. |
| |
| @item --item=@var{text} |
| @opindex --item=@var{text} |
| Same as --entry=@var{text}. An Info directory entry is actually a menu |
| item. |
| |
| @item --quiet |
| @opindex --quiet |
| Suppress warnings. |
| |
| @item --remove |
| @opindex --remove |
| Same as --delete. |
| |
| @item --section=@var{sec} |
| @opindex --section=@var{sec} |
| Put this file's entries in section @var{sec} of the directory. If you |
| specify more than one section, all the entries are added in each of the |
| sections. If you don't specify any sections, they are determined from |
| information in the Info file itself. |
| |
| @item --version |
| @opindex --version |
| @cindex version number, finding |
| Display version information and exit successfully. |
| |
| @end table |
| |
| |
| @c ================ Appendix starts here ================ |
| |
| @node Command List, Tips, Install an Info File, Top |
| @appendix @@-Command List |
| @cindex Alphabetical @@-command list |
| @cindex List of @@-commands |
| @cindex @@-command list |
| |
| Here is an alphabetical list of the @@-commands in Texinfo. Square |
| brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, |
| @samp{@dots{}}, indicates repeated text.@refill |
| |
| @sp 1 |
| @table @code |
| @item @@@var{whitespace} |
| An @code{@@} followed by a space, tab, or newline produces a normal, |
| stretchable, interword space. @xref{Multiple Spaces}. |
| |
| @item @@! |
| Generate an exclamation point that really does end a sentence (usually |
| after an end-of-sentence capital letter). @xref{Ending a Sentence}. |
| |
| @item @@" |
| @itemx @@' |
| Generate an umlaut or acute accent, respectively, over the next |
| character, as in @"o and @'o. @xref{Inserting Accents}. |
| |
| @item @@* |
| Force a line break. Do not end a paragraph that uses @code{@@*} with |
| an @code{@@refill} command. @xref{Line Breaks}.@refill |
| |
| @item @@,@{@var{c}@} |
| Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting |
| Accents}. |
| |
| @item @@- |
| Insert a discretionary hyphenation point. @xref{- and hyphenation}. |
| |
| @item @@. |
| Produce a period that really does end a sentence (usually after an |
| end-of-sentence capital letter). @xref{Ending a Sentence}. |
| |
| @item @@: |
| Indicate to @TeX{} that an immediately preceding period, question |
| mark, exclamation mark, or colon does not end a sentence. Prevent |
| @TeX{} from inserting extra whitespace as it does at the end of a |
| sentence. The command has no effect on the Info file output. |
| @xref{Not Ending a Sentence}.@refill |
| |
| @item @@= |
| Generate a macro (bar) accent over the next character, as in @=o. |
| @xref{Inserting Accents}. |
| |
| @item @@? |
| Generate a question mark that really does end a sentence (usually after |
| an end-of-sentence capital letter). @xref{Ending a Sentence}. |
| |
| @item @@@@ |
| Stands for an at sign, @samp{@@}.@* |
| @xref{Braces Atsigns, , Inserting @@ and braces}. |
| |
| @item @@^ |
| @itemx @@` |
| Generate a circumflex (hat) or grave accent, respectively, over the next |
| character, as in @^o. |
| @xref{Inserting Accents}. |
| |
| @item @@@{ |
| Stands for a left brace, @samp{@{}.@* |
| @xref{Braces Atsigns, , Inserting @@ and braces}. |
| |
| @item @@@} |
| Stands for a right-hand brace, @samp{@}}.@* |
| @xref{Braces Atsigns, , Inserting @@ and braces}. |
| |
| @item @@= |
| Generate a tilde accent over the next character, as in @~N. |
| @xref{Inserting Accents}. |
| |
| @item @@AA@{@} |
| @itemx @@aa@{@} |
| Generate the uppercase and lowercase Scandinavian A-ring letters, |
| respectively: @AA{}, @aa{}. @xref{Inserting Accents}. |
| |
| @item @@AE@{@} |
| @itemx @@ae@{@} |
| Generate the uppercase and lowercase AE ligatures, respectively: |
| @AE{}, @ae{}. @xref{Inserting Accents}. |
| |
| @item @@appendix @var{title} |
| Begin an appendix. The title appears in the table |
| of contents of a printed manual. In Info, the title is |
| underlined with asterisks. @xref{unnumbered & appendix, , The |
| @code{@@unnumbered} and @code{@@appendix} Commands}.@refill |
| |
| @item @@appendixsec @var{title} |
| @itemx @@appendixsection @var{title} |
| Begin an appendix section within an appendix. The section title appears |
| in the table of contents of a printed manual. In Info, the title is |
| underlined with equal signs. @code{@@appendixsection} is a longer |
| spelling of the @code{@@appendixsec} command. @xref{unnumberedsec |
| appendixsec heading, , Section Commands}.@refill |
| |
| @item @@appendixsubsec @var{title} |
| Begin an appendix subsection within an appendix. The title appears |
| in the table of contents of a printed manual. In Info, the title is |
| underlined with hyphens. @xref{unnumberedsubsec appendixsubsec |
| subheading, , Subsection Commands}.@refill |
| |
| @item @@appendixsubsubsec @var{title} |
| Begin an appendix subsubsection within a subappendix. The title |
| appears in the table of contents of a printed manual. In Info, the |
| title is underlined with periods. @xref{subsubsection,, The `subsub' |
| Commands}.@refill |
| |
| @item @@asis |
| Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to |
| print the table's first column without highlighting (``as is''). |
| @xref{Two-column Tables, , Making a Two-column Table}.@refill |
| |
| @item @@author @var{author} |
| Typeset @var{author} flushleft and underline it. @xref{title |
| subtitle author, , The @code{@@title} and @code{@@author} |
| Commands}.@refill |
| |
| @item @@b@{@var{text}@} |
| Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill |
| |
| @ignore |
| @item @@br |
| Force a paragraph break. If used within a line, follow @code{@@br} |
| with braces. @xref{br, , @code{@@br}}.@refill |
| @end ignore |
| |
| @item @@bullet@{@} |
| Generate a large round dot, or the closest possible |
| thing to one. @xref{bullet, , @code{@@bullet}}.@refill |
| |
| @item @@bye |
| Stop formatting a file. The formatters do not see the contents of a |
| file following an @code{@@bye} command. @xref{Ending a File}.@refill |
| |
| @item @@c @var{comment} |
| Begin a comment in Texinfo. The rest of the line does not appear in |
| either the Info file or the printed manual. A synonym for |
| @code{@@comment}. @xref{Comments, , Comments}.@refill |
| |
| @item @@cartouche |
| Highlight an example or quotation by drawing a box with rounded |
| corners around it. Pair with @code{@@end cartouche}. No effect in |
| Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill |
| |
| @item @@center @var{line-of-text} |
| Center the line of text following the command. |
| @xref{titlefont center sp, , @code{@@center}}.@refill |
| |
| @item @@centerchap @var{line-of-text} |
| Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, |
| @code{@@chapter}}. |
| |
| @item @@chapheading @var{title} |
| Print a chapter-like heading in the text, but not in the table of |
| contents of a printed manual. In Info, the title is underlined with |
| asterisks. @xref{majorheading & chapheading, , @code{@@majorheading} |
| and @code{@@chapheading}}.@refill |
| |
| @item @@chapter @var{title} |
| Begin a chapter. The chapter title appears in the table of |
| contents of a printed manual. In Info, the title is underlined with |
| asterisks. @xref{chapter, , @code{@@chapter}}.@refill |
| |
| @item @@cindex @var{entry} |
| Add @var{entry} to the index of concepts. @xref{Index Entries, , |
| Defining the Entries of an Index}.@refill |
| |
| @item @@cite@{@var{reference}@} |
| Highlight the name of a book or other reference that lacks a |
| companion Info file. @xref{cite, , @code{@@cite}}.@refill |
| |
| @item @@clear @var{flag} |
| Unset @var{flag}, preventing the Texinfo formatting commands from |
| formatting text between subsequent pairs of @code{@@ifset @var{flag}} |
| and @code{@@end ifset} commands, and preventing |
| @code{@@value@{@var{flag}@}} from expanding to the value to which |
| @var{flag} is set. |
| @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill |
| |
| @item @@code@{@var{sample-code}@} |
| Highlight text that is an expression, a syntactically complete token |
| of a program, or a program name. @xref{code, , @code{@@code}}.@refill |
| |
| @item @@comment @var{comment} |
| Begin a comment in Texinfo. The rest of the line does not appear in |
| either the Info file or the printed manual. A synonym for @code{@@c}. |
| @xref{Comments, , Comments}.@refill |
| |
| @item @@contents |
| Print a complete table of contents. Has no effect in Info, which uses |
| menus instead. @xref{Contents, , Generating a Table of |
| Contents}.@refill |
| |
| @item @@copyright@{@} |
| Generate a copyright symbol. @xref{copyright symbol, , |
| @code{@@copyright}}.@refill |
| |
| @ignore |
| @item @@ctrl@{@var{ctrl-char}@} |
| Describe an @sc{ascii} control character. Insert actual control character |
| into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill |
| @end ignore |
| |
| @item @@defcodeindex @var{index-name} |
| Define a new index and its indexing command. Print entries in an |
| @code{@@code} font. @xref{New Indices, , Defining New |
| Indices}.@refill |
| |
| @item @@defcv @var{category} @var{class} @var{name} |
| @itemx @@defcvx @var{category} @var{class} @var{name} |
| Format a description for a variable associated with a class in |
| object-oriented programming. Takes three arguments: the category of |
| thing being defined, the class to which it belongs, and its name. |
| @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} |
| Format a description for a function, interactive command, or similar |
| entity that may take arguments. @code{@@deffn} takes as arguments the |
| category of entity being described, the name of this particular |
| entity, and its arguments, if any. @xref{Definition Commands}.@refill |
| |
| @item @@defindex @var{index-name} |
| Define a new index and its indexing command. Print entries in a roman |
| font. @xref{New Indices, , Defining New Indices}.@refill |
| |
| @c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96. |
| @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, |
| Create new @@-command for Info that marks text by enclosing it in |
| strings that precede and follow the text. Write definition inside of |
| @code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized |
| Highlighting}.@refill |
| |
| @item @@defivar @var{class} @var{instance-variable-name} |
| @itemx @@defivarx @var{class} @var{instance-variable-name} |
| This command formats a description for an instance variable in |
| object-oriented programming. The command is equivalent to @samp{@@defcv |
| @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defmac @var{macro-name} @var{arguments}@dots{} |
| @itemx @@defmacx @var{macro-name} @var{arguments}@dots{} |
| Format a description for a macro. The command is equivalent to |
| @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} |
| @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} |
| Format a description for a method in object-oriented programming. The |
| command is equivalent to @samp{@@defop Method @dots{}}. Takes as |
| arguments the name of the class of the method, the name of the |
| method, and its arguments, if any. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| Format a description for an operation in object-oriented programming. |
| @code{@@defop} takes as arguments the overall name of the category of |
| operation, the name of the class of the operation, the name of the |
| operation, and its arguments, if any. @xref{Definition |
| Commands}, and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defopt @var{option-name} |
| @itemx @@defoptx @var{option-name} |
| Format a description for a user option. The command is equivalent to |
| @samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defspec @var{special-form-name} @var{arguments}@dots{} |
| @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} |
| Format a description for a special form. The command is equivalent to |
| @samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}, |
| and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} |
| @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} |
| Format a description for a data type. @code{@@deftp} takes as arguments |
| the category, the name of the type (which is a word like @samp{int} or |
| @samp{float}), and then the names of attributes of objects of that type. |
| @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} |
| @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} |
| Format a description for a function or similar entity that may take |
| arguments and that is typed. @code{@@deftypefn} takes as arguments the |
| classification of entity being described, the type, the name of the |
| entity, and its arguments, if any. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} |
| @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} |
| Format a description for a function in a typed language. |
| The command is equivalent to @samp{@@deftypefn Function @dots{}}. |
| @xref{Definition Commands}, |
| and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@deftypevr @var{classification} @var{data-type} @var{name} |
| @itemx @@deftypevrx @var{classification} @var{data-type} @var{name} |
| Format a description for something like a variable in a typed |
| language---an entity that records a value. Takes as arguments the |
| classification of entity being described, the type, and the name of the |
| entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in |
| Detail}. |
| |
| @item @@deftypevar @var{data-type} @var{variable-name} |
| @itemx @@deftypevarx @var{data-type} @var{variable-name} |
| Format a description for a variable in a typed language. The command is |
| equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition |
| Commands}, and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defun @var{function-name} @var{arguments}@dots{} |
| @itemx @@defunx @var{function-name} @var{arguments}@dots{} |
| Format a description for functions. The command is equivalent to |
| @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defvar @var{variable-name} |
| @itemx @@defvarx @var{variable-name} |
| Format a description for variables. The command is equivalent to |
| @samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and |
| @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@defvr @var{category} @var{name} |
| @itemx @@defvrx @var{category} @var{name} |
| Format a description for any kind of variable. @code{@@defvr} takes |
| as arguments the category of the entity and the name of the entity. |
| @xref{Definition Commands}, |
| and @ref{deffnx,, Def Cmds in Detail}. |
| |
| @item @@detailmenu@{@} |
| Use to avoid Makeinfo confusion stemming from the detailed node listing |
| in a master menu. @xref{Master Menu Parts}. |
| |
| @item @@dfn@{@var{term}@} |
| Highlight the introductory or defining use of a term. |
| @xref{dfn, , @code{@@dfn}}.@refill |
| |
| @item @@dircategory @var{dirpart} |
| Specify a part of the Info directory menu where this file's entry should |
| go. @xref{Installing Dir Entries}. |
| |
| @item @@direntry |
| Begin the Info directory menu entry for this file. |
| @xref{Installing Dir Entries}. |
| |
| @need 100 |
| @item @@display |
| Begin a kind of example. Indent text, do not fill, do not select a |
| new font. Pair with @code{@@end display}. @xref{display, , |
| @code{@@display}}.@refill |
| |
| @item @@dmn@{@var{dimension}@} |
| Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a |
| thin space before @var{dimension}. No effect in Info. |
| @xref{dmn, , @code{@@dmn}}.@refill |
| |
| @need 100 |
| @item @@dots@{@} |
| Insert an ellipsis: @samp{@dots{}}. |
| @xref{dots, , @code{@@dots}}.@refill |
| |
| @item @@email@{@var{address}@} |
| Indicate an electronic mail address. |
| @xref{email, , @code{@@email}}.@refill |
| |
| @need 100 |
| @item @@emph@{@var{text}@} |
| Highlight @var{text}; text is displayed in @emph{italics} in printed |
| output, and surrounded by asterisks in Info. @xref{Emphasis, , Emphasizing Text}.@refill |
| |
| @item @@end @var{environment} |
| Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting |
| Commands,,@@-commands}. |
| |
| @item @@enddots@{@} |
| Generate an end-of-sentence of ellipsis, like this @enddots{} |
| @xref{dots,,@code{@@dots@{@}}}. |
| |
| @need 100 |
| @item @@enumerate [@var{number-or-letter}] |
| Begin a numbered list, using @code{@@item} for each entry. |
| Optionally, start list with @var{number-or-letter}. Pair with |
| @code{@@end enumerate}. @xref{enumerate, , |
| @code{@@enumerate}}.@refill |
| |
| @need 100 |
| @item @@equiv@{@} |
| Indicate to the reader the exact equivalence of two forms with a |
| glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill |
| |
| @item @@error@{@} |
| Indicate to the reader with a glyph that the following text is |
| an error message: @samp{@error{}}. @xref{Error Glyph}.@refill |
| |
| @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| Specify page footings for even-numbered (left-hand) pages. Not relevant to |
| Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill |
| |
| @item @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| Specify page headings for even-numbered (left-hand) pages. Only |
| supported within @code{@@iftex}. @xref{Custom Headings, , How to Make |
| Your Own Headings}.@refill |
| |
| @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| Specify page footings resp.@: headings for every page. Not relevant to |
| Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill |
| |
| @item @@example |
| Begin an example. Indent text, do not fill, and select fixed-width font. |
| Pair with @code{@@end example}. @xref{example, , |
| @code{@@example}}.@refill |
| |
| @item @@exclamdown@{@} |
| Generate an upside-down exclamation point. @xref{Inserting Accents}. |
| |
| @item @@exdent @var{line-of-text} |
| Remove any indentation a line might have. @xref{exdent, , |
| Undoing the Indentation of a Line}.@refill |
| |
| @item @@expansion@{@} |
| Indicate the result of a macro expansion to the reader with a special |
| glyph: @samp{@expansion{}}. |
| @xref{expansion, , @expansion{} Indicating an Expansion}.@refill |
| |
| @item @@file@{@var{filename}@} |
| Highlight the name of a file, buffer, node, or directory. @xref{file, , |
| @code{@@file}}.@refill |
| |
| @item @@finalout |
| Prevent @TeX{} from printing large black warning rectangles beside |
| over-wide lines. @xref{Overfull hboxes}.@refill |
| |
| @need 100 |
| @item @@findex @var{entry} |
| Add @var{entry} to the index of functions. @xref{Index Entries, , |
| Defining the Entries of an Index}.@refill |
| |
| @need 200 |
| @item @@flushleft |
| @itemx @@flushright |
| Left justify every line but leave the right end ragged. |
| Leave font as is. Pair with @code{@@end flushleft}. |
| @code{@@flushright} analogous. |
| @xref{flushleft & flushright, , @code{@@flushleft} and |
| @code{@@flushright}}.@refill |
| |
| @need 200 |
| @item @@footnote@{@var{text-of-footnote}@} |
| Enter a footnote. Footnote text is printed at the bottom of the page |
| by @TeX{}; Info may format in either `End' node or `Separate' node style. |
| @xref{Footnotes}.@refill |
| |
| @item @@footnotestyle @var{style} |
| Specify an Info file's footnote style, either @samp{end} for the end |
| node style or @samp{separate} for the separate node style. |
| @xref{Footnotes}.@refill |
| |
| @item @@format |
| Begin a kind of example. Like @code{@@example} or @code{@@display}, |
| but do not narrow the margins and do not select the fixed-width font. |
| Pair with @code{@@end format}. @xref{example, , |
| @code{@@example}}.@refill |
| |
| @item @@ftable @var{formatting-command} |
| Begin a two-column table, using @code{@@item} for each entry. |
| Automatically enter each of the items in the first column into the |
| index of functions. Pair with @code{@@end ftable}. The same as |
| @code{@@table}, except for indexing. @xref{ftable vtable, , |
| @code{@@ftable} and @code{@@vtable}}.@refill |
| |
| @item @@group |
| Hold text together that must appear on one printed page. Pair with |
| @code{@@end group}. Not relevant to Info. @xref{group, , |
| @code{@@group}}.@refill |
| |
| @item @@H@{@var{c}@} |
| Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. |
| |
| @item @@heading @var{title} |
| Print an unnumbered section-like heading in the text, but not in the |
| table of contents of a printed manual. In Info, the title is |
| underlined with equal signs. @xref{unnumberedsec appendixsec heading, |
| , Section Commands}.@refill |
| |
| @item @@headings @var{on-off-single-double} |
| Turn page headings on or off, and/or specify single-sided or double-sided |
| page headings for printing. @xref{headings on off, , The |
| @code{@@headings} Command}. |
| |
| @item @@i@{@var{text}@} |
| Print @var{text} in @i{italic} font. No effect in Info. |
| @xref{Fonts}.@refill |
| |
| @item @@ifclear @var{flag} |
| If @var{flag} is cleared, the Texinfo formatting commands format text |
| between @code{@@ifclear @var{flag}} and the following @code{@@end |
| ifclear} command. |
| @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill |
| |
| @item @@ifhtml |
| @itemx @@ifinfo |
| Begin a stretch of text that will be ignored by @TeX{} when it typesets |
| the printed manual. The text appears only in the HTML resp.@: Info |
| file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. |
| @xref{Conditionals, , Conditionally Visible Text}.@refill |
| |
| @item @@ifset @var{flag} |
| If @var{flag} is set, the Texinfo formatting commands format text |
| between @code{@@ifset @var{flag}} and the following @code{@@end ifset} |
| command. |
| @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill |
| |
| @item @@iftex |
| Begin a stretch of text that will not appear in the Info file, but |
| will be processed only by @TeX{}. Pair with @code{@@end iftex}. |
| @xref{Conditionals, , Conditionally Visible Text}.@refill |
| |
| @item @@ignore |
| Begin a stretch of text that will not appear in either the Info file |
| or the printed output. Pair with @code{@@end ignore}. |
| @xref{Comments, , Comments and Ignored Text}.@refill |
| |
| @item @@include @var{filename} |
| Incorporate the contents of the file @var{filename} into the Info file |
| or printed document. @xref{Include Files}.@refill |
| |
| @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} |
| Make a cross reference to an Info file for which there is no printed |
| manual. @xref{inforef, , Cross references using |
| @code{@@inforef}}.@refill |
| |
| @item \input @var{macro-definitions-file} |
| Use the specified macro definitions file. This command is used only |
| in the first line of a Texinfo file to cause @TeX{} to make use of the |
| @file{texinfo} macro definitions file. The backslash in @code{\input} |
| is used instead of an @code{@@} because @TeX{} does not |
| recognize @code{@@} until after it has read the definitions file. |
| @xref{Header, , The Texinfo File Header}.@refill |
| |
| @item @@item |
| Indicate the beginning of a marked paragraph for @code{@@itemize} and |
| @code{@@enumerate}; indicate the beginning of the text of a first column |
| entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. |
| @xref{Lists and Tables}.@refill |
| |
| @item @@itemize @var{mark-generating-character-or-command} |
| Produce a sequence of indented paragraphs, with a mark inside the left |
| margin at the beginning of each paragraph. Pair with @code{@@end |
| itemize}. @xref{itemize, , @code{@@itemize}}.@refill |
| |
| @item @@itemx |
| Like @code{@@item} but do not generate extra vertical space above the |
| item text. @xref{itemx, , @code{@@itemx}}.@refill |
| |
| @item @@kbd@{@var{keyboard-characters}@} |
| Indicate text that is characters of input to be typed by |
| users. @xref{kbd, , @code{@@kbd}}.@refill |
| |
| @item @@key@{@var{key-name}@} |
| Highlight @var{key-name}, a name for a key on a keyboard. |
| @xref{key, , @code{@@key}}.@refill |
| |
| @item @@kindex @var{entry} |
| Add @var{entry} to the index of keys. @xref{Index Entries, , Defining the |
| Entries of an Index}.@refill |
| |
| @item @@L@{@} |
| @itemx @@l@{@} |
| Generate the uppercase and lowercase Polish suppressed-L letters, |
| respectively: @L{}, @l{}. |
| |
| @c Possibly this can be tossed now that we have macros. --karl, 16sep96. |
| @item @@global@@let@var{new-command}=@var{existing-command} |
| Equate a new highlighting command with an existing one. Only for |
| @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end |
| iftex}. @xref{Customized Highlighting}.@refill |
| |
| @item @@lisp |
| Begin an example of Lisp code. Indent text, do not fill, and select |
| fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, , |
| @code{@@lisp}}.@refill |
| |
| @item @@lowersections |
| Change subsequent chapters to sections, sections to subsections, and so |
| on. @xref{Raise/lower sections, , @code{@@raisesections} and |
| @code{@@lowersections}}.@refill |
| |
| @item @@macro @var{macro-name} @{@var{params}@} |
| Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}. |
| Only supported by Makeinfo and Texi2dvi. @xref{Defining Macros}. |
| |
| @item @@majorheading @var{title} |
| Print a chapter-like heading in the text, but not in the table of |
| contents of a printed manual. Generate more vertical whitespace before |
| the heading than the @code{@@chapheading} command. In Info, the chapter |
| heading line is underlined with asterisks. @xref{majorheading & |
| chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill |
| |
| @item @@math@{@var{mathematical-expression}@} |
| Format a mathematical expression. |
| @xref{math, , @code{@@math}: Inserting Mathematical Expressions}. |
| |
| @item @@menu |
| Mark the beginning of a menu of nodes in Info. No effect in a printed |
| manual. Pair with @code{@@end menu}. @xref{Menus}.@refill |
| |
| @item @@minus@{@} |
| Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill |
| |
| @item @@multitable @var{column-width-spec} |
| Begin a multi-column table. Pair with @code{@@end multitable}. |
| @xref{Multitable Column Widths}. |
| |
| @item @@need @var{n} |
| Start a new page in a printed manual if fewer than @var{n} mils |
| (thousandths of an inch) remain on the current page. @xref{need, , |
| @code{@@need}}.@refill |
| |
| @item @@node @var{name, next, previous, up} |
| Define the beginning of a new node in Info, and serve as a locator for |
| references for @TeX{}. @xref{node, , @code{@@node}}.@refill |
| |
| @item @@noindent |
| Prevent text from being indented as if it were a new paragraph. |
| @xref{noindent, , @code{@@noindent}}.@refill |
| |
| @item @@O@{@} |
| @itemx @@o@{@} |
| Generate the uppercase and lowercase Owith-slash letters, respectively: |
| @O{}, @o{}. |
| |
| @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| Specify page footings resp.@: headings for odd-numbered (right-hand) |
| pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, , |
| How to Make Your Own Headings}.@refill |
| |
| @item @@OE@{@} |
| @itemx @@oe@{@} |
| Generate the uppercase and lowercase OE ligatures, respectively: |
| @OE{}, @oe{}. @xref{Inserting Accents}. |
| |
| @item @@page |
| Start a new page in a printed manual. No effect in Info. |
| @xref{page, , @code{@@page}}.@refill |
| |
| @item @@paragraphindent @var{indent} |
| Indent paragraphs by @var{indent} number of spaces; delete indentation |
| if the value of @var{indent} is 0; and do not change indentation if |
| @var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph |
| Indenting}.@refill |
| |
| @item @@pindex @var{entry} |
| Add @var{entry} to the index of programs. @xref{Index Entries, , Defining |
| the Entries of an Index}.@refill |
| |
| @item @@point@{@} |
| Indicate the position of point in a buffer to the reader with a |
| glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating |
| Point in a Buffer}.@refill |
| |
| @item @@pounds@{@} |
| Generate the pounds sterling currency sign. |
| @xref{pounds,,@code{@@pounds@{@}}}. |
| |
| @item @@print@{@} |
| Indicate printed output to the reader with a glyph: |
| @samp{@print{}}. @xref{Print Glyph}.@refill |
| |
| @item @@printindex @var{index-name} |
| Print an alphabetized two-column index in a printed manual or generate |
| an alphabetized menu of index entries for Info. @xref{Printing |
| Indices & Menus}.@refill |
| |
| @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} |
| Make a reference that starts with a lower case `see' in a printed |
| manual. Use within parentheses only. Do not follow command with a |
| punctuation mark---the Info formatting commands automatically insert |
| terminating punctuation as needed. Only the first argument is mandatory. |
| @xref{pxref, , @code{@@pxref}}.@refill |
| |
| @item @@questiondown@{@} |
| Generate an upside-down question mark. @xref{Inserting Accents}. |
| |
| @item @@quotation |
| Narrow the margins to indicate text that is quoted from another real |
| or imaginary work. Write command on a line of its own. Pair with |
| @code{@@end quotation}. @xref{quotation, , |
| @code{@@quotation}}.@refill |
| |
| @need 100 |
| @item @@r@{@var{text}@} |
| Print @var{text} in @r{roman} font. No effect in Info. |
| @xref{Fonts}.@refill |
| |
| @item @@raisesections |
| Change subsequent sections to chapters, subsections to sections, and so |
| on. @xref{Raise/lower sections, , @code{@@raisesections} and |
| @code{@@lowersections}}.@refill |
| |
| @need 300 |
| @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} |
| Make a reference. In a printed manual, the reference does not start |
| with a `See'. Follow command with a punctuation mark. Only the first |
| argument is mandatory. @xref{ref, , @code{@@ref}}.@refill |
| |
| @need 300 |
| @item @@refill |
| In Info, refill and indent the paragraph after all the other processing |
| has been done. No effect on @TeX{}, which always refills. This command |
| is no longer needed, since all formatters now automatically refill. |
| @xref{Refilling Paragraphs}.@refill |
| |
| @need 300 |
| @item @@result@{@} |
| Indicate the result of an expression to the reader with a special |
| glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill |
| |
| @item @@ringaccent@{@var{c}@} |
| Generate a ring accent over the next character, as in @ringaccent{o}. |
| @xref{Inserting Accents}. |
| |
| @item @@samp@{@var{text}@} |
| Highlight @var{text} that is a literal example of a sequence of |
| characters. Used for single characters, for statements, and often for |
| entire shell commands. @xref{samp, , @code{@@samp}}.@refill |
| |
| @item @@sc@{@var{text}@} |
| Set @var{text} in a printed output in @sc{the small caps font} and |
| set text in the Info file in uppercase letters. |
| @xref{Smallcaps}.@refill |
| |
| @item @@section @var{title} |
| Begin a section within a chapter. In a printed manual, the section |
| title is numbered and appears in the table of contents. In Info, the |
| title is underlined with equal signs. @xref{section, , |
| @code{@@section}}.@refill |
| |
| @item @@set @var{flag} [@var{string}] |
| Make @var{flag} active, causing the Texinfo formatting commands to |
| format text between subsequent pairs of @code{@@ifset @var{flag}} and |
| @code{@@end ifset} commands. Optionally, set value of @var{flag} to |
| @var{string}. |
| @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill |
| |
| @item @@setchapternewpage @var{on-off-odd} |
| Specify whether chapters start on new pages, and if so, whether on |
| odd-numbered (right-hand) new pages. @xref{setchapternewpage, , |
| @code{@@setchapternewpage}}.@refill |
| |
| @item @@setfilename @var{info-file-name} |
| Provide a name to be used by the Info file. This command is essential |
| for @TeX{} formatting as well, even though it produces no output. |
| @xref{setfilename, , @code{@@setfilename}}.@refill |
| |
| @item @@settitle @var{title} |
| Provide a title for page headers in a printed manual. |
| @xref{settitle, , @code{@@settitle}}.@refill |
| |
| @item @@shortcontents |
| Print a short table of contents. Not relevant to Info, which uses |
| menus rather than tables of contents. A synonym for |
| @code{@@summarycontents}. @xref{Contents, , Generating a Table of |
| Contents}.@refill |
| |
| @item @@shorttitlepage@{@var{title}@} |
| Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. |
| |
| @need 400 |
| @item @@smallbook |
| Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format |
| rather than the regular 8.5 by 11 inch format. @xref{smallbook, , |
| Printing Small Books}. Also, see @ref{smallexample & smalllisp, , |
| @code{@@smallexample} and @code{@@smalllisp}}.@refill |
| |
| @need 400 |
| @item @@smallexample |
| Indent text to indicate an example. Do not fill, select fixed-width |
| font. In @code{@@smallbook} format, print text in a smaller font than |
| with @code{@@example}. Pair with @code{@@end smallexample}. |
| @xref{smallexample & smalllisp, , @code{@@smallexample} and |
| @code{@@smalllisp}}.@refill |
| |
| @need 400 |
| @item @@smalllisp |
| Begin an example of Lisp code. Indent text, do not fill, select |
| fixed-width font. In @code{@@smallbook} format, print text in a |
| smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & |
| smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill |
| |
| @need 700 |
| @item @@sp @var{n} |
| Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill |
| |
| @item @@ss@{@} |
| Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. |
| |
| @need 700 |
| @item @@strong @var{text} |
| Emphasize @var{text} by typesetting it in a @strong{bold} font for the |
| printed manual and by surrounding it with asterisks for Info. |
| @xref{emph & strong, , Emphasizing Text}.@refill |
| |
| @item @@subheading @var{title} |
| Print an unnumbered subsection-like heading in the text, but not in |
| the table of contents of a printed manual. In Info, the title is |
| underlined with hyphens. @xref{unnumberedsubsec appendixsubsec |
| subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} |
| @code{@@subheading}}.@refill |
| |
| @item @@subsection @var{title} |
| Begin a subsection within a section. In a printed manual, the |
| subsection title is numbered and appears in the table of contents. In |
| Info, the title is underlined with hyphens. @xref{subsection, , |
| @code{@@subsection}}.@refill |
| |
| @item @@subsubheading @var{title} |
| Print an unnumbered subsubsection-like heading in the text, but not in |
| the table of contents of a printed manual. In Info, the title is |
| underlined with periods. @xref{subsubsection, , The `subsub' |
| Commands}.@refill |
| |
| @item @@subsubsection @var{title} |
| Begin a subsubsection within a subsection. In a printed manual, |
| the subsubsection title is numbered and appears in the table of |
| contents. In Info, the title is underlined with periods. |
| @xref{subsubsection, , The `subsub' Commands}.@refill |
| |
| @item @@subtitle @var{title} |
| In a printed manual, set a subtitle in a normal sized font flush to |
| the right-hand side of the page. Not relevant to Info, which does not |
| have title pages. @xref{title subtitle author, , @code{@@title} |
| @code{@@subtitle} and @code{@@author} Commands}.@refill |
| |
| @item @@summarycontents |
| Print a short table of contents. Not relevant to Info, which uses |
| menus rather than tables of contents. A synonym for |
| @code{@@shortcontents}. @xref{Contents, , Generating a Table of |
| Contents}.@refill |
| |
| @need 300 |
| @item @@syncodeindex @var{from-index} @var{into-index} |
| Merge the index named in the first argument into the index named in |
| the second argument, printing the entries from the first index in |
| @code{@@code} font. @xref{Combining Indices}.@refill |
| |
| @need 300 |
| @item @@synindex @var{from-index} @var{into-index} |
| Merge the index named in the first argument into the index named in |
| the second argument. Do not change the font of @var{from-index} |
| entries. @xref{Combining Indices}.@refill |
| |
| @need 100 |
| @item @@t@{@var{text}@} |
| Print @var{text} in a @t{fixed-width}, typewriter-like font. |
| No effect in Info. @xref{Fonts}.@refill |
| |
| @item @@tab |
| Separate columns in a multitable. @xref{Multitable Rows}. |
| |
| @need 400 |
| @item @@table @var{formatting-command} |
| Begin a two-column table, using @code{@@item} for each entry. Write |
| each first column entry on the same line as @code{@@item}. First |
| column entries are printed in the font resulting from |
| @var{formatting-command}. Pair with @code{@@end table}. |
| @xref{Two-column Tables, , Making a Two-column Table}. |
| Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, |
| and @ref{itemx, , @code{@@itemx}}.@refill |
| |
| @item @@TeX@{@} |
| Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{} |
| and @copyright{}}.@refill |
| |
| @item @@tex |
| Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Using |
| Ordinary TeX Commands, , Using Ordinary @TeX{} Commands}.@refill |
| |
| @item @@thischapter |
| @itemx @@thischaptername |
| @itemx @@thisfile |
| @itemx @@thispage |
| @itemx @@thistitle |
| Only allowed in a heading or footing. Stands for the number and name of |
| the current chapter (in the format `Chapter 1: Title'), the chapter name |
| only, the filename, the current page number, and the title of the |
| document, respectively. @xref{Custom Headings, , How to Make Your Own |
| Headings}.@refill |
| |
| @item @@tindex @var{entry} |
| Add @var{entry} to the index of data types. @xref{Index Entries, , |
| Defining the Entries of an Index}.@refill |
| |
| @item @@title @var{title} |
| In a printed manual, set a title flush to the left-hand side of the |
| page in a larger than normal font and underline it with a black rule. |
| Not relevant to Info, which does not have title pages. @xref{title |
| subtitle author, , The @code{@@title} @code{@@subtitle} and |
| @code{@@author} Commands}.@refill |
| |
| @need 400 |
| @item @@titlefont@{@var{text}@} |
| In a printed manual, print @var{text} in a larger than normal font. |
| Not relevant to Info, which does not have title pages. |
| @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} |
| and @code{@@sp} Commands}.@refill |
| |
| @need 300 |
| @item @@titlepage |
| Indicate to Texinfo the beginning of the title page. Write command on |
| a line of its own. Pair with @code{@@end titlepage}. Nothing between |
| @code{@@titlepage} and @code{@@end titlepage} appears in Info. |
| @xref{titlepage, , @code{@@titlepage}}.@refill |
| |
| @need 150 |
| @item @@today@{@} |
| Insert the current date, in `1 Jan 1900' style. @xref{Custom |
| Headings, , How to Make Your Own Headings}.@refill |
| |
| @item @@top @var{title} |
| In a Texinfo file to be formatted with @code{makeinfo}, identify the |
| topmost @code{@@node} line in the file, which must be written on the line |
| immediately preceding the @code{@@top} command. Used for |
| @code{makeinfo}'s node pointer insertion feature. The title is |
| underlined with asterisks. Both the @code{@@node} line and the @code{@@top} |
| line normally should be enclosed by @code{@@ifinfo} and @code{@@end |
| ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} |
| command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo |
| Pointer Creation, , Creating Pointers with @code{makeinfo}}. |
| |
| @item @@u@var{c} |
| @itemx @@ubaraccent@var{c} |
| @itemx @@udotaccent@var{c} |
| Generate a breve, underbar, or underdot accent, respectively, over or |
| under the character @var{c}, as in @u{o}, @ubaraccent{o}, |
| @udotaccent{o}. @xref{Inserting Accents}. |
| |
| @item @@unnumbered @var{title} |
| In a printed manual, begin a chapter that appears without chapter |
| numbers of any kind. The title appears in the table of contents of a |
| printed manual. In Info, the title is underlined with asterisks. |
| @xref{unnumbered & appendix, , @code{@@unnumbered} and |
| @code{@@appendix}}.@refill |
| |
| @item @@unnumberedsec @var{title} |
| In a printed manual, begin a section that appears without section |
| numbers of any kind. The title appears in the table of contents of a |
| printed manual. In Info, the title is underlined with equal signs. |
| @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill |
| |
| @item @@unnumberedsubsec @var{title} |
| In a printed manual, begin an unnumbered subsection within a |
| chapter. The title appears in the table of contents of a printed |
| manual. In Info, the title is underlined with hyphens. |
| @xref{unnumberedsubsec appendixsubsec subheading, , |
| @code{@@unnumberedsubsec} @code{@@appendixsubsec} |
| @code{@@subheading}}.@refill |
| |
| @item @@unnumberedsubsubsec @var{title} |
| In a printed manual, begin an unnumbered subsubsection within a |
| chapter. The title appears in the table of contents of a printed |
| manual. In Info, the title is underlined with periods. |
| @xref{subsubsection, , The `subsub' Commands}.@refill |
| |
| @item @@url@{@var{url}@} |
| Highlight text that is a uniform resource locator for the World Wide |
| Web. @xref{url, , @code{@@url}}.@refill |
| |
| @item @@v@var{c} |
| Generate check accent over the character @var{c}, as in @v{o}. |
| @xref{Inserting Accents}. |
| |
| @item @@value@{@var{flag}@} |
| Replace @var{flag} with the value to which it is set by @code{@@set |
| @var{flag}}. |
| @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill |
| |
| @item @@var@{@var{metasyntactic-variable}@} |
| Highlight a metasyntactic variable, which is something that stands for |
| another piece of text. @xref{var, , Indicating Metasyntactic |
| Variables}.@refill |
| |
| @need 400 |
| @item @@vindex @var{entry} |
| Add @var{entry} to the index of variables. @xref{Index Entries, , |
| Defining the Entries of an Index}.@refill |
| |
| @need 400 |
| @item @@vskip @var{amount} |
| In a printed manual, insert whitespace so as to push text on the |
| remainder of the page towards the bottom of the page. Used in |
| formatting the copyright page with the argument @samp{0pt plus |
| 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used |
| only in contexts ignored for Info. @xref{Copyright & Permissions, , |
| The Copyright Page and Printed Permissions}.@refill |
| |
| @need 400 |
| @item @@vtable @var{formatting-command} |
| Begin a two-column table, using @code{@@item} for each entry. |
| Automatically enter each of the items in the first column into the |
| index of variables. Pair with @code{@@end vtable}. The same as |
| @code{@@table}, except for indexing. @xref{ftable vtable, , |
| @code{@@ftable} and @code{@@vtable}}.@refill |
| |
| @need 400 |
| @item @@w@{@var{text}@} |
| Prevent @var{text} from being split across two lines. Do not end a |
| paragraph that uses @code{@@w} with an @code{@@refill} command. |
| @xref{w, , @code{@@w}}.@refill |
| |
| @need 400 |
| @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} |
| Make a reference that starts with `See' in a printed manual. Follow |
| command with a punctuation mark. Only the first argument is |
| mandatory. @xref{xref, , @code{@@xref}}.@refill |
| @end table |
| |
| @node Tips, Sample Texinfo File, Command List, Top |
| @comment node-name, next, previous, up |
| @appendix Tips and Hints |
| |
| Here are some tips for writing Texinfo documentation:@refill |
| |
| @cindex Tips |
| @cindex Usage tips |
| @cindex Hints |
| @itemize @bullet |
| @item |
| Write in the present tense, not in the past or the future. |
| |
| @item |
| Write actively! For example, write ``We recommend that @dots{}'' rather |
| than ``It is recommended that @dots{}''. |
| |
| @item |
| Use 70 or 72 as your fill column. Longer lines are hard to read. |
| |
| @item |
| Include a copyright notice and copying permissions. |
| @end itemize |
| |
| @subsubheading 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: |
| |
| @itemize @bullet |
| @item |
| Write each index entry differently, so each entry refers to a different |
| place in the document. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @need 1000 |
| In the example that follows, a blank line comes after the index |
| entry for ``Leaping'': |
| |
| @example |
| @group |
| @@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. |
| @end group |
| @end example |
| |
| @noindent |
| (Note that the example shows entries for the same concept that are |
| written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so |
| readers can look up the concept in different ways.) |
| @end itemize |
| |
| @subsubheading Blank lines |
| |
| @itemize @bullet |
| @item |
| 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. |
| |
| @item |
| Always insert a blank line before an @code{@@table} command and after an |
| @code{@@end table} command; but never insert a blank line after an |
| @code{@@table} command or before an @code{@@end table} command. |
| |
| @need 1000 |
| For example, |
| |
| @example |
| @group |
| Types of fox: |
| |
| @@table @@samp |
| @@item Quick |
| Jump over lazy dogs. |
| @end group |
| |
| @group |
| @@item Brown |
| Also jump over lazy dogs. |
| @@end table |
| |
| @end group |
| @group |
| @@noindent |
| On the other hand, @dots{} |
| @end group |
| @end example |
| |
| Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end |
| itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the |
| same way. |
| @end itemize |
| |
| @subsubheading Complete phrases |
| |
| Complete phrases are easier to read than @dots{} |
| |
| @itemize @bullet |
| @item |
| Write entries in an itemized list as complete sentences; or at least, as |
| complete phrases. Incomplete expressions @dots{} awkward @dots{} like |
| this. |
| |
| @item |
| 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. |
| @end itemize |
| |
| @subsubheading Editions, dates and versions |
| |
| Write the edition and version numbers and date in three places in every |
| manual: |
| |
| @enumerate |
| @item |
| In the first @code{@@ifinfo} section, for people reading the Texinfo file. |
| |
| @item |
| In the @code{@@titlepage} section, for people reading the printed manual. |
| |
| @item |
| In the `Top' node, for people reading the Info file. |
| @end enumerate |
| |
| @noindent |
| Also, it helps to write a note before the first @code{@@ifinfo} |
| section to explain what you are doing. |
| |
| @need 800 |
| @noindent |
| For example: |
| |
| @example |
| @group |
| @@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 |
| @end group |
| |
| @group |
| @@ifinfo |
| @@c !!set edition, date, version |
| This is Edition 4.03, January 1992, |
| of the @@cite@{GDB Manual@} for GDB Version 4.3. |
| @dots{} |
| @end group |
| @end example |
| |
| @noindent |
| ---or use @code{@@set} and @code{@@value} |
| (@pxref{value Example, , @code{@@value} Example}). |
| |
| @subsubheading Definition Commands |
| |
| Definition commands are @code{@@deffn}, @code{@@defun}, |
| @code{@@defmac}, and the like, and enable you to write descriptions in |
| a uniform format.@refill |
| |
| @itemize @bullet |
| @item |
| 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. |
| |
| @item |
| Use @code{@@table} @dots{} @code{@@end table} in an appendix that |
| contains a summary of functions, not @code{@@deffn} or other definition |
| commands. |
| @end itemize |
| |
| @subsubheading Capitalization |
| |
| @itemize @bullet |
| @item |
| Capitalize @samp{Texinfo}; it is a name. Do not write the @samp{x} or |
| @samp{i} in upper case. |
| |
| @item |
| Capitalize @samp{Info}; it is a name. |
| |
| @item |
| Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase |
| @samp{T} and @samp{X}. This command causes the formatters to |
| typeset the name according to the wishes of Donald Knuth, who wrote |
| @TeX{}. |
| @end itemize |
| |
| @subsubheading Spaces |
| |
| Do not use spaces to format a Texinfo file, except inside of |
| @code{@@example} @dots{} @code{@@end example} and similar commands. |
| |
| @need 700 |
| For example, @TeX{} fills the following: |
| |
| @example |
| @group |
| @@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. |
| @end group |
| @end example |
| |
| @need 950 |
| @noindent |
| so it looks like this: |
| |
| @iftex |
| @quotation |
| @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. |
| @end quotation |
| @end iftex |
| @ifinfo |
| @quotation |
| `C-x v' `M-x vc-next-action' Perform the next logical operation on the |
| version-controlled file corresponding to the current buffer. |
| @end quotation |
| @end ifinfo |
| |
| @noindent |
| In this case, the text should be formatted with |
| @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. |
| |
| @subsubheading @@code, @@samp, @@var, and @samp{---} |
| |
| @itemize @bullet |
| @item |
| Use @code{@@code} around Lisp symbols, including command names. |
| For example, |
| |
| @example |
| The main function is @@code@{vc-next-action@}, @dots{} |
| @end example |
| |
| @item |
| Avoid putting letters such as @samp{s} immediately after an |
| @samp{@@code}. Such letters look bad. |
| |
| @item |
| Use @code{@@var} around meta-variables. Do not write angle brackets |
| around them. |
| |
| @item |
| Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} |
| typesets these as a long dash and the Info formatters reduce three |
| hyphens to two. |
| @end itemize |
| |
| @subsubheading 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: |
| |
| @example |
| Evidently, @samp{au} is an abbreviation for ``author''. |
| @end example |
| |
| @noindent |
| since @samp{au} does @emph{not} serve as an abbreviation for |
| @samp{author.} (with a period following the word). |
| |
| @subsubheading Introducing New Terms |
| |
| @itemize @bullet |
| @item |
| 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. |
| |
| @quotation |
| 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. |
| @end quotation |
| |
| @item |
| 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. |
| @end itemize |
| |
| @subsubheading @@pxref |
| |
| @c !!! maybe include this in the tips on pxref |
| @ignore |
| 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. |
| @end 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. |
| |
| @subsubheading 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.@refill |
| |
| Name such sections with a phrase beginning with the word |
| @w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way |
| users can find the section easily. |
| |
| @subsubheading @sc{ansi c} Syntax |
| |
| When you use @code{@@example} to describe a C function's calling |
| conventions, use the @sc{ansi c} syntax, like this:@refill |
| |
| @example |
| void dld_init (char *@@var@{path@}); |
| @end example |
| |
| @noindent |
| And in the subsequent discussion, refer to the argument values by |
| writing the same argument names, again highlighted with |
| @code{@@var}.@refill |
| |
| @need 800 |
| Avoid the obsolete style that looks like this:@refill |
| |
| @example |
| #include <dld.h> |
| |
| dld_init (path) |
| char *path; |
| @end 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 |
| @code{#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.@refill |
| |
| @subsubheading Bad Examples |
| |
| Here are several examples of bad writing to avoid: |
| |
| In this example, say, `` @dots{} you must @code{@@dfn}@{check |
| in@} the new version.'' That flows better. |
| |
| @quotation |
| When you are done editing the file, you must perform a |
| @code{@@dfn}@{check in@}. |
| @end quotation |
| |
| In the following example, say, ``@dots{} makes a unified interface such as VC |
| mode possible.'' |
| |
| @quotation |
| 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). |
| @end quotation |
| |
| And in this example, you should specify what `it' refers to: |
| |
| @quotation |
| If you are working with other people, it assists in coordinating |
| everyone's changes so they do not step on each other. |
| @end quotation |
| |
| @subsubheading And Finally @dots{} |
| |
| @itemize @bullet |
| @item |
| 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': |
| @samp{teckinfo}. |
| |
| @item |
| Write notes for yourself at the very end of a Texinfo file after the |
| @code{@@bye}. None of the formatters process text after the |
| @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} |
| @code{@@end ignore}. |
| @end itemize |
| |
| @node Sample Texinfo File, Sample Permissions, Tips, Top |
| @comment node-name, next, previous, up |
| @appendix A Sample Texinfo File |
| @cindex 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, , A Short Sample Texinfo File}. |
| |
| @sp 1 |
| @example |
| \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 |
| @end example |
| |
| @node Sample Permissions, Include Files, Sample Texinfo File, Top |
| @appendix Sample Permissions |
| @cindex Permissions |
| @cindex Copying 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.@refill |
| |
| 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. @xref{Distrib, , |
| Distribution, emacs, The GNU Emacs Manual}, for an example of the text |
| that could be used in the software ``Distribution'', ``General Public |
| License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, |
| , Texinfo Copying Conditions}, for an example of a brief explanation |
| of how the copying conditions provide you with rights. @refill |
| |
| @menu |
| * Inserting Permissions:: How to put permissions in your document. |
| * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. |
| * Titlepage Permissions:: Sample Titlepage copying permissions. |
| @end menu |
| |
| @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions |
| @ifinfo |
| @appendixsec Inserting Permissions |
| @end ifinfo |
| |
| In a Texinfo file, the first @code{@@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 @kbd{g *} sees first. @inforef{Expert, Advanced Info |
| commands, info}, 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.)@refill |
| |
| In the @code{@@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 @code{@@ignore} and |
| @code{@@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.@refill |
| |
| 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 @code{@@titlepage} and |
| @code{@@end titlepage} commands. The copying permission notice is exactly |
| the same as the notice in the @code{@@ifinfo} section except that the |
| paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is |
| not part of the notice.@refill |
| |
| 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.@refill |
| |
| Note that you may need to specify the correct name of a section |
| mentioned in the permission notice. For example, in @cite{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.@refill |
| |
| @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions |
| @comment node-name, next, previous, up |
| @appendixsec @samp{ifinfo} Copying Permissions |
| @cindex @samp{ifinfo} permissions |
| |
| In the @code{@@ifinfo} section of a Texinfo file, the standard Free |
| Software Foundation permission notice reads as follows:@refill |
| |
| @example |
| This file documents @dots{} |
| |
| 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. |
| @end example |
| |
| @node Titlepage Permissions, , ifinfo Permissions, Sample Permissions |
| @comment node-name, next, previous, up |
| @appendixsec Titlepage Copying Permissions |
| @cindex Titlepage permissions |
| |
| In the @code{@@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:@refill |
| |
| @example |
| 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. |
| @end example |
| |
| @node Include Files, Headings, Sample Permissions, Top |
| @comment node-name, next, previous, up |
| @appendix Include Files |
| @cindex Include files |
| |
| 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 @sc{dvi} or Info file being |
| created. Index entries from the included file are incorporated into |
| the indices of the output file.@refill |
| |
| Include files let you keep a single large document as a collection of |
| conveniently small parts.@refill |
| |
| @menu |
| * 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 File Requirements:: What @code{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 @code{@@include} command |
| has changed over time. |
| @end menu |
| |
| @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files |
| @appendixsec How to Use Include Files |
| @findex include |
| |
| To include another file within a Texinfo file, write the |
| @code{@@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:@refill |
| |
| @example |
| @@include buffers.texi |
| @end 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.@refill |
| |
| 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.@refill |
| |
| 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.@refill |
| |
| @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files |
| @appendixsec @code{texinfo-multiple-files-update} |
| @findex texinfo-multiple-files-update |
| |
| 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 |
| |
| @table @kbd |
| @item M-x texinfo-multiple-files-update |
| Called without any arguments:@refill |
| |
| @itemize @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 file.@refill |
| |
| @item |
| Create or update the `Top' level node pointers of the outer or |
| overall file.@refill |
| |
| @item |
| Create or update a main menu in the outer file.@refill |
| @end itemize |
| |
| @item C-u M-x texinfo-multiple-files-update |
| Called with @kbd{C-u} as a prefix argument: |
| |
| @itemize @minus{} |
| @item |
| Create or update pointers in the first @code{@@node} line in each |
| included file. |
| |
| @item |
| Create or update the `Top' level node pointers of the outer file. |
| |
| @item |
| Create and insert a master menu in the outer file. The master menu |
| is made from all the menus in all the included files.@refill |
| @end itemize |
| |
| @item C-u 8 M-x texinfo-multiple-files-update |
| Called with a numeric prefix argument, such as @kbd{C-u 8}: |
| |
| @itemize @minus |
| @item |
| Create or update @strong{all} the `Next', `Previous', and `Up' pointers |
| of all the included files.@refill |
| |
| @item |
| Create or update @strong{all} the menus of all the included |
| files.@refill |
| |
| @item |
| Create or update the `Top' level node pointers of the outer or |
| overall file.@refill |
| |
| @item |
| 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.@refill |
| @end itemize |
| @end table |
| |
| Note the use of the prefix argument in interactive use: with a regular |
| prefix argument, just @w{@kbd{C-u}}, the |
| @code{texinfo-multiple-files-update} 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.@refill |
| |
| @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files |
| @appendixsec Include File Requirements |
| @cindex Include file requirements |
| @cindex 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.@refill |
| |
| 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 |
| @code{@@unnumbered} node. Thus, normally, each included file contains |
| one, and only one, chapter or equivalent-level node.@refill |
| |
| 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 |
| @code{texinfo-multiple-files-update} command will not process |
| them.@refill |
| |
| @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files |
| @appendixsec Sample File with @code{@@include} |
| @cindex Sample @code{@@include} file |
| @cindex Include file sample |
| @cindex @code{@@include} file sample |
| |
| Here is an example of a complete outer Texinfo file with @code{@@include} files |
| within it before running @code{texinfo-multiple-files-update}, which |
| would insert a main or master menu:@refill |
| |
| @example |
| @group |
| \input texinfo @@c -*-texinfo-*- |
| @c %**start of header |
| @@setfilename include-example.info |
| @@settitle Include Example |
| @c %**end of header |
| @end group |
| |
| @group |
| @@setchapternewpage odd |
| @@titlepage |
| @@sp 12 |
| @@center @@titlefont@{Include Example@} |
| @@sp 2 |
| @@center by Whom Ever |
| @end group |
| |
| @group |
| @@page |
| @@vskip 0pt plus 1filll |
| Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. |
| @@end titlepage |
| @end group |
| |
| @group |
| @@ifinfo |
| @@node Top, First, (dir), (dir) |
| @@top Master Menu |
| @@end ifinfo |
| @end group |
| |
| @group |
| @@include foo.texinfo |
| @@include bar.texinfo |
| @@include concept-index.texinfo |
| @end group |
| |
| @group |
| @@summarycontents |
| @@contents |
| |
| @@bye |
| @end group |
| @end example |
| |
| An included file, such as @file{foo.texinfo}, might look like |
| this:@refill |
| |
| @example |
| @group |
| @@node First, Second, , Top |
| @@chapter First Chapter |
| |
| Contents of first chapter @dots{} |
| @end group |
| @end example |
| |
| The full contents of @file{concept-index.texinfo} might be as simple as this: |
| |
| @example |
| @group |
| @@node Concept Index, , Second, Top |
| @@unnumbered Concept Index |
| |
| @@printindex cp |
| @end group |
| @end 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.@refill |
| |
| @node Include Files Evolution, , Sample Include File, Include Files |
| @comment node-name, next, previous, up |
| @appendixsec 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.@refill |
| |
| 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, , |
| @code{@@xref} with Four and Five Arguments}.)@refill |
| |
| 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 |
| @code{@@setfilename} line.)@refill |
| |
| However, because large Info files are now split automatically, it is |
| no longer necessary to keep them small.@refill |
| |
| 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.@refill |
| |
| 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.@refill |
| |
| @node Headings, Catching Mistakes, Include Files, Top |
| @comment node-name, next, previous, up |
| @appendix Page Headings |
| @cindex Headings |
| @cindex Footings |
| @cindex Page numbering |
| @cindex Page headings |
| @cindex Formatting headings and footings |
| |
| 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.)@refill |
| |
| @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. |
| @end menu |
| |
| @node Headings Introduced, Heading Format, Headings, Headings |
| @ifinfo |
| @heading Headings Introduced |
| @end ifinfo |
| |
| 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.@refill |
| |
| 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.@refill |
| |
| 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.@refill |
| |
| The @code{@@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.@refill |
| |
| 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.@refill |
| |
| @node Heading Format, Heading Choice, Headings Introduced, Headings |
| @comment node-name, next, previous, up |
| @appendixsec 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.@refill |
| |
| 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.@refill |
| |
| @need 950 |
| A single-sided page looks like this: |
| |
| @example |
| @group |
| _______________________ |
| | | |
| | chapter page number | |
| | | |
| | Start of text ... | |
| | ... | |
| | | |
| |
| @end group |
| @end example |
| |
| 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.)@refill |
| |
| 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 |
| @code{@@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.@refill |
| |
| @need 750 |
| Two pages, side by side as in an open book, look like this:@refill |
| |
| @example |
| @group |
| _______________________ _______________________ |
| | | | | |
| | page number title | | chapter page number | |
| | | | | |
| | Start of text ... | | More text ... | |
| | ... | | ... | |
| | | | | |
| |
| @end group |
| @end example |
| |
| @noindent |
| The chapter name is preceded by the word @samp{Chapter}, the chapter |
| number and a colon. This makes it easier to keep track of where you |
| are in the manual.@refill |
| |
| @node Heading Choice, Custom Headings, Heading Format, Headings |
| @comment node-name, next, previous, up |
| @appendixsec Specifying the Type of Heading |
| |
| @TeX{} does not begin to generate page headings for a standard Texinfo |
| file until it reaches the @code{@@end titlepage} command. Thus, the |
| title and copyright pages are not numbered. The @code{@@end |
| titlepage} command causes @TeX{} to begin to generate page headings |
| according to a standard format specified by the |
| @code{@@setchapternewpage} command that precedes the |
| @code{@@titlepage} section.@refill |
| |
| @need 1000 |
| There are four possibilities:@refill |
| |
| @table @asis |
| @item No @code{@@setchapternewpage} command |
| Cause @TeX{} to specify the single-sided heading format, with chapters |
| on new pages. This is the same as @code{@@setchapternewpage on}.@refill |
| |
| @item @code{@@setchapternewpage on} |
| Specify the single-sided heading format, with chapters on new pages.@refill |
| |
| @item @code{@@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 @code{@@headings double} command; see |
| @ref{headings on off, , The @code{@@headings} Command}.)@refill |
| |
| @item @code{@@setchapternewpage odd} |
| Specify the double-sided heading format, with chapters on new pages.@refill |
| @end table |
| |
| @noindent |
| Texinfo lacks an @code{@@setchapternewpage even} command.@refill |
| |
| @node Custom Headings, , Heading Choice, Headings |
| @comment node-name, next, previous, up |
| @appendixsec How to Make Your Own Headings |
| |
| You can use the standard headings provided with Texinfo or specify |
| your own.@refill |
| |
| @c Following paragraph is verbose to prevent overfull hboxes. |
| Texinfo provides six commands for specifying headings and |
| footings. The @code{@@everyheading} command and |
| @code{@@everyfooting} command generate page headers and footers |
| that are the same for both even- and odd-numbered pages. |
| The @code{@@evenheading} command and @code{@@evenfooting} |
| command generate headers and footers for even-numbered |
| (left-hand) pages; and the @code{@@oddheading} command and |
| @code{@@oddfooting} command generate headers and footers for |
| odd-numbered (right-hand) pages.@refill |
| |
| Write custom heading specifications in the Texinfo file immediately |
| after the @code{@@end titlepage} command. Enclose your specifications |
| between @code{@@iftex} and @code{@@end iftex} commands since the |
| @code{texinfo-format-buffer} command may not recognize them. Also, |
| you must cancel the predefined heading commands with the |
| @code{@@headings off} command before defining your own |
| specifications.@refill |
| |
| @need 1000 |
| 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:@refill |
| |
| @example |
| @group |
| @@iftex |
| @@headings off |
| @@everyheading @@thischapter @@| @@thispage @@| @@today@{@} |
| @@end iftex |
| @end group |
| @end example |
| |
| @noindent |
| You need to divide the left part from the central part and the central |
| part from the right had part by inserting @samp{@@|} between parts. |
| Otherwise, the specification command will not be able to tell where |
| the text for one part ends and the next part begins.@refill |
| |
| 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.@refill |
| |
| @need 950 |
| Here are the six heading and footing commands:@refill |
| |
| @findex everyheading |
| @findex everyfooting |
| @table @code |
| @item @@everyheading @var{left} @@| @var{center} @@| @var{right} |
| @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{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.@refill |
| |
| @findex evenheading |
| @findex evenfooting |
| @findex oddheading |
| @findex oddfooting |
| @item @@evenheading @var{left} @@| @var{center} @@| @var{right} |
| @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} |
| |
| @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} |
| @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{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.@refill |
| @end table |
| |
| Use the @samp{@@this@dots{}} series of @@-commands to |
| provide the names of chapters |
| and sections and the page number. You can use the |
| @samp{@@this@dots{}} 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 @code{@@iftex} and @code{@@end iftex} commands.@refill |
| |
| @need 1000 |
| Here are the @samp{@@this@dots{}} commands:@refill |
| |
| @table @code |
| @findex thispage |
| @item @@thispage |
| Expands to the current page number.@refill |
| @c !!! Karl Berry says that `thissection' fails on page breaks. |
| @ignore |
| @item @@thissection |
| Expands to the name of the current section.@refill |
| @end ignore |
| |
| @findex thischaptername |
| @item @@thischaptername |
| Expands to the name of the current chapter.@refill |
| |
| @findex thischapter |
| @item @@thischapter |
| Expands to the number and name of the current |
| chapter, in the format `Chapter 1: Title'.@refill |
| |
| @findex thistitle |
| @item @@thistitle |
| Expands to the name of the document, as specified by the |
| @code{@@settitle} command.@refill |
| |
| @findex thisfile |
| @item @@thisfile |
| For @code{@@include} files only: expands to the name of the current |
| @code{@@include} file. If the current Texinfo source file is not an |
| @code{@@include} file, this command has no effect. This command does |
| @emph{not} provide the name of the current Texinfo source file unless |
| it is an @code{@@include} file. (@xref{Include Files}, for more |
| information about @code{@@include} files.)@refill |
| @end table |
| |
| @noindent |
| You can also use the @code{@@today@{@}} command, which expands to the |
| current date, in `1 Jan 1900' format.@refill |
| @findex today |
| |
| 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:@refill |
| |
| @example |
| @group |
| @@iftex |
| @@headings off |
| @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter |
| @@everyfooting @@| @@| Version: 0.27: @@today@{@} |
| @@end iftex |
| @end group |
| @end example |
| |
| Beware of overlong titles: they may overlap another part of the |
| header or footer and blot it out.@refill |
| |
| @node Catching Mistakes, Refilling Paragraphs, Headings, Top |
| @comment node-name, next, previous, up |
| @appendix Formatting Mistakes |
| @cindex Structure, catching mistakes in |
| @cindex Nodes, catching mistakes |
| @cindex Catching mistakes |
| @cindex Correcting mistakes |
| @cindex Mistakes, catching |
| @cindex Problems, catching |
| @cindex Debugging the Texinfo structure |
| |
| 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.@refill |
| |
| Emacs has two tools for catching the @@-command mistakes and two for |
| catching structuring mistakes.@refill |
| |
| 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.@refill |
| |
| For finding problems with the structure of nodes and chapters, you can use |
| @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} |
| command and you can use the @kbd{M-x Info-validate} command.@refill |
| |
| @menu |
| * makeinfo preferred:: @code{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 @code{texinfo-show-structure}. |
| * Using occur:: How to list all lines containing a pattern. |
| * Running Info-Validate:: How to find badly referenced nodes. |
| @end menu |
| |
| @node makeinfo preferred, Debugging with Info, Catching Mistakes, Catching Mistakes |
| @ifinfo |
| @heading @code{makeinfo} Find Errors |
| @end ifinfo |
| |
| The @code{makeinfo} program does an excellent job of catching errors |
| and reporting them---far better than @code{texinfo-format-region} or |
| @code{texinfo-format-buffer}. In addition, the various functions for |
| automatically creating and updating node pointers and menus remove |
| many opportunities for human error.@refill |
| |
| If you can, use the updating commands to create and insert pointers |
| and menus. These prevent many errors. Then use @code{makeinfo} (or |
| its Texinfo mode manifestations, @code{makeinfo-region} and |
| @code{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 @code{makeinfo}, or your problem is very puzzling, then you |
| may want to use the tools described in this appendix.@refill |
| |
| @node Debugging with Info, Debugging with TeX, makeinfo preferred, Catching Mistakes |
| @comment node-name, next, previous, up |
| @appendixsec Catching Errors with Info Formatting |
| @cindex Catching errors with Info formatting |
| @cindex Debugging with Info formatting |
| |
| After you have written part of a Texinfo file, you can use the |
| @code{texinfo-format-region} or the @code{makeinfo-region} command to |
| see whether the region formats properly.@refill |
| |
| Most likely, however, you are reading this section because for some |
| reason you cannot use the @code{makeinfo-region} command; therefore, the |
| rest of this section presumes that you are using |
| @code{texinfo-format-region}.@refill |
| |
| If you have made a mistake with an @@-command, |
| @code{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 @samp{*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).@refill |
| |
| For example, if you accidentally end a menu with the command @code{@@end |
| menus} with an `s' on the end, instead of with @code{@@end menu}, you |
| will see an error message that says:@refill |
| |
| @example |
| @@end menus is not handled by texinfo |
| @end example |
| |
| @noindent |
| 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:@refill |
| |
| @example |
| @group |
| ---------- 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 |
| @point{} |
| ---------- Buffer: *Info Region* ---------- |
| @end group |
| @end example |
| |
| The @code{texinfo-format-region} command sometimes provides slightly |
| odd error messages. For example, the following cross reference fails to format:@refill |
| |
| @example |
| (@@xref@{Catching Mistakes, for more info.) |
| @end example |
| |
| @noindent |
| In this case, @code{texinfo-format-region} detects the missing closing |
| brace but displays a message that says @samp{Unbalanced parentheses} |
| rather than @samp{Unbalanced braces}. This is because the formatting |
| command looks for mismatches between braces as if they were |
| parentheses.@refill |
| |
| Sometimes @code{texinfo-format-region} fails to detect mistakes. For |
| example, in the following, the closing brace is swapped with the |
| closing parenthesis:@refill |
| |
| @example |
| (@@xref@{Catching Mistakes), for more info.@} |
| @end example |
| |
| @noindent |
| Formatting produces: |
| @example |
| (*Note for more info.: Catching Mistakes) |
| @end example |
| |
| The only way for you to detect this error is to realize that the |
| reference should have looked like this:@refill |
| |
| @example |
| (*Note Catching Mistakes::, for more info.) |
| @end example |
| |
| Incidentally, if you are reading this node in Info and type @kbd{f |
| @key{RET}} (@code{Info-follow-reference}), you will generate an error |
| message that says: |
| |
| @example |
| No such node: "Catching Mistakes) The only way @dots{} |
| @end example |
| |
| @noindent |
| This is because Info perceives the example of the error as the first |
| cross reference in this node and if you type a @key{RET} immediately |
| after typing the Info @kbd{f} command, Info will attempt to go to the |
| referenced node. If you type @kbd{f catch @key{TAB} @key{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 @kbd{l} |
| (@code{Info-last}).) |
| |
| @c !!! section on using Elisp debugger ignored. |
| @ignore |
| Sometimes @code{texinfo-format-region} will stop long after the |
| original error; this is because it does not discover the problem until |
| then. In this case, you will need to backtrack.@refill |
| |
| @c menu |
| @c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. |
| @c end menu |
| |
| @c node Using the Emacs Lisp Debugger |
| @c appendixsubsec Using the Emacs Lisp Debugger |
| @c index Using the Emacs Lisp debugger |
| @c index Emacs Lisp debugger |
| @c index Debugger, using the Emacs Lisp |
| |
| If an error is especially elusive, you can turn on the Emacs Lisp |
| debugger and look at the backtrace; this tells you where in the |
| @code{texinfo-format-region} function the problem occurred. You can |
| turn on the debugger with the command:@refill |
| |
| @example |
| M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} |
| @end example |
| |
| @noindent |
| and turn it off with |
| |
| @example |
| M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} |
| @end example |
| |
| Often, when you are using the debugger, it is easier to follow what is |
| going on if you use the Emacs Lisp files that are not byte-compiled. |
| The byte-compiled sources send octal numbers to the debugger that may |
| look mysterious. To use the uncompiled source files, load |
| @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} |
| command.@refill |
| |
| The debugger will not catch an error if @code{texinfo-format-region} |
| does not detect one. In the example shown above, |
| @code{texinfo-format-region} did not find the error when the whole |
| list was formatted, but only when part of the list was formatted. |
| When @code{texinfo-format-region} did not find an error, the debugger |
| did not find one either. @refill |
| |
| However, when @code{texinfo-format-region} did report an error, it |
| invoked the debugger. This is the backtrace it produced:@refill |
| |
| @example |
| ---------- Buffer: *Backtrace* ---------- |
| Signalling: (search-failed "[@},]") |
| re-search-forward("[@},]") |
| (while ...) |
| (let ...) |
| texinfo-format-parse-args() |
| (let ...) |
| texinfo-format-xref() |
| funcall(texinfo-format-xref) |
| (if ...) |
| (let ...) |
| (if ...) |
| (while ...) |
| texinfo-format-scan() |
| (save-excursion ...) |
| (let ...) |
| texinfo-format-region(103370 103631) |
| * call-interactively(texinfo-format-region) |
| ---------- Buffer: *Backtrace* ---------- |
| @end example |
| |
| The backtrace is read from the bottom up. |
| @code{texinfo-format-region} was called interactively; and it, in |
| turn, called various functions, including @code{texinfo-format-scan}, |
| @code{texinfo-format-xref} and @code{texinfo-format-parse-args}. |
| Inside the function @code{texinfo-format-parse-args}, the function |
| @code{re-search-forward} was called; it was this function that could |
| not find the missing right-hand brace.@refill |
| |
| @xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs |
| Manual}, for more information.@refill |
| @end ignore |
| |
| @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes |
| @comment node-name, next, previous, up |
| @appendixsec Catching Errors with @TeX{} Formatting |
| @cindex Catching errors with @TeX{} formatting |
| @cindex Debugging with @TeX{} formatting |
| |
| You can also catch mistakes when you format a file with @TeX{}.@refill |
| |
| Usually, you will want to do this after you have run |
| @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on |
| the same file, because @code{texinfo-format-buffer} sometimes displays |
| error messages that make more sense than @TeX{}. (@xref{Debugging |
| with Info}, for more information.)@refill |
| |
| For example, @TeX{} was run on a Texinfo file, part of which is shown |
| here:@refill |
| |
| @example |
| ---------- Buffer: texinfo.texi ---------- |
| name of the Texinfo file as an extension. The |
| @@samp@{??@} are `wildcards' that cause the shell to |
| substitute all the raw index files. (@@xref@{sorting |
| indices, for more information about sorting |
| indices.)@@refill |
| ---------- Buffer: texinfo.texi ---------- |
| @end example |
| |
| @noindent |
| (The cross reference lacks a closing brace.) |
| @TeX{} produced the following output, after which it stopped:@refill |
| |
| @example |
| ---------- Buffer: *tex-shell* ---------- |
| Runaway argument? |
| @{sorting indices, for more information about sorting |
| indices.) @@refill @@ETC. |
| ! Paragraph ended before @@xref was complete. |
| <to be read again> |
| @@par |
| l.27 |
| |
| ? |
| ---------- Buffer: *tex-shell* ---------- |
| @end example |
| |
| In this case, @TeX{} produced an accurate and |
| understandable error message: |
| |
| @example |
| Paragraph ended before @@xref was complete. |
| @end example |
| |
| @noindent |
| @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. |
| @samp{l.27} means that @TeX{} detected the problem on line 27 of the |
| Texinfo file. The @samp{?} is the prompt @TeX{} uses in this |
| circumstance.@refill |
| |
| Unfortunately, @TeX{} is not always so helpful, and sometimes you must |
| truly be a Sherlock Holmes to discover what went wrong.@refill |
| |
| In any case, if you run into a problem like this, you can do one of three |
| things.@refill |
| |
| @enumerate |
| @item |
| You can tell @TeX{} to continue running and ignore just this error by |
| typing @key{RET} at the @samp{?} prompt.@refill |
| |
| @item |
| You can tell @TeX{} to continue running and to ignore all errors as best |
| it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill |
| |
| This is often the best thing to do. However, beware: the one error |
| may produce a cascade of additional error messages as its consequences |
| are felt through the rest of the file. (To stop @TeX{} when it is |
| producing such an avalanche of error messages, type @kbd{C-d} (or |
| @kbd{C-c C-d}, if you are running a shell inside Emacs.))@refill |
| |
| @item |
| You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} |
| at the @samp{?} prompt.@refill |
| @end enumerate |
| |
| Please note that if you are running @TeX{} inside Emacs, you need to |
| switch to the shell buffer and line at which @TeX{} offers the @samp{?} |
| prompt.@refill |
| |
| Sometimes @TeX{} will format a file without producing error messages even |
| though there is a problem. This usually occurs if a command is not ended |
| but @TeX{} is able to continue processing anyhow. For example, if you fail |
| to end an itemized list with the @code{@@end itemize} command, @TeX{} will |
| write a @sc{dvi} file that you can print out. The only error message that |
| @TeX{} will give you is the somewhat mysterious comment that@refill |
| |
| @example |
| (@@end occurred inside a group at level 1) |
| @end example |
| |
| @noindent |
| However, if you print the @sc{dvi} file, you will find that the text |
| of the file that follows the itemized list is entirely indented as if |
| it were part of the last item in the itemized list. The error message |
| is the way @TeX{} says that it expected to find an @code{@@end} |
| command somewhere in the file; but that it could not determine where |
| it was needed.@refill |
| |
| Another source of notoriously hard-to-find errors is a missing |
| @code{@@end group} command. If you ever are stumped by |
| incomprehensible errors, look for a missing @code{@@end group} command |
| first.@refill |
| |
| If the Texinfo file lacks header lines, |
| @TeX{} may stop in the |
| beginning of its run and display output that looks like the following. |
| The @samp{*} indicates that @TeX{} is waiting for input.@refill |
| |
| @example |
| This is TeX, Version 3.14159 (Web2c 7.0) |
| (test.texinfo [1]) |
| * |
| @end example |
| |
| @noindent |
| In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then |
| write the header lines in the Texinfo file and run the @TeX{} command |
| again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} |
| instead of @samp{@@}; and in this circumstance, you are working |
| directly with @TeX{}, not with Texinfo.)@refill |
| |
| @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes |
| @comment node-name, next, previous, up |
| @appendixsec Using @code{texinfo-show-structure} |
| @cindex Showing the structure of a file |
| @findex texinfo-show-structure |
| |
| It is not always easy to keep track of the nodes, chapters, sections, and |
| subsections of a Texinfo file. This is especially true if you are revising |
| or adding to a Texinfo file that someone else has written.@refill |
| |
| In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} |
| command lists all the lines that begin with the @@-commands that |
| specify the structure: @code{@@chapter}, @code{@@section}, |
| @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} |
| as prefix argument, if interactive), |
| the command also shows the @code{@@node} lines. The |
| @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in |
| Texinfo mode, by default.@refill |
| |
| The lines are displayed in a buffer called the @samp{*Occur*} buffer, |
| indented by hierarchical level. For example, here is a part of what was |
| produced by running @code{texinfo-show-structure} on this manual:@refill |
| |
| @example |
| @group |
| Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| |
| unnum\\|major\\|chapheading \\|heading \\|appendix\\)" |
| in buffer texinfo.texi. |
| @dots{} |
| 4177:@@chapter Nodes |
| 4198: @@heading Two Paths |
| 4231: @@section Node and Menu Illustration |
| 4337: @@section The @@code@{@@@@node@} Command |
| 4393: @@subheading Choosing Node and Pointer Names |
| 4417: @@subsection How to Write an @@code@{@@@@node@} Line |
| 4469: @@subsection @@code@{@@@@node@} Line Tips |
| @dots{} |
| @end group |
| @end example |
| |
| This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin |
| with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} |
| commands respectively. If you move your cursor into the @samp{*Occur*} |
| window, you can position the cursor over one of the lines and use the |
| @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to |
| the corresponding spot in the Texinfo file. @xref{Other Repeating |
| Search, , Using Occur, emacs, The GNU Emacs Manual}, for more |
| information about @code{occur-mode-goto-occurrence}.@refill |
| |
| The first line in the @samp{*Occur*} window describes the @dfn{regular |
| expression} specified by @var{texinfo-heading-pattern}. This regular |
| expression is the pattern that @code{texinfo-show-structure} looks for. |
| @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, |
| for more information.@refill |
| |
| When you invoke the @code{texinfo-show-structure} command, Emacs will |
| display the structure of the whole buffer. If you want to see the |
| structure of just a part of the buffer, of one chapter, for example, |
| use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the |
| region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is |
| how the example used above was generated. (To see the whole buffer |
| again, use @kbd{C-x n w} (@code{widen}).)@refill |
| |
| If you call @code{texinfo-show-structure} with a prefix argument by |
| typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with |
| @code{@@node} as well as the lines beginning with the @@-sign commands |
| for @code{@@chapter}, @code{@@section}, and the like.@refill |
| |
| You can remind yourself of the structure of a Texinfo file by looking at |
| the list in the @samp{*Occur*} window; and if you have mis-named a node |
| or left out a section, you can correct the mistake.@refill |
| |
| @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes |
| @comment node-name, next, previous, up |
| @appendixsec Using @code{occur} |
| @cindex Occurrences, listing with @code{@@occur} |
| @findex occur |
| |
| Sometimes the @code{texinfo-show-structure} command produces too much |
| information. Perhaps you want to remind yourself of the overall structure |
| of a Texinfo file, and are overwhelmed by the detailed list produced by |
| @code{texinfo-show-structure}. In this case, you can use the @code{occur} |
| command directly. To do this, type@refill |
| |
| @example |
| @kbd{M-x occur} |
| @end example |
| |
| @noindent |
| and then, when prompted, type a @dfn{regexp}, a regular expression for |
| the pattern you want to match. (@xref{Regexps, , Regular Expressions, |
| emacs, The GNU Emacs Manual}.) The @code{occur} command works from |
| the current location of the cursor in the buffer to the end of the |
| buffer. If you want to run @code{occur} on the whole buffer, place |
| the cursor at the beginning of the buffer.@refill |
| |
| For example, to see all the lines that contain the word |
| @samp{@@chapter} in them, just type @samp{@@chapter}. This will |
| produce a list of the chapters. It will also list all the sentences |
| with @samp{@@chapter} in the middle of the line.@refill |
| |
| If you want to see only those lines that start with the word |
| @samp{@@chapter}, type @samp{^@@chapter} when prompted by |
| @code{occur}. If you want to see all the lines that end with a word |
| or phrase, end the last word with a @samp{$}; for example, |
| @samp{catching mistakes$}. This can be helpful when you want to see |
| all the nodes that are part of the same chapter or section and |
| therefore have the same `Up' pointer.@refill |
| |
| @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, |
| for more information.@refill |
| |
| @node Running Info-Validate, , Using occur, Catching Mistakes |
| @comment node-name, next, previous, up |
| @appendixsec Finding Badly Referenced Nodes |
| @findex Info-validate |
| @cindex Nodes, checking for badly referenced |
| @cindex Checking for badly referenced nodes |
| @cindex Looking for badly referenced nodes |
| @cindex Finding badly referenced nodes |
| @cindex Badly referenced nodes |
| |
| You can use the @code{Info-validate} command to check whether any of |
| the `Next', `Previous', `Up' or other node pointers fail to point to a |
| node. This command checks that every node pointer points to an |
| existing node. The @code{Info-validate} command works only on Info |
| files, not on Texinfo files.@refill |
| |
| The @code{makeinfo} program validates pointers automatically, so you |
| do not need to use the @code{Info-validate} command if you are using |
| @code{makeinfo}. You only may need to use @code{Info-validate} if you |
| are unable to run @code{makeinfo} and instead must create an Info file |
| using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or |
| if you write an Info file from scratch.@refill |
| |
| @menu |
| * Using Info-validate:: How to run @code{Info-validate}. |
| * Unsplit:: How to create an unsplit file. |
| * Tagifying:: How to tagify a file. |
| * Splitting:: How to split a file manually. |
| @end menu |
| |
| @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate |
| @appendixsubsec Running @code{Info-validate} |
| @cindex Running @code{Info-validate} |
| @cindex Info validating a large file |
| @cindex Validating a large file |
| |
| To use @code{Info-validate}, visit the Info file you wish to check and |
| type:@refill |
| |
| @example |
| M-x Info-validate |
| @end example |
| |
| @noindent |
| (Note that the @code{Info-validate} command requires an upper case |
| `I'. You may also need to create a tag table before running |
| @code{Info-validate}. @xref{Tagifying}.)@refill |
| |
| If your file is valid, you will receive a message that says ``File appears |
| valid''. However, if you have a pointer that does not point to a node, |
| error messages will be displayed in a buffer called @samp{*problems in |
| info file*}.@refill |
| |
| For example, @code{Info-validate} was run on a test file that contained |
| only the first node of this manual. One of the messages said:@refill |
| |
| @example |
| In node "Overview", invalid Next: Texinfo Mode |
| @end example |
| |
| @noindent |
| This meant that the node called @samp{Overview} had a `Next' pointer that |
| did not point to anything (which was true in this case, since the test file |
| had only one node in it).@refill |
| |
| Now suppose we add a node named @samp{Texinfo Mode} to our test case |
| but we do not specify a `Previous' for this node. Then we will get |
| the following error message:@refill |
| |
| @example |
| In node "Texinfo Mode", should have Previous: Overview |
| @end example |
| |
| @noindent |
| This is because every `Next' pointer should be matched by a |
| `Previous' (in the node where the `Next' points) which points back.@refill |
| |
| @code{Info-validate} also checks that all menu entries and cross references |
| point to actual nodes.@refill |
| |
| Note that @code{Info-validate} requires a tag table and does not work |
| with files that have been split. (The @code{texinfo-format-buffer} |
| command automatically splits large files.) In order to use |
| @code{Info-validate} on a large file, you must run |
| @code{texinfo-format-buffer} with an argument so that it does not split |
| the Info file; and you must create a tag table for the unsplit |
| file.@refill |
| |
| @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate |
| @comment node-name, next, previous, up |
| @appendixsubsec Creating an Unsplit File |
| @cindex Creating an unsplit file |
| @cindex Unsplit file creation |
| |
| You can run @code{Info-validate} only on a single Info file that has a |
| tag table. The command will not work on the indirect subfiles that |
| are generated when a master file is split. If you have a large file |
| (longer than 70,000 bytes or so), you need to run the |
| @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such |
| a way that it does not create indirect subfiles. You will also need |
| to create a tag table for the Info file. After you have done this, |
| you can run @code{Info-validate} and look for badly referenced |
| nodes.@refill |
| |
| The first step is to create an unsplit Info file. To prevent |
| @code{texinfo-format-buffer} from splitting a Texinfo file into |
| smaller Info files, give a prefix to the @kbd{M-x |
| texinfo-format-buffer} command:@refill |
| |
| @example |
| C-u M-x texinfo-format-buffer |
| @end example |
| |
| @noindent |
| or else |
| |
| @example |
| C-u C-c C-e C-b |
| @end example |
| |
| @noindent |
| When you do this, Texinfo will not split the file and will not create |
| a tag table for it. @refill |
| @cindex Making a tag table manually |
| @cindex Tag table, making manually |
| |
| @node Tagifying, Splitting, Unsplit, Running Info-Validate |
| @appendixsubsec Tagifying a File |
| |
| After creating an unsplit Info file, you must create a tag table for |
| it. Visit the Info file you wish to tagify and type:@refill |
| |
| @example |
| M-x Info-tagify |
| @end example |
| |
| @noindent |
| (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an |
| Info file with a tag table that you can validate.@refill |
| |
| The third step is to validate the Info file:@refill |
| |
| @example |
| M-x Info-validate |
| @end example |
| |
| @noindent |
| (Note the upper case @samp{I} in @code{Info-validate}.) |
| In brief, the steps are:@refill |
| |
| @example |
| @group |
| C-u M-x texinfo-format-buffer |
| M-x Info-tagify |
| M-x Info-validate |
| @end group |
| @end example |
| |
| After you have validated the node structure, you can rerun |
| @code{texinfo-format-buffer} in the normal way so it will construct a |
| tag table and split the file automatically, or you can make the tag |
| table and split the file manually.@refill |
| |
| @node Splitting, , Tagifying, Running Info-Validate |
| @comment node-name, next, previous, up |
| @appendixsubsec Splitting a File Manually |
| @cindex Splitting an Info file manually |
| @cindex Info file, splitting manually |
| |
| You should split a large file or else let the |
| @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it |
| for you automatically. (Generally you will let one of the formatting |
| commands do this job for you. @xref{Create an Info File}.)@refill |
| |
| The split-off files are called the indirect subfiles.@refill |
| |
| Info files are split to save memory. With smaller files, Emacs does not |
| have make such a large buffer to hold the information.@refill |
| |
| If an Info file has more than 30 nodes, you should also make a tag |
| table for it. @xref{Using Info-validate}, for information |
| about creating a tag table. (Again, tag tables are usually created |
| automatically by the formatting command; you only need to create a tag |
| table yourself if you are doing the job manually. Most likely, you |
| will do this for a large, unsplit file on which you have run |
| @code{Info-validate}.)@refill |
| |
| @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 |
| @ignore |
| Before running @code{Info-split}, you need to load the @code{info} library |
| into Emacs by giving the command @kbd{M-x load-library @key{RET} info |
| @key{RET}}. |
| @end ignore |
| |
| Visit the Info file you wish to tagify and split and type the two |
| commands:@refill |
| |
| @example |
| M-x Info-tagify |
| M-x Info-split |
| @end example |
| |
| @noindent |
| (Note that the @samp{I} in @samp{Info} is upper case.)@refill |
| |
| When you use the @code{Info-split} command, the buffer is modified into a |
| (small) Info file which lists the indirect subfiles. This file should be |
| saved in place of the original visited file. The indirect subfiles are |
| written in the same directory the original file is in, with names generated |
| by appending @samp{-} and a number to the original file name.@refill |
| |
| The primary file still functions as an Info file, but it contains just |
| the tag table and a directory of subfiles.@refill |
| |
| @node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top |
| @comment node-name, next, previous, up |
| @appendix Refilling Paragraphs |
| @cindex Refilling paragraphs |
| @cindex Filling paragraphs |
| @findex refill |
| |
| The @code{@@refill} command refills and, optionally, indents the first |
| line of a paragraph.@footnote{Perhaps the command should have been |
| called the @code{@@refillandindent} command, but @code{@@refill} is |
| shorter and the name was chosen before indenting was possible.} The |
| @code{@@refill} command is no longer important, but we describe it here |
| because you once needed it. You will see it in many old Texinfo |
| files.@refill |
| |
| Without refilling, paragraphs containing long @@-constructs may look |
| bad after formatting because the formatter removes @@-commands and |
| shortens some lines more than others. In the past, neither the |
| @code{texinfo-format-region} command nor the |
| @code{texinfo-format-buffer} command refilled paragraphs |
| automatically. The @code{@@refill} command had to be written at the |
| end of every paragraph to cause these formatters to fill them. (Both |
| @TeX{} and @code{makeinfo} have always refilled paragraphs |
| automatically.) Now, all the Info formatters automatically fill and |
| indent those paragraphs that need to be filled and indented.@refill |
| |
| The @code{@@refill} command causes @code{texinfo-format-region} and |
| @code{texinfo-format-buffer} to refill a paragraph in the Info file |
| @emph{after} all the other processing has been done. For this reason, |
| you can not use @code{@@refill} with a paragraph containing either |
| @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will |
| override those two commands.@refill |
| |
| The @code{texinfo-format-region} and @code{texinfo-format-buffer} |
| commands now automatically append @code{@@refill} to the end of each |
| paragraph that should be filled. They do not append @code{@@refill} to |
| the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} |
| and therefore do not refill or indent them.@refill |
| |
| @node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top |
| @comment node-name, next, previous, up |
| @appendix @@-Command Syntax |
| @cindex @@-command syntax |
| |
| The character @samp{@@} is used to start special Texinfo commands. |
| (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo |
| has four types of @@-command:@refill |
| |
| @table @asis |
| @item 1. Non-alphabetic commands. |
| These commands consist of an @@ followed by a punctuation mark or other |
| character that is not part of the alphabet. Non-alphabetic commands |
| are almost always part of the text within a paragraph, and never take |
| any argument. The two characters (@@ and the other one) are complete |
| in themselves; none is followed by braces. The non-alphabetic |
| commands are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@@}, |
| @code{@@@{}, and @code{@@@}}.@refill |
| |
| @item 2. Alphabetic commands that do not require arguments. |
| These commands start with @@ followed by a word followed by left- and |
| right-hand braces. These commands insert special symbols in the |
| document; they do not require arguments. For example, |
| @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} |
| @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', |
| and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill |
| |
| @item 3. Alphabetic commands that require arguments within braces. |
| These commands start with @@ followed by a letter or a word, followed by an |
| argument within braces. For example, the command @code{@@dfn} indicates |
| the introductory or defining use of a term; it is used as follows: @samp{In |
| Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill |
| |
| @item 4. Alphabetic commands that occupy an entire line. |
| These commands occupy an entire line. The line starts with @@, |
| followed by the name of the command (a word); for example, @code{@@center} |
| or @code{@@cindex}. If no argument is needed, the word is followed by |
| the end of the line. If there is an argument, it is separated from |
| the command name by a space. Braces are not used.@refill |
| @end table |
| |
| @cindex Braces and argument syntax |
| Thus, the alphabetic commands fall into classes that have |
| different argument syntaxes. You cannot tell to which class a command |
| belongs by the appearance of its name, but you can tell by the |
| command's meaning: if the command stands for a glyph, it is in |
| class 2 and does not require an argument; if it makes sense to use the |
| command together with other text as part of a paragraph, the command |
| is in class 3 and must be followed by an argument in braces; |
| otherwise, it is in class 4 and uses the rest of the line as its |
| argument.@refill |
| |
| The purpose of having a different syntax for commands of classes 3 and |
| 4 is to make Texinfo files easier to read, and also to help the GNU |
| Emacs paragraph and filling commands work properly. There is only one |
| exception to this rule: the command @code{@@refill}, which is always |
| used at the end of a paragraph immediately following the final period |
| or other punctuation character. @code{@@refill} takes no argument and |
| does @emph{not} require braces. @code{@@refill} never confuses the |
| Emacs paragraph commands because it cannot appear at the beginning of |
| a line.@refill |
| |
| @node Obtaining TeX, New Features, Command Syntax, Top |
| @appendix How to Obtain @TeX{} |
| @cindex Obtaining @TeX{} |
| @cindex @TeX{}, how to obtain |
| |
| @c !!! Here is information about obtaining TeX. Update it whenever. |
| @c !!! Also consider updating TeX.README on prep. |
| @c Updated by RJC on 1 March 1995, conversation with MacKay. |
| @c Updated by kb@cs.umb.edu on 29 July 1996. |
| @TeX{} is freely redistributable. You can obtain @TeX{} for Unix |
| systems via anonymous ftp or on tape or CD-ROM. The core material |
| consists of Karl Berry's Web2c @TeX{} distribution. |
| |
| On-line retrieval instructions are available from either: |
| @example |
| @url{ftp://ftp.tug.org/tex/unixtex.ftp} |
| @url{http://www.tug.org/unixtex.ftp} |
| @end example |
| |
| The Free Software Foundation provides a core distribution on its Source |
| Code CD-ROM suitable for printing Texinfo manuals; the University of |
| Washington maintains and supports a tape distribution; the @TeX{} Users |
| Group co-sponsors a complete CD-ROM @TeX{} distribution. |
| |
| For the FSF Source Code CD-ROM, please contact: |
| |
| @iftex |
| @display |
| @group |
| Free Software Foundation, Inc. |
| 59 Temple Place Suite 330 |
| Boston, MA w{ } 02111-1307 |
| USA |
| |
| Telephone: @w{@t{+}1--617--542--5942} |
| Fax: (including Japan) @w{@t{+}1--617--542--2652} |
| Free Dial Fax (in Japan): |
| @w{ } @w{ } @w{ } 0031--13--2473 (KDD) |
| @w{ } @w{ } @w{ } 0066--3382--0158 (IDC) |
| Electronic mail: @code{gnu@@prep.ai.mit.edu} |
| @end group |
| @end display |
| @end iftex |
| @ifinfo |
| @display |
| @group |
| Free Software Foundation, Inc. |
| 59 Temple Place Suite 330 |
| Boston, MA @w{ } 02111-1307 |
| USA |
| |
| Telephone: @w{@t{+}1-617-542-5942} |
| Fax: (including Japan) @w{@t{+}1-617-542-2652} |
| Free Dial Fax (in Japan): |
| @w{ } @w{ } @w{ } 0031-13-2473 (KDD) |
| @w{ } @w{ } @w{ } 0066-3382-0158 (IDC) |
| Electronic mail: @code{gnu@@prep.ai.mit.edu} |
| @end group |
| @end display |
| @end ifinfo |
| |
| To order a full distribution on CD-ROM, please see: |
| @display |
| @url{http://www.tug.org/tex-live.html} |
| @end display |
| |
| @noindent |
| (The distribution is also available by FTP; see the URL's above.) |
| |
| To order a full distribution from the University of Washington on either a |
| 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge, send |
| $210 to: |
| |
| @display |
| @group |
| Pierre A. MacKay |
| Denny Hall, Mail Stop DH-10 |
| University of Washington |
| Seattle, WA @w{ } 98195 |
| USA |
| |
| Telephone: @t{+}1--206--543--2268 |
| Electronic mail: @code{mackay@@cs.washington.edu} |
| @end group |
| @end display |
| |
| Please make checks payable to the University of Washington. |
| Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. |
| |
| Prepaid orders are the only orders that can now be handled. Overseas |
| sites: please add to the base cost, if desired, $20.00 for shipment |
| via air parcel post, or $30.00 for shipment via courier. |
| |
| Please check with the above for current prices and formats. |
| |
| |
| @node New Features, Command and Variable Index, Obtaining TeX, Top |
| @appendix Second Edition Features |
| |
| @tex |
| % Widen the space for the first column so three control-character |
| % strings fit in the first column. Switched back to default .8in |
| % value at end of chapter. |
| \global\tableindent=1.0in |
| @end tex |
| |
| The second edition of the Texinfo manual describes more than 20 new |
| Texinfo mode commands and more than 50 previously undocumented Texinfo |
| @@-commands. This edition is more than twice the length of the first |
| edition.@refill |
| |
| Here is a brief description of the new commands.@refill |
| |
| @menu |
| * New Texinfo Mode Commands:: The updating commands are especially useful. |
| * New Commands:: Many newly described @@-commands. |
| @end menu |
| |
| @node New Texinfo Mode Commands, New Commands, New Features, New Features |
| @appendixsec New Texinfo Mode Commands |
| |
| Texinfo mode provides commands and features especially designed for |
| working with Texinfo files. More than 20 new commands have been |
| added, including commands for automatically creating and updating |
| both nodes and menus. This is a tedious task when done by hand.@refill |
| |
| The keybindings are intended to be somewhat mnemonic.@refill |
| |
| @subheading Update all nodes and menus |
| |
| The @code{texinfo-master-menu} command is the primary command: |
| |
| @table @kbd |
| @item C-c C-u m |
| @itemx M-x texinfo-master-menu |
| Create or update a master menu. |
| With @kbd{C-u} as a prefix argument, |
| first create or update all nodes |
| and regular menus. |
| @end table |
| |
| @subheading Update Pointers |
| |
| @noindent |
| Create or update `Next', `Previous', and `Up' node pointers.@refill |
| |
| @noindent |
| @xref{Updating Nodes and Menus}. |
| |
| @table @kbd |
| @item C-c C-u C-n |
| @itemx M-x texinfo-update-node |
| Update a node. |
| |
| @item C-c C-u C-e |
| @itemx M-x texinfo-every-node-update |
| Update every node in the buffer. |
| @end table |
| |
| @subheading Update Menus |
| |
| @noindent |
| Create or update menus.@refill |
| |
| @noindent |
| @xref{Updating Nodes and Menus}. |
| |
| @table @kbd |
| @item C-c C-u C-m |
| @itemx M-x texinfo-make-menu |
| Make or update a menu. |
| |
| @item C-c C-u C-a |
| @itemx M-x texinfo-all-menus-update |
| Make or update all the menus in a buffer. |
| With @kbd{C-u} as a prefix argument, |
| first update all the nodes. |
| @end table |
| |
| @subheading Insert Title as Description |
| |
| @noindent |
| Insert a node's chapter or section title in the space for the |
| description in a menu entry line; position point so you can edit the |
| insert. (This command works somewhat differently than the other |
| insertion commands, which insert only a predefined string.)@refill |
| |
| @noindent |
| @xref{Inserting, Inserting Frequently Used Commands}. |
| |
| @table @kbd |
| @item C-c C-c C-d |
| Insert title. |
| @end table |
| |
| @subheading Format for Info |
| |
| @noindent |
| Provide keybindings both for the Info formatting commands that are |
| written in Emacs Lisp and for @code{makeinfo} that is written in |
| C.@refill |
| |
| @noindent |
| @xref{Info Formatting}. |
| |
| @noindent |
| Use the Emacs lisp @code{texinfo-format@dots{}} commands: |
| |
| @table @kbd |
| @item C-c C-e C-r |
| Format the region. |
| |
| @item C-c C-e C-b |
| Format the buffer. |
| @end table |
| |
| @noindent |
| Use @code{makeinfo}: |
| |
| @table @kbd |
| @item C-c C-m C-r |
| Format the region. |
| |
| @item C-c C-m C-b |
| Format the buffer. |
| |
| @item C-c C-m C-l |
| Recenter the @code{makeinfo} output buffer. |
| |
| @item C-c C-m C-k |
| Kill the @code{makeinfo} formatting job. |
| @end table |
| |
| @subheading Typeset and Print |
| |
| @noindent |
| Typeset and print Texinfo documents from within Emacs.@refill |
| |
| @ifinfo |
| @noindent |
| @xref{Printing}. |
| @end ifinfo |
| @iftex |
| @noindent |
| @xref{Printing, , Formatting and Printing}. |
| @end iftex |
| |
| @table @kbd |
| @item C-c C-t C-b |
| Run @code{texi2dvi} on the buffer. |
| |
| @item C-c C-t C-r |
| Run @TeX{} on the region. |
| |
| @item C-c C-t C-i |
| Run @code{texindex}. |
| |
| @item C-c C-t C-p |
| Print the @sc{dvi} file. |
| |
| @item C-c C-t C-q |
| Show the print queue. |
| |
| @item C-c C-t C-d |
| Delete a job from the print queue. |
| |
| @item C-c C-t C-k |
| Kill the current @TeX{} formatting job. |
| |
| @item C-c C-t C-x |
| Quit a currently stopped @TeX{} formatting job. |
| |
| @item C-c C-t C-l |
| Recenter the output buffer. |
| @end table |
| |
| @subheading Other Updating Commands |
| |
| @noindent |
| The ``other updating commands'' do not have standard keybindings because |
| they are used less frequently.@refill |
| |
| @noindent |
| @xref{Other Updating Commands}. |
| |
| @table @kbd |
| @item M-x texinfo-insert-node-lines |
| Insert missing @code{@@node} lines using |
| section titles as node names. |
| |
| @item M-x texinfo-multiple-files-update |
| Update a multi-file document. |
| With a numeric prefix, such as @kbd{C-u 8}, |
| update @strong{every} pointer and |
| menu in @strong{all} the files and |
| then insert a master menu. |
| |
| @item M-x texinfo-indent-menu-description |
| Indent descriptions in menus. |
| |
| @item M-x texinfo-sequential-node-update |
| Insert node pointers in strict sequence. |
| @end table |
| |
| @node New Commands, , New Texinfo Mode Commands, New Features |
| @appendixsec New Texinfo @@-Commands |
| |
| The second edition of the Texinfo manual describes more than 50 |
| commands that were not described in the first edition. A third or so |
| of these commands existed in Texinfo but were not documented in the |
| manual; the others are new. Here is a listing, with brief |
| descriptions of them:@refill |
| |
| @subheading Indexing |
| |
| @noindent |
| Create your own index, and merge indices.@refill |
| |
| @noindent |
| @xref{Indices}. |
| |
| @table @kbd |
| @item @@defindex @var{index-name} |
| Define a new index and its indexing command. |
| See also the @code{@@defcodeindex} command. |
| |
| @c written verbosely to avoid overfull hbox |
| @item @@synindex @var{from-index} @var{into-index} |
| Merge the @var{from-index} index into the @var{into-index} index. |
| See also the @code{@@syncodeindex} command. |
| @end table |
| |
| @subheading Definitions |
| |
| @noindent |
| Describe functions, variables, macros, |
| commands, user options, special forms, and other such artifacts in a |
| uniform format.@refill |
| |
| @noindent |
| @xref{Definition Commands}. |
| |
| @table @kbd |
| @item @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| Format a description for functions, interactive |
| commands, and similar entities. |
| |
| @item @@defvr, @@defop, @dots{} |
| 15 other related commands. |
| @end table |
| |
| @subheading Glyphs |
| |
| @noindent |
| Indicate the results of evaluation, expansion, |
| printed output, an error message, equivalence of expressions, and the |
| location of point.@refill |
| |
| @noindent |
| @xref{Glyphs}. |
| |
| @table @kbd |
| @item @@equiv@{@} |
| @itemx @equiv{} |
| Equivalence: |
| |
| @item @@error@{@} |
| @itemx @error{} |
| Error message |
| |
| @item @@expansion@{@} |
| @itemx @expansion{} |
| Macro expansion |
| |
| @item @@point@{@} |
| @itemx @point{} |
| Position of point |
| |
| @item @@print@{@} |
| @itemx @print{} |
| Printed output |
| |
| @item @@result@{@} |
| @itemx @result{} |
| Result of an expression |
| @end table |
| |
| @subheading Page Headings |
| |
| @noindent |
| Customize page headings. |
| |
| @noindent |
| @xref{Headings}. |
| |
| @table @kbd |
| @item @@headings @var{on-off-single-double} |
| Headings on or off, single, or double-sided. |
| |
| @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| Footings for even-numbered (left-hand) pages. |
| |
| @item @@evenheading, @@everyheading, @@oddheading, @dots{} |
| Five other related commands. |
| |
| @item @@thischapter |
| Insert name of chapter and chapter number. |
| |
| @item @@thischaptername, @@thisfile, @@thistitle, @@thispage |
| Related commands. |
| @end table |
| |
| @subheading Formatting |
| |
| @noindent |
| Format blocks of text. |
| |
| @noindent |
| @xref{Quotations and Examples}, and@* |
| @ref{Lists and Tables, , Making Lists and Tables}. |
| |
| @table @kbd |
| @item @@cartouche |
| Draw rounded box surrounding text (not in Info). |
| |
| @item @@enumerate @var{optional-arg} |
| Enumerate a list with letters or numbers. |
| |
| @item @@exdent @var{line-of-text} |
| Remove indentation. |
| |
| @item @@flushleft |
| Left justify. |
| |
| @item @@flushright |
| Right justify. |
| |
| @item @@format |
| Do not narrow nor change font. |
| |
| @item @@ftable @var{formatting-command} |
| @itemx @@vtable @var{formatting-command} |
| Two-column table with indexing. |
| |
| @item @@lisp |
| For an example of Lisp code. |
| |
| @item @@smallexample |
| @itemx @@smalllisp |
| Like @@table and @@lisp @r{but for} @@smallbook. |
| @end table |
| |
| @subheading Conditionals |
| |
| @noindent |
| Conditionally format text. |
| |
| @noindent |
| @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill |
| |
| @table @kbd |
| @item @@set @var{flag} [@var{string}] |
| Set a flag. Optionally, set value |
| of @var{flag} to @var{string}. |
| |
| @item @@clear @var{flag} |
| Clear a flag. |
| |
| @item @@value@{@var{flag}@} |
| Replace with value to which @var{flag} is set. |
| |
| @item @@ifset @var{flag} |
| Format, if @var{flag} is set. |
| |
| @item @@ifclear @var{flag} |
| Ignore, if @var{flag} is set. |
| @end table |
| |
| @subheading @@heading series for Titles |
| |
| @noindent |
| Produce unnumbered headings that do not appear in a table of contents. |
| |
| @noindent |
| @xref{Structuring}. |
| |
| @table @kbd |
| @item @@heading @var{title} |
| Unnumbered section-like heading not listed |
| in the table of contents of a printed manual. |
| |
| @item @@chapheading, @@majorheading, @@subheading, @@subsubheading |
| Related commands. |
| @end table |
| |
| @need 1000 |
| @subheading Font commands |
| |
| @need 1000 |
| @noindent |
| @xref{Smallcaps}, and @* |
| @ref{Fonts}. |
| |
| @table @kbd |
| @item @@r@{@var{text}@} |
| Print in roman font. |
| |
| @item @@sc@{@var{text}@} |
| Print in @sc{small caps} font. |
| @end table |
| |
| @subheading Miscellaneous |
| |
| @noindent |
| See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* |
| see @ref{Customized Highlighting},@* |
| see @ref{Overfull hboxes},@* |
| see @ref{Footnotes},@* |
| see @ref{dmn, , Format a Dimension},@* |
| see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* |
| see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* |
| see @ref{minus, , Inserting a Minus Sign},@* |
| see @ref{paragraphindent, , Paragraph Indenting},@* |
| see @ref{Cross Reference Commands},@* |
| see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* |
| see @ref{Custom Headings, , How to Make Your Own Headings}. |
| |
| @table @kbd |
| @item @@author @var{author} |
| Typeset author's name. |
| |
| @ignore |
| @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, |
| Define a highlighting command for Info. (Info only.) |
| @end ignore |
| |
| @item @@finalout |
| Produce cleaner printed output. |
| |
| @item @@footnotestyle @var{end-or-separate} |
| Specify footnote style. |
| |
| @item @@dmn@{@var{dimension}@} |
| Format a dimension. |
| |
| @item @@global@@let@var{new-cmd}=@var{existing-cmd} |
| Define a highlighting command for @TeX{}. (@TeX{} only.) |
| |
| @item @@lowersections |
| Reduce hierarchical level of sectioning commands. |
| |
| @item @@math@{@var{mathematical-expression}@} |
| Format a mathematical expression. |
| |
| @item @@minus@{@} |
| Generate a minus sign. |
| |
| @item @@paragraphindent @var{asis-or-number} |
| Specify paragraph indentation. |
| |
| @item @@raisesections |
| Raise hierarchical level of sectioning commands. |
| |
| @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} |
| Make a reference. In the printed manual, the |
| reference does not start with the word `see'. |
| |
| @item @@title @var{title} |
| Typeset @var{title} in the alternative |
| title page format. |
| |
| @item @@subtitle @var{subtitle} |
| Typeset @var{subtitle} in the alternative |
| title page format. |
| |
| @item @@today@{@} |
| Insert the current date. |
| @end table |
| @tex |
| % Switch width of first column of tables back to default value |
| \global\tableindent=.8in |
| @end tex |
| |
| |
| @node Command and Variable Index, Concept Index, New Features, Top |
| @comment node-name, next, previous, up |
| @unnumbered Command and Variable Index |
| |
| This is an alphabetical list of all the @@-commands, assorted Emacs Lisp |
| functions, and several variables. To make the list easier to use, the |
| commands are listed without their preceding @samp{@@}.@refill |
| |
| @printindex fn |
| |
| |
| @node Concept Index, , Command and Variable Index, Top |
| @unnumbered Concept Index |
| |
| @printindex cp |
| |
| |
| @summarycontents |
| @contents |
| @bye |