Short Contents ************** Texinfo Texinfo Copying Conditions 1 Overview of Texinfo 2 Using Texinfo Mode 3 Beginning a Texinfo File 4 Ending a Texinfo File 5 Chapter Structuring 6 Nodes 7 Menus 8 Cross References 9 Marking Words and Phrases 10 Quotations and Examples 11 Lists and Tables 12 Special Displays 13 Indices 14 Special Insertions 15 Forcing and Preventing Breaks 16 Definition Commands 17 Conditionally Visible Text 18 Internationalization 19 Defining New Texinfo Commands 20 Formatting and Printing Hardcopy 21 Creating and Installing Info Files 22 Generating HTML Appendix A @-Command List Appendix B Tips and Hints Appendix C Sample Texinfo Files Appendix D Include Files Appendix E Page Headings Appendix F Formatting Mistakes Appendix G GNU Free Documentation License Command and Variable Index General Index Table of Contents ***************** Texinfo Texinfo Copying Conditions 1 Overview of Texinfo 1.1 Reporting Bugs 1.2 Using Texinfo 1.3 Output Formats 1.4 Info Files 1.5 Printed Books 1.6 @-commands 1.7 General Syntactic Conventions 1.8 Comments 1.9 What a Texinfo File Must Have 1.10 Six Parts of a Texinfo File 1.11 A Short Sample Texinfo File 1.12 History 2 Using Texinfo Mode 2.1 Texinfo Mode Overview 2.2 The Usual GNU Emacs Editing Commands 2.3 Inserting Frequently Used Commands 2.4 Showing the Section Structure of a File 2.5 Updating Nodes and Menus 2.5.1 The Updating Commands 2.5.2 Updating Requirements 2.5.3 Other Updating Commands 2.6 Formatting for Info 2.7 Printing 2.8 Texinfo Mode Summary 3 Beginning a Texinfo File 3.1 Sample Texinfo File Beginning 3.2 Texinfo File Header 3.2.1 The First Line of a Texinfo File 3.2.2 Start of Header 3.2.3 `@setfilename': Set the output file name 3.2.4 `@settitle': Set the document title 3.2.5 End of Header 3.3 Document Permissions 3.3.1 `@copying': Declare Copying Permissions 3.3.2 `@insertcopying': Include Permissions Text 3.4 Title and Copyright Pages 3.4.1 `@titlepage' 3.4.2 `@titlefont', `@center', and `@sp' 3.4.3 `@title', `@subtitle', and `@author' 3.4.4 Copyright Page 3.4.5 Heading Generation 3.4.6 The `@headings' Command 3.5 Generating a Table of Contents 3.6 The `Top' Node and Master Menu 3.6.1 Top Node Example 3.6.2 Parts of a Master Menu 3.7 Global Document Commands 3.7.1 `@documentdescription': Summary Text 3.7.2 `@setchapternewpage': 3.7.3 `@paragraphindent': Paragraph Indenting 3.7.4 `@firstparagraphindent': Indenting After Headings 3.7.5 `@exampleindent': Environment Indenting 3.8 Software Copying Permissions 4 Ending a Texinfo File 4.1 Printing Indices and Menus 4.2 `@bye' File Ending 5 Chapter Structuring 5.1 Tree Structure of Sections 5.2 Structuring Command Types 5.3 `@top' 5.4 `@chapter' 5.5 `@unnumbered' and `@appendix' 5.6 `@majorheading', `@chapheading' 5.7 `@section' 5.8 `@unnumberedsec', `@appendixsec', `@heading' 5.9 The `@subsection' Command 5.10 The `@subsection'-like Commands 5.11 The `subsub' Commands 5.12 `@raisesections' and `@lowersections' 6 Nodes 6.1 Two Paths 6.2 Node and Menu Illustration 6.3 The `@node' Command 6.3.1 Choosing Node and Pointer Names 6.3.2 How to Write an `@node' Line 6.3.3 `@node' Line Tips 6.3.4 `@node' Line Requirements 6.3.5 The First Node 6.3.6 The `@top' Sectioning Command 6.4 Creating Pointers with `makeinfo' 6.5 `@anchor': Defining Arbitrary Cross-reference Targets 7 Menus 7.1 Menu Location 7.2 Writing a Menu 7.3 The Parts of a Menu 7.4 Less Cluttered Menu Entry 7.5 A Menu Example 7.6 Referring to Other Info Files 8 Cross References 8.1 What References Are For 8.2 Different Cross Reference Commands 8.3 Parts of a Cross Reference 8.4 `@xref' 8.4.1 What a Reference Looks Like and Requires 8.4.2 `@xref' with One Argument 8.4.3 `@xref' with Two Arguments 8.4.4 `@xref' with Three Arguments 8.4.5 `@xref' with Four and Five Arguments 8.5 Naming a `Top' Node 8.6 `@ref' 8.7 `@pxref' 8.8 `@inforef' 8.9 `@url', `@uref{URL[, TEXT][, REPLACEMENT]}' 9 Marking Words and Phrases 9.1 Indicating Definitions, Commands, etc. 9.1.1 Highlighting Commands are Useful 9.1.2 `@code'{SAMPLE-CODE} 9.1.3 `@kbd'{KEYBOARD-CHARACTERS} 9.1.4 `@key'{KEY-NAME} 9.1.5 `@samp'{TEXT} 9.1.6 `@verb'{TEXT} 9.1.7 `@var'{METASYNTACTIC-VARIABLE} 9.1.8 `@env'{ENVIRONMENT-VARIABLE} 9.1.9 `@file'{FILE-NAME} 9.1.10 `@command'{COMMAND-NAME} 9.1.11 `@option'{OPTION-NAME} 9.1.12 `@dfn'{TERM} 9.1.13 `@cite'{REFERENCE} 9.1.14 `@abbr'{ABBREVIATION[, MEANING]} 9.1.15 `@acronym'{ACRONYM[, MEANING]} 9.1.16 `@indicateurl'{UNIFORM-RESOURCE-LOCATOR} 9.1.17 `@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]} 9.2 Emphasizing Text 9.2.1 `@emph'{TEXT} and `@strong'{TEXT} 9.2.2 `@sc'{TEXT}: The Small Caps Font 9.2.3 Fonts for Printing, Not Info 10 Quotations and Examples 10.1 Block Enclosing Commands 10.2 `@quotation': Block quotations 10.3 `@example': Example Text 10.4 `@verbatim': Literal Text 10.5 `@verbatiminclude' FILE: Include a File Verbatim 10.6 `@lisp': Marking a Lisp Example 10.7 `@small...' Block Commands 10.8 `@display' and `@smalldisplay' 10.9 `@format' and `@smallformat' 10.10 `@exdent': Undoing a Line's Indentation 10.11 `@flushleft' and `@flushright' 10.12 `@noindent': Omitting Indentation 10.13 `@indent': Forcing Indentation 10.14 `@cartouche': Rounded Rectangles Around Examples 11 Lists and Tables 11.1 Introducing Lists 11.2 `@itemize': Making an Itemized List 11.3 `@enumerate': Making a Numbered or Lettered List 11.4 Making a Two-column Table 11.4.1 Using the `@table' Command 11.4.2 `@ftable' and `@vtable' 11.4.3 `@itemx' 11.5 `@multitable': Multi-column Tables 11.5.1 Multitable Column Widths 11.5.2 Multitable Rows 12 Special Displays 12.1 Floats 12.1.1 `@float' [TYPE][,LABEL]: Floating Material 12.1.2 `@caption' & `@shortcaption' 12.1.3 `@listoffloats': Tables of Contents for Floats 12.2 Inserting Images 12.2.1 Image Syntax 12.2.2 Image Scaling 12.3 Footnotes 12.3.1 Footnote Commands 12.3.2 Footnote Styles 13 Indices 13.1 Making Index Entries 13.2 Predefined Indices 13.3 Defining the Entries of an Index 13.4 Combining Indices 13.4.1 `@syncodeindex' 13.4.2 `@synindex' 13.5 Defining New Indices 14 Special Insertions 14.1 Inserting @ and {} and , 14.1.1 Inserting `@' with `@@' 14.1.2 Inserting `{' and `}' with `@{' and `@}' 14.1.3 Inserting `,' with `@comma{}' 14.2 Inserting Quote Characters 14.3 Inserting Space 14.3.1 Not Ending a Sentence 14.3.2 Ending a Sentence 14.3.3 Multiple Spaces 14.3.4 `@frenchspacing' VAL: Control sentence spacing 14.3.5 `@dmn'{DIMENSION}: Format a Dimension 14.4 Inserting Accents 14.5 Inserting Quotation Marks 14.6 Inserting Ellipsis and Bullets 14.6.1 `@dots'{} (...) and `@enddots'{} (...) 14.6.2 `@bullet'{} (*) 14.7 Inserting TeX and Legal Symbols: (C), (R) 14.7.1 `@TeX'{} (TeX) and `@LaTeX'{} (LaTeX) 14.7.2 `@copyright{}' ((C)) 14.7.3 `@registeredsymbol{}' ((R)) 14.8 `@euro'{} (Euro ): Euro Currency Symbol 14.9 `@pounds'{} (#): Pounds Sterling 14.10 `@textdegree'{} (o): Degrees Symbol 14.11 `@minus'{} (-): Inserting a Minus Sign 14.12 `@geq{}' (>=) and `@leq{}' (<=): Inserting relations 14.13 `@math': Inserting Mathematical Expressions 14.14 Click Sequences 14.15 Glyphs for Examples 14.15.1 Glyphs Summary 14.15.2 `@result{}' (=>): Indicating Evaluation 14.15.3 `@expansion{}' (==>): Indicating an Expansion 14.15.4 `@print{}' (-|): Indicating Printed Output 14.15.5 `@error{}' (error-->): Indicating an Error Message 14.15.6 `@equiv{}' (==): Indicating Equivalence 14.15.7 `@point{}' (-!-): Indicating Point in a Buffer 15 Forcing and Preventing Breaks 15.1 Break Commands 15.2 `@*' and `@/': Generate and Allow Line Breaks 15.3 `@-' and `@hyphenation': Helping TeX Hyphenate 15.4 `@allowcodebreaks': Control Line Breaks in `@code' 15.5 `@w'{TEXT}: Prevent Line Breaks 15.6 `@tie{}': Inserting an Unbreakable Space 15.7 `@sp' N: Insert Blank Lines 15.8 `@page': Start a New Page 15.9 `@group': Prevent Page Breaks 15.10 `@need MILS': Prevent Page Breaks 16 Definition Commands 16.1 The Template for a Definition 16.2 Definition Command Continuation Lines 16.3 Optional and Repeated Arguments 16.4 Two or More `First' Lines 16.5 The Definition Commands 16.5.1 Functions and Similar Entities 16.5.2 Variables and Similar Entities 16.5.3 Functions in Typed Languages 16.5.4 Variables in Typed Languages 16.5.5 Data Types 16.5.6 Object-Oriented Programming 16.5.6.1 Object-Oriented Variables 16.5.6.2 Object-Oriented Methods 16.6 Conventions for Writing Definitions 16.7 A Sample Function Definition 17 Conditionally Visible Text 17.1 Conditional Commands 17.2 Conditional Not Commands 17.3 Raw Formatter Commands 17.4 `@set', `@clear', and `@value' 17.4.1 `@set' and `@value' 17.4.2 `@ifset' and `@ifclear' 17.4.3 `@value' Example 17.5 Conditional Nesting 18 Internationalization 18.1 `@documentlanguage LL[_CC]': Set the Document Language 18.2 `@documentencoding ENC': Set Input Encoding 19 Defining New Texinfo Commands 19.1 Defining Macros 19.2 Invoking Macros 19.3 Macro Details and Caveats 19.4 `@alias NEW=EXISTING' 19.5 `definfoenclose': Customized Highlighting 20 Formatting and Printing Hardcopy 20.1 Use TeX 20.2 Format with `tex' and `texindex' 20.3 Format with `texi2dvi' 20.4 Shell Print Using `lpr -d' 20.5 From an Emacs Shell 20.6 Formatting and Printing in Texinfo Mode 20.7 Using the Local Variables List 20.8 TeX Formatting Requirements Summary 20.9 Preparing for TeX 20.10 Overfull "hboxes" 20.11 Printing "Small" Books 20.12 Printing on A4 Paper 20.13 `@pagesizes' [WIDTH][, HEIGHT]: Custom Page Sizes 20.14 Cropmarks and Magnification 20.15 PDF Output 20.16 How to Obtain TeX 21 Creating and Installing Info Files 21.1 Creating an Info File 21.1.1 `makeinfo' Preferred 21.1.2 Running `makeinfo' from a Shell 21.1.3 Options for `makeinfo' 21.1.4 Pointer Validation 21.1.5 Running `makeinfo' Within Emacs 21.1.6 The `texinfo-format...' Commands 21.1.7 Batch Formatting 21.1.8 Tag Files and Split Files 21.2 Installing an Info File 21.2.1 The Directory File `dir' 21.2.2 Listing a New Info File 21.2.3 Info Files in Other Directories 21.2.4 Installing Info Directory Files 21.2.5 Invoking `install-info' 22 Generating HTML 22.1 HTML Translation 22.2 HTML Splitting 22.3 HTML CSS 22.4 HTML Cross-references 22.4.1 HTML Cross-reference Link Basics 22.4.2 HTML Cross-reference Node Name Expansion 22.4.3 HTML Cross-reference Command Expansion 22.4.4 HTML Cross-reference 8-bit Character Expansion 22.4.5 HTML Cross-reference Mismatch Appendix A @-Command List A.1 @-Command Syntax Appendix B Tips and Hints Appendix C Sample Texinfo Files C.1 Short Sample C.2 GNU Sample Texts C.3 Verbatim Copying License C.4 All-permissive Copying License Appendix D Include Files D.1 How to Use Include Files D.2 `texinfo-multiple-files-update' D.3 Include Files Requirements D.4 Sample File with `@include' D.5 Evolution of Include Files Appendix E Page Headings E.1 Headings Introduced E.2 Standard Heading Formats E.3 Specifying the Type of Heading E.4 How to Make Your Own Headings Appendix F Formatting Mistakes F.1 `makeinfo' Find Errors F.2 Catching Errors with Info Formatting F.3 Catching Errors with TeX Formatting F.4 Using `texinfo-show-structure' F.5 Using `occur' F.6 Finding Badly Referenced Nodes F.6.1 Running `Info-validate' F.6.2 Creating an Unsplit File F.6.3 Tagifying a File F.6.4 Splitting a File Manually Appendix G GNU Free Documentation License Command and Variable Index General Index Texinfo ******* This manual is for GNU Texinfo (version 4.12, 9 April 2008), a documentation system that can produce both online information and a printed manual from a single source. 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. Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. --Dick Brandon Texinfo Copying Conditions ************************** The programs currently being distributed that relate to Texinfo include `makeinfo', `info', `texindex', and `texinfo.tex'. These programs are "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. 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. 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. 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. 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. This manual specifically is covered by the GNU Free Documentation License (*note GNU Free Documentation License::). 1 Overview of Texinfo ********************* "Texinfo"(1) is a documentation system that uses a single source file to produce both online information and printed output. This means that instead of writing two different documents, one for the online information and the other for a printed work, you need write only one document. Therefore, when the work is revised, you need revise only that one document. ---------- Footnotes ---------- (1) 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 `X' is actually the Greek letter "chi" rather than the English letter "ex". Pronounce TeX as if the `X' were the last sound in the name `Bach'; but pronounce Texinfo as if the `x' were a `k'. Spell "Texinfo" with a capital "T" and the other letters in lower case. 1.1 Reporting Bugs ================== We welcome bug reports and suggestions for any aspect of the Texinfo system, programs, documentation, installation, anything. Please email them to . You can get the latest version of Texinfo from `ftp://ftp.gnu.org/gnu/texinfo/' and its mirrors worldwide. For bug reports, please include enough information for the maintainers to reproduce the problem. Generally speaking, that means: * the version number of Texinfo and the program(s) or manual(s) involved. * hardware and operating system names and versions. * the contents of any input files necessary to reproduce the bug. * a description of the problem and samples of any erroneous output. * any unusual options you gave to `configure'. * anything else that you think would be helpful. When in doubt whether something is needed or not, include it. It's better to include too much than to leave out something important. Patches are most welcome; if possible, please make them with `diff -c' (*note Overview: (diff)Top.) and include `ChangeLog' entries (*note Change Log: (emacs)Change Log.), and follow the existing coding style. 1.2 Using Texinfo ================= Using Texinfo, you can create a printed document (via the TeX typesetting system) the normal features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create an Info file with special features to make documentation browsing easy. You can also create from that same source file an HTML output file suitable for use with a web browser, or an XML file. See the next section (*note Output Formats::) for details and the exact commands to generate output from the source. TeX works with virtually all printers; Info works with virtually all computer terminals; the HTML output works with virtually all web browsers. Thus Texinfo can be used by almost any computer user. A Texinfo source file is a plain ASCII file containing text interspersed with "@-commands" (words preceded by an `@') that tell the typesetting and formatting programs what to do. You can 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. (*Note Texinfo Mode::.) You can use Texinfo to create both online help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo is the official documentation format of the GNU project. More information is available at the GNU documentation web page (http://www.gnu.org/doc/). 1.3 Output Formats ================== Here is a brief overview of the output formats currently supported by Texinfo. Info (Generated via `makeinfo'.) This format is essentially a plain text transliteration of the Texinfo source. It adds a few control characters to separate nodes and provide navigational information for menus, cross-references, indices, and so on. See the next section (*note Info Files::) for more details on this format. The Emacs Info subsystem (*note Getting Started: (info)Top.), and the standalone `info' program (*note Info Standalone: (info-stnd)Top.), among others, can read these files. *Note Creating and Installing Info Files::. Plain text (Generated via `makeinfo --no-headers'.) This is almost the same as Info output, except the navigational control characters are omitted. Also, standard output is used by default. HTML (Generated via `makeinfo --html'.) This is the Hyper Text Markup Language that has become the most commonly used language for writing documents on the World Wide Web. Web browsers, such as Mozilla, Lynx, and Emacs-W3, can render this language online. There are many versions of HTML; `makeinfo' tries to use a subset of the language that can be interpreted by any common browser. For details of the HTML language and much related information, see `http://www.w3.org/MarkUp/'. *Note Generating HTML::. DVI (Generated via `texi2dvi'.) This DeVice Independent binary format is output by the TeX typesetting program (`http://tug.org'). This is then read by a DVI `driver', which writes the actual device-specific commands that can be viewed or printed, notably Dvips for translation to PostScript (*note Invoking Dvips: (dvips)Invoking Dvips.) and Xdvi for viewing on an X display (`http://sourceforge.net/projects/xdvi/'). *Note Hardcopy::. Be aware that the Texinfo language is very different from and much stricter than TeX's usual languages, plain TeX and LaTeX. For more information on TeX in general, please see the book `TeX for the Impatient', available from `http://savannah.gnu.org/projects/teximpatient'. PDF (Generated via `texi2dvi --pdf' or `texi2pdf'.) This format was developed by Adobe Systems for portable document interchange, based on their previous PostScript language. It can represent the exact appearance of a document, including fonts and graphics, and supporting arbitrary scaling. It is intended to be platform-independent and easily viewable, among other design goals; `http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf' has some background. Texinfo uses the `pdftex' program, a variant of TeX, to output PDF; see `http://tug.org/applications/pdftex'. *Note PDF Output::. XML (Generated via `makeinfo --xml'.) XML is a generic syntax specification usable for any sort of content (see, for example, `http://www.w3.org/XML/'). The `makeinfo' XML output, unlike all the formats above, interprets very little of the Texinfo source. Rather, it merely translates the Texinfo markup commands into XML syntax, for processing by further XML tools. The particular syntax output is defined in the file `texinfo.dtd' included in the Texinfo source distribution. Docbook (Generated via `makeinfo --docbook'.) This is an XML-based format developed some years ago, primarily for technical documentation. It therefore bears some resemblance, in broad outlines, to Texinfo. See `http://www.docbook.org'. If you want to convert from Docbook _to_ Texinfo, please see `http://docbook2X.sourceforge.net'. From time to time, proposals are made to generate traditional Unix man pages from Texinfo source. However, because man pages have a very strict conventional format, generating a good man page requires a completely different source than the typical Texinfo applications of writing a good user tutorial and/or a good reference manual. This makes generating man pages incompatible with the Texinfo design goal of not having to document the same information in different ways for different output formats. You might as well just write the man page directly. Man pages still have their place, and if you wish to support them, you may find the program `help2man' to be useful; it generates a traditional man page from the `--help' output of a program. In fact, this is currently used to generate man pages for the programs in the Texinfo distribution. It is GNU software written by Brendan O'Dea, available from `ftp://ftp.gnu.org/gnu/help2man/'. If you are a programmer and would like to contribute to the GNU project by implementing additional output formats for Texinfo, that would be excellent. But please do not write a separate translator texi2foo for your favorite format foo! That is the hard way to do the job, and makes extra work in subsequent maintenance, since the Texinfo language is continually being enhanced and updated. Instead, the best approach is modify `makeinfo' to generate the new format. 1.4 Info Files ============== An Info file is a Texinfo file formatted so that the Info documentation reading program can operate on it. (`makeinfo' and `texinfo-format-buffer' are two commands that convert a Texinfo file into an Info file.) Info files are divided into pieces called "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. *Note Top: (info)Top, for more information about using Info. 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 "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. 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.(1) 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. 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. Usually, you will design a document so that its nodes match the structure of chapters and sections in the printed output. But occasionally 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. Generally, you enter an Info file through a node that by convention is named `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. Alternatively, with the standalone Info program, you can specify specific menu items on the command line (*note Top: (info)Top.). If you want to read through an Info file in sequence, as if it were a printed manual, you can hit repeatedly, or you get the whole file with the advanced Info command `g *'. (*note Advanced Info commands: (info)Advanced.) The `dir' file in the `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. If you wish to refer to an Info file in a URI, you can use the (unofficial) syntax exemplified in the following. This works with Emacs/W3, for example: info:///usr/info/emacs#Dissociated%20Press info:emacs#Dissociated%20Press info://localhost/usr/info/emacs#Dissociated%20Press The `info' program itself does not follow URIs of any kind. ---------- Footnotes ---------- (1) 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. 1.5 Printed Books ================= 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.(1) 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. You can use Texinfo to write a book without ever having the intention of converting it into online 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. TeX is a general purpose typesetting program. Texinfo provides a file `texinfo.tex' that contains information (definitions or "macros") that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX commands, which TeX can then process to create the typeset document.) `texinfo.tex' contains the specifications for printing a document. You can get the latest version of `texinfo.tex' from the Texinfo home page, `http://www.gnu.org/software/texinfo/'. In the United States, documents are most often printed on 8.5 inch by 11 inch pages (216mm by 280mm); this is the default size. But you can also print for 7 inch by 9.25 inch pages (178mm by 235mm, the `@smallbook' size; or on A4 or A5 size paper (`@afourpaper', `@afivepaper'). (*Note Printing "Small" Books: smallbook. Also, see *note Printing on A4 Paper: A4 Paper.) By changing the parameters in `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. TeX is freely distributable. It is written in a superset 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. (*Note TeX Mode: (emacs)TeX Mode, for information about TeX.) 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. To get a copy of TeX, see *note How to Obtain TeX: Obtaining TeX. ---------- Footnotes ---------- (1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz) program if you do not have TeX; since Texinfo is designed for use with TeX, `texi2roff' is not described here. `texi2roff' is not part of the standard GNU distribution and is not maintained or up-to-date with all the Texinfo features described in this manual. 1.6 @-commands ============== In a Texinfo file, the commands that tell TeX how to typeset the printed manual and tell `makeinfo' and `texinfo-format-buffer' how to create an Info file are preceded by `@'; they are called "@-commands". For example, `@node' is the command to indicate a node and `@chapter' is the command to indicate the start of a chapter. Note: Almost all @ command names are entirely lower case. 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. Depending on what they do or what arguments(1) they take, you need to write @-commands on lines of their own or as part of sentences: * Write a command such as `@quotation' at the beginning of a line as the only text on the line. (`@quotation' begins an indented environment.) * Write a command such as `@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. (`@chapter' creates chapter titles.) * Write a command such as `@dots{}' wherever you wish but usually within a sentence. (`@dots{}' creates an ellipsis ...) * Write a command such as `@code{SAMPLE-CODE}' wherever you wish (but usually within a sentence) with its argument, SAMPLE-CODE in this example, between the braces. (`@code' marks text as being code.) * Write a command such as `@example' on a line of its own; write the body-text on following lines; and write the matching `@end' command, `@end example' in this case, on a line of its own after the body-text. (`@example' ... `@end example' indents and typesets body-text as an example.) It's usually ok to indent environment commands like this, but in complicated and hard-to-define circumstances the extra spaces cause extra space to appear in the output, so beware. 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 `@:', are exceptions to the rule; they do not need braces. As you gain experience with Texinfo, you will rapidly learn how to write the different commands: the different ways to write commands actually make it easier to write and read Texinfo files than if all commands followed exactly the same syntax. *Note @-Command Syntax: Command Syntax, for all the details. ---------- Footnotes ---------- (1) The word "argument" comes from the way it is used in mathematics and does not refer to a dispute between two people; it refers to the information presented to the command. According to the `Oxford English Dictionary', the word derives from the Latin for "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 dispute. 1.7 General Syntactic Conventions ================================= This section describes the general conventions used in all Texinfo documents. * All printable ASCII characters except `@', `{' and `}' can appear in a Texinfo file and stand for themselves. `@' is the escape character which introduces commands, while `{' and `}' are used to surround arguments to certain commands. To put one of these special characters into the document, put an `@' character in front of it, like this: `@@', `@{', and `@}'. * Separate paragraphs with one or more blank lines. Currently Texinfo only recognizes newline characters as end of line, not the CRLF sequence used on some systems; so a "blank line" means exactly two consecutive newlines. Sometimes blank lines are useful or convenient in other cases as well; you can use the `@noindent' to inhibit paragraph indentation if required (*note `@noindent': noindent.). * Texinfo supports the usual quotation marks used in English, and quotation marks used in other languages, please see *note Inserting Quotation Marks::. * Use three hyphens in a row, `---', to produce a long dash--like this (called an "em dash"), used for punctuation in sentences. Use two hyphens, `--', to produce a medium dash (called an "en dash"), used primarily for numeric ranges, as in "June 25-26". Use a single hyphen, `-', to produce a standard hyphen used in compound words. For display on the screen, Info reduces three hyphens to two and two hyphens to one (not transitively!). Of course, any number of hyphens in the source remain as they are in literal contexts, such as `@code' and `@example'. * *Caution:* Last, do not use tab characters in a Texinfo file (except in verbatim modes)! TeX uses variable-width fonts, which means that it is impractical at best to define a tab to work in all circumstances. Consequently, TeX treats tabs like single spaces, and that is not what they look like in the source. Furthermore, `makeinfo' does nothing special with tabs, and thus a tab character in your input file will usually appear differently in the output. To avoid this problem, Texinfo mode in GNU Emacs inserts multiple spaces when you press the key. Also, you can run `untabify' in Emacs to convert tabs in a region to multiple spaces, or use the `unexpand' command from the shell. 1.8 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 `@comment' command (which may be abbreviated to `@c'). Such comments are for the person who revises the Texinfo file. All the text on a line that follows either `@comment' or `@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 `@comment' or `@c' in the middle of a line, and only the text that follows after the `@comment' or `@c' command does not appear; but some commands, such as `@settitle' and `@setfilename', work on a whole line. You cannot use `@comment' or `@c' in a line beginning with such a command. You can write long stretches of text that will not appear in either the Info file or the printed manual by using the `@ignore' and `@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 `@ignore' and `@end ignore' for writing comments. Text enclosed by `@ignore' or by failing `@ifset' or `@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 _stop_ ignoring text from the source file; that means that you may still get error messages if you have invalid Texinfo commands within ignored text. 1.9 What a Texinfo File Must Have ================================= By convention, the name of a Texinfo file ends with (in order of preference) one of the extensions `.texinfo', `.texi', `.txi', or `.tex'. The longer extensions are preferred since they describe more clearly to a human reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names. In order to be made into a printed manual and an Info file, a Texinfo file *must* begin with lines like this: \input texinfo @setfilename INFO-FILE-NAME @settitle NAME-OF-MANUAL The contents of the file follow this beginning, and then you *must* end a Texinfo file with a line like this: @bye Here's an explanation: * The `\input texinfo' line tells TeX to use the `texinfo.tex' file, which tells TeX how to translate the Texinfo @-commands into TeX typesetting commands. (Note the use of the backslash, `\'; this is correct for TeX.) * The `@setfilename' line provides a name for the Info file and tells TeX to open auxiliary files. *All text before `@setfilename' is ignored!* * The `@settitle' line specifies a title for the page headers (or footers) of the printed manual, and the default document description for the `' in HTML format. Strictly speaking, `@settitle' is optional--if you don't mind your document being titled `Untitled'. * The `@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. Typically, 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: \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename INFO-FILE-NAME @settitle NAME-OF-MANUAL @c %**end of header In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo mode when you edit the file. The `@c' lines which surround the `@setfilename' and `@settitle' lines are optional, but you need them in order to run TeX or Info on just part of the file. (*Note Start of Header::.) Furthermore, you will usually provide a Texinfo file with a title page, indices, and the like, all of which are explained in this manual. 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. 1.10 Six Parts of a Texinfo File ================================ Generally, a Texinfo file contains more than the minimal beginning and end described in the previous section--it usually contains the six parts listed below. These are described fully in the following sections. 1. Header The "Header" names the file, tells TeX which definitions file to use, and other such housekeeping tasks. 2. Summary and Copyright The "Summary and Copyright" segment describes the document and contains the copyright notice and copying permissions. This is done with the `@copying' command. 3. Title and Copyright The "Title and Copyright" segment contains the title and copyright pages for the printed manual. The segment must be enclosed between `@titlepage' and `@end titlepage' commands. The title and copyright page appear only in the printed manual. 4. `Top' Node and Master Menu The `Top' node starts off the online output; it does not appear in the printed manual. We recommend including the copying permissions here as well as the segments above. And it contains at least a top-level menu listing the chapters, and possibly a "Master Menu" listing all the nodes in the entire document. 5. Body The "Body" of the document is typically structured like a traditional book or encyclopedia, but it may be free form. 6. End The "End" segment may contain commands for printing indices, and closes with the `@bye' command on a line of its own. 1.11 A Short Sample Texinfo File ================================ Here is a very short but complete Texinfo file, in the six conventional parts enumerated in the previous section, so you can see how Texinfo source appears in practice. The first three parts of the file, from `\input texinfo' through to `@end titlepage', look more intimidating than they are: most of the material is standard boilerplate; when writing a manual, you simply change the names as appropriate. *Note Beginning a File::, for full documentation on the commands listed here. *Note GNU Sample Texts::, for the full texts to be used in GNU manuals. In the following, the sample text is _indented_; comments on it are not. The complete file, without interspersed comments, is shown in *note Short Sample Texinfo File::. Part 1: Header -------------- 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. \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename sample.info @settitle Sample Manual 1.0 @c %**end of header Part 2: Summary Description and Copyright ----------------------------------------- A real manual includes more text here, according to the license under which it is distributed. *Note GNU Sample Texts::. @copying This is a short example of a complete Texinfo file, version 1.0. Copyright @copyright{} 2005 Free Software Foundation, Inc. @end copying Part 3: Titlepage, Contents, Copyright -------------------------------------- The titlepage segment does not appear in the online output, only in the printed manual. We use the `@insertcopying' command to include the permission text from the previous section, instead of writing it out again; it is output on the back of the title page. The `@contents' command generates a table of contents. @titlepage @title Sample Title @c The following two commands start the copyright page. @page @vskip 0pt plus 1filll @insertcopying @end titlepage @c Output the table of contents at the beginning. @contents Part 4: `Top' Node and Master Menu ---------------------------------- The `Top' node contains the master menu for the Info file. Since the printed manual uses a table of contents rather than a menu, it excludes the `Top' node. We repeat the short description from the beginning of the `@copying' text, but there's no need to repeat the copyright information, so we don't use `@insertcopying' here. The `@top' command itself helps `makeinfo' determine the relationships between nodes. @ifnottex @node Top @top Short Sample This is a short sample Texinfo file. @end ifnottex @menu * First Chapter:: The first chapter is the only chapter in this sample. * Index:: Complete index. @end menu Part 5: The Body of the Document -------------------------------- 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. @node First Chapter @chapter First Chapter @cindex chapter, first This is the first chapter. @cindex index entry, another Here is a numbered list. @enumerate @item This is the first item. @item This is the second item. @end enumerate Part 6: The End of the Document ------------------------------- The end segment contains commands for generating an index in a node and unnumbered chapter of its own, and the `@bye' command that marks the end of the document. @node Index @unnumbered Index @printindex cp @bye Some Results ------------ Here is what the contents of the first chapter of the sample look like: This is the first chapter. Here is a numbered list. 1. This is the first item. 2. This is the second item. 1.12 History ============ Richard M. Stallman invented the Texinfo format, wrote the initial processors, and created Edition 1.0 of this manual. Robert J. Chassell greatly revised and extended the manual, starting with Edition 1.1. Brian Fox was responsible for the standalone Texinfo distribution until version 3.8, and wrote the standalone `makeinfo' and `info' programs. Karl Berry has continued maintenance since Texinfo 3.8 (manual edition 2.22). Our thanks go out to all who helped improve this work, particularly the indefatigable Eli Zaretskii and Andreas Schwab, who have provided patches beyond counting. Franc,ois Pinard and David D. Zuhn, tirelessly recorded and reported mistakes and obscurities. Zack Weinberg did the impossible by implementing the macro syntax in `texinfo.tex'. Special thanks go to Melissa Weisshaus for her frequent reviews of nearly similar editions. Dozens of others have contributed patches and suggestions, they are gratefully acknowledged in the `ChangeLog' file. Our mistakes are our own. A bit of history: in the 1970's at CMU, Brian Reid developed a program and format named Scribe to mark up documents for printing. It used the `@' character to introduce commands, as Texinfo does. Much more consequentially, it strove to describe document contents rather than formatting, an idea wholeheartedly adopted by Texinfo. Meanwhile, people at MIT developed another, not too dissimilar format called Bolio. This then was converted to using TeX as its typesetting language: BoTeX. The earliest BoTeX version seems to have been 0.02 on October 31, 1984. BoTeX could only be used as a markup language for documents to be printed, not for online documents. Richard Stallman (RMS) worked on both Bolio and BoTeX. He also developed a nifty on-line help format called Info, and then combined BoTeX and Info to create Texinfo, a mark up language for text that is intended to be read both online and as printed hard copy. 2 Using Texinfo Mode ******************** You may edit a Texinfo file with any text editor you choose. A Texinfo file is no different from any other ASCII file. However, GNU Emacs comes with a special mode, called Texinfo mode, that provides Emacs commands and tools to help ease your work. This chapter describes features of GNU Emacs' Texinfo mode but not any features of the Texinfo formatting language. So 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. 2.1 Texinfo Mode Overview ========================= Texinfo mode provides special features for working with Texinfo files. You can: * Insert frequently used @-commands. * Automatically create `@node' lines. * Show the structure of a Texinfo source file. * Automatically create or update the `Next', `Previous', and `Up' pointers of a node. * Automatically create or update menus. * Automatically create a master menu. * Format a part or all of a file for Info. * Typeset and print part or all of a file. Perhaps the two most helpful features are those for inserting frequently used @-commands and for creating node pointers and menus. 2.2 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 `M-q' (`fill-paragraph') command will refill a paragraph but not mix an indexing command on a line adjacent to it into the paragraph. In addition, Texinfo mode sets the `page-delimiter' variable to the value of `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 `C-x ]' (`forward-page') and `C-x [' (`backward-page') commands and narrow to a chapter with the `C-x n p' (`narrow-to-page') command. (*Note Pages: (emacs)Pages, for details about the page commands.) You may name a Texinfo file however you wish, but the convention is to end a Texinfo file name with one of the extensions `.texinfo', `.texi', `.txi', or `.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 `.texinfo', `.texi' or `.txi' extension. Also, Emacs switches to Texinfo mode when you visit a file that has `-*-texinfo-*-' in its first line. If ever you are in another mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'. 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. 2.3 Inserting Frequently Used Commands ====================================== Texinfo mode provides commands to insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes. The insert commands are invoked by typing `C-c' twice and then the first letter of the @-command: `C-c C-c c' `M-x texinfo-insert-@code' Insert `@code{}' and put the cursor between the braces. `C-c C-c d' `M-x texinfo-insert-@dfn' Insert `@dfn{}' and put the cursor between the braces. `C-c C-c e' `M-x texinfo-insert-@end' Insert `@end' and attempt to insert the correct following word, such as `example' or `table'. (This command does not handle nested lists correctly, but inserts the word appropriate to the immediately preceding list.) `C-c C-c i' `M-x texinfo-insert-@item' Insert `@item' and put the cursor at the beginning of the next line. `C-c C-c k' `M-x texinfo-insert-@kbd' Insert `@kbd{}' and put the cursor between the braces. `C-c C-c n' `M-x texinfo-insert-@node' Insert `@node' and a comment line listing the sequence for the `Next', `Previous', and `Up' nodes. Leave point after the `@node'. `C-c C-c o' `M-x texinfo-insert-@noindent' Insert `@noindent' and put the cursor at the beginning of the next line. `C-c C-c s' `M-x texinfo-insert-@samp' Insert `@samp{}' and put the cursor between the braces. `C-c C-c t' `M-x texinfo-insert-@table' Insert `@table' followed by a and leave the cursor after the . `C-c C-c v' `M-x texinfo-insert-@var' Insert `@var{}' and put the cursor between the braces. `C-c C-c x' `M-x texinfo-insert-@example' Insert `@example' and put the cursor at the beginning of the next line. `C-c C-c {' `M-x texinfo-insert-braces' Insert `{}' and put the cursor between the braces. `C-c }' `C-c ]' `M-x up-list' Move from between a pair of braces forward past the closing brace. Typing `C-c ]' is easier than typing `C-c }', which is, however, more mnemonic; hence the two keybindings. (Also, you can move out from between braces by typing `C-f'.) To put a command such as `@code{...}' around an _existing_ word, position the cursor in front of the word and type `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 `@kbd' and `@var'. This set of insert commands was created after analyzing the frequency with which different @-commands are used in the `GNU Emacs Manual' and the `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 `texinfo.el'. `C-c C-c C-d' (`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. *Note The Parts of a Menu: Menu Parts.) To use `texinfo-start-menu-description', position point in a menu entry line and type `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. 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. 2.4 Showing the Section Structure of a File =========================================== You can show the section structure of a Texinfo file by using the `C-c C-s' command (`texinfo-show-structure'). This command shows the section structure of a Texinfo file by listing the lines that begin with the @-commands for `@chapter', `@section', and the like. It constructs what amounts to a table of contents. These lines are displayed in another buffer called the `*Occur*' buffer. In that buffer, you can position the cursor over one of the lines and use the `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the corresponding spot in the Texinfo file. `C-c C-s' `M-x texinfo-show-structure' Show the `@chapter', `@section', and such lines of a Texinfo file. `C-c C-c' `M-x occur-mode-goto-occurrence' Go to the line in the Texinfo file corresponding to the line under the cursor in the `*Occur*' buffer. If you call `texinfo-show-structure' with a prefix argument by typing `C-u C-c C-s', it will list not only those lines with the @-commands for `@chapter', `@section', and the like, but also the `@node' lines. You can use `texinfo-show-structure' with a prefix argument to check whether the `Next', `Previous', and `Up' pointers of an `@node' line are correct. 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 `C-x n n' (`narrow-to-region') command and `texinfo-show-structure' will work on only that region. To see the whole buffer again, use `C-x n w' (`widen'). (*Note Narrowing: (emacs)Narrowing, for more information about the narrowing commands.) In addition to providing the `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 `C-x ]' (`forward-page') and `C-x [' (`backward-page') commands to move forward and backward by chapter, and to use the `C-x n p' (`narrow-to-page') command to narrow to a chapter. *Note Pages: (emacs)Pages, for more information about the page commands. 2.5 Updating Nodes and 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 `@node' line that has none and to create menus in a file that has none. If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task. 2.5.1 The Updating Commands --------------------------- You can use the updating commands to: * insert or update the `Next', `Previous', and `Up' pointers of a node, * insert or update the menu for a section, and * create a master menu for a Texinfo source file. You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file. 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 `@node' line, except for the `Top' `@node' line. (A "structuring command line" is a line beginning with `@chapter', `@section', or other similar command.) You can write the structuring command line on the line that follows immediately after an `@node' line or else on the line that follows after a single `@comment' line or a single `@ifinfo' line. You cannot interpose more than one line between the `@node' line and the structuring command line; and you may interpose only an `@comment' line or an `@ifinfo' line. Commands which work on a whole buffer require that the `Top' node be followed by a node with an `@chapter' or equivalent-level command. The menu updating commands will not create a main or master menu for a Texinfo file that has only `@chapter'-level nodes! The menu updating commands only create menus _within_ nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' node. 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. 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 `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. The `texinfo-master-menu' command is the primary command: `C-c C-u m' `M-x texinfo-master-menu' Create or update a master menu that includes all the other menus (incorporating the descriptions from pre-existing menus, if any). With an argument (prefix argument, `C-u,' if interactive), first create or update all the nodes and all the regular menus in the buffer before constructing the master menu. (*Note The Top Node and Master Menu: The Top Node, for more about a master menu.) For `texinfo-master-menu' to work, the Texinfo file must have a `Top' node and at least one subsequent node. After extensively editing a Texinfo file, you can type the following: C-u M-x texinfo-master-menu or C-u C-c C-u m This updates all the nodes and menus completely and all at once. 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. The commands are: `C-c C-u C-n' `M-x texinfo-update-node' Insert the `Next', `Previous', and `Up' pointers for the node that point is within (i.e., for the `@node' line preceding point). If the `@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, `C-u', if interactive), this command updates all `@node' lines in the region (which is the text between point and mark). `C-c C-u C-m' `M-x texinfo-make-menu' Create or update the menu in the node that point is within. With an argument (`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. Whenever `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. `C-c C-u C-e' `M-x texinfo-every-node-update' Insert or update the `Next', `Previous', and `Up' pointers for every node in the buffer. `C-c C-u C-a' `M-x texinfo-all-menus-update' Create or update all the menus in the buffer. With an argument (`C-u' as prefix argument, if interactive), first insert or update all the node pointers before working on the menus. If a master menu exists, the `texinfo-all-menus-update' command updates it; but the command does not create a new master menu if none already exists. (Use the `texinfo-master-menu' command for that.) When working on a document that does not merit a master menu, you can type the following: C-u C-c C-u C-a or C-u M-x texinfo-all-menus-update This updates all the nodes and menus. The `texinfo-column-for-description' variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it can be useful to reduce it to as low as 24. You can set the variable via customization (*note Changing an Option: (emacs)Changing an Option.) or with the `M-x set-variable' command (*note Examining and Setting Variables: (emacs)Examining.). Also, the `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 `texinfo-insert-node-lines' command to insert missing `@node' lines into a file. (*Note Other Updating Commands::, for more information.) 2.5.2 Updating Requirements --------------------------- 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. Each `@node' line, with the exception of the line for the `Top' node, must be followed by a line with a structuring command such as `@chapter', `@section', or `@unnumberedsubsec'. Each `@node' line/structuring-command line combination must look either like this: @node Comments, Minimum, Conventions, Overview @comment node-name, next, previous, up @section Comments or like this (without the `@comment' line): @node Comments, Minimum, Conventions, Overview @section Comments or like this (without the explicit node pointers): @node Comments @section Comments 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 `@comment' line, you may also write an `@ifinfo' line.) If a file has a `Top' node, it must be called `top' or `Top' and be the first node in the file. 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. Incidentally, the `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 `makeinfo', you have no need for the update node commands. (*Note Creating an Info File::, for more information about `makeinfo'.) However, both `makeinfo' and the `texinfo-format-...' commands require that you insert menus in the file. 2.5.3 Other Updating Commands ----------------------------- In addition to the five major updating commands, Texinfo mode possesses several less frequently used updating commands: `M-x texinfo-insert-node-lines' Insert `@node' lines before the `@chapter', `@section', and other sectioning commands wherever they are missing throughout a region in a Texinfo file. With an argument (`C-u' as prefix argument, if interactive), the `texinfo-insert-node-lines' command not only inserts `@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 `@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. For example, the following marks a whole buffer as a region and inserts `@node' lines and titles throughout: C-x h C-u M-x texinfo-insert-node-lines This command inserts titles as node names in `@node' lines; the `texinfo-start-menu-description' command (*note Inserting Frequently Used Commands: Inserting.) inserts titles as descriptions in menu entries, a different action. However, in both cases, you need to edit the inserted text. `M-x texinfo-multiple-files-update' Update nodes and menus in a document built from several separate files. With `C-u' as a prefix argument, create and insert a master menu in the outer file. With a numeric prefix argument, such as `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 `texinfo-multiple-files-update' command is described in the appendix on `@include' files. *Note texinfo-multiple-files-update::. `M-x 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 (`C-u' as prefix argument, if interactive), the `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. `M-x 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 `g *' command lets you look through the file sequentially, so sequentially ordered nodes are not strictly necessary.) With an argument (prefix argument, if interactive), the `texinfo-sequential-node-update' command sequentially updates all the nodes in the region. 2.6 Formatting for Info ======================= 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. You can use either the `texinfo-format-region' or the `makeinfo-region' command to format a region: `C-c C-e C-r' `M-x texinfo-format-region' `C-c C-m C-r' `M-x makeinfo-region' Format the current region for Info. You can use either the `texinfo-format-buffer' or the `makeinfo-buffer' command to format a whole buffer: `C-c C-e C-b' `M-x texinfo-format-buffer' `C-c C-m C-b' `M-x makeinfo-buffer' Format the current buffer for Info. For example, after writing a Texinfo file, you can type the following: C-u C-c C-u m or C-u M-x texinfo-master-menu This updates all the nodes and menus. Then type the following to create an Info file: C-c C-m C-b or M-x makeinfo-buffer For TeX or the Info formatting commands to work, the file _must_ include a line that has `@setfilename' in its header. *Note Creating an Info File::, for details about Info formatting. 2.7 Printing ============ Typesetting and printing a Texinfo file is a multi-step process in which you first create a file for printing (called a DVI file), and then print the file. Optionally, you may also create indices. To do this, you must run the `texindex' command after first running the `tex' typesetting command; and then you must run the `tex' command again. Or else run the `texi2dvi' command which automatically creates indices as needed (*note Format with texi2dvi::). 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 `texinfo-tex-region' and related commands for this purpose. Use the `texinfo-tex-buffer' command to format all of a buffer. `C-c C-t C-b' `M-x texinfo-tex-buffer' Run `texi2dvi' on the buffer. In addition to running TeX on the buffer, this command automatically creates or updates indices as needed. `C-c C-t C-r' `M-x texinfo-tex-region' Run TeX on the region. `C-c C-t C-i' `M-x texinfo-texindex' Run `texindex' to sort the indices of a Texinfo file formatted with `texinfo-tex-region'. The `texinfo-tex-region' command does not run `texindex' automatically; it only runs the `tex' typesetting command. You must run the `texinfo-tex-region' command a second time after sorting the raw index files with the `texindex' command. (Usually, you do not format an index when you format a region, only when you format a buffer. Now that the `texi2dvi' command exists, there is little or no need for this command.) `C-c C-t C-p' `M-x texinfo-tex-print' Print the file (or the part of the file) previously formatted with `texinfo-tex-buffer' or `texinfo-tex-region'. For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file _must_ start with a `\input texinfo' line and must include an `@settitle' line. The file must end with `@bye' on a line by itself. (When you use `texinfo-tex-region', you must surround the `@settitle' line with start-of-header and end-of-header lines.) *Note Hardcopy::, for a description of the other TeX related commands, such as `tex-show-print-queue'. 2.8 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 `C-c'. The keys are somewhat mnemonic. Insert Commands --------------- The insert commands are invoked by typing `C-c' twice and then the first letter of the @-command to be inserted. (It might make more sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c' is quick to type.) C-c C-c c Insert `@code'. C-c C-c d Insert `@dfn'. C-c C-c e Insert `@end'. C-c C-c i Insert `@item'. C-c C-c n Insert `@node'. C-c C-c s Insert `@samp'. C-c C-c v Insert `@var'. C-c { Insert braces. C-c ] C-c } Move out of enclosing braces. C-c C-c C-d Insert a node's section title in the space for the description in a menu entry line. Show Structure -------------- The `texinfo-show-structure' command is often used within a narrowed region. C-c C-s List all the headings. The Master Update Command ------------------------- The `texinfo-master-menu' command creates a master menu; and can be used to update every node and menu in a file as well. C-c C-u m M-x texinfo-master-menu Create or update a master menu. C-u C-c C-u m With `C-u' as a prefix argument, first create or update all nodes and regular menus, and then create a master menu. Update Pointers --------------- The update pointer commands are invoked by typing `C-c C-u' and then either `C-n' for `texinfo-update-node' or `C-e' for `texinfo-every-node-update'. C-c C-u C-n Update a node. C-c C-u C-e Update every node in the buffer. Update Menus ------------ Invoke the update menu commands by typing `C-c C-u' and then either `C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'. To update both nodes and menus at the same time, precede `C-c C-u C-a' with `C-u'. C-c C-u C-m Make or update a menu. C-c C-u C-a Make or update all menus in a buffer. C-u C-c C-u C-a With `C-u' as a prefix argument, first create or update all nodes and then create or update all menus. Format for Info --------------- The Info formatting commands that are written in Emacs Lisp are invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b' for the whole buffer. The Info formatting commands that are written in C and based on the `makeinfo' program are invoked by typing `C-c C-m' and then either `C-r' for a region or `C-b' for the whole buffer. Use the `texinfo-format...' commands: C-c C-e C-r Format the region. C-c C-e C-b Format the buffer. Use `makeinfo': C-c C-m C-r Format the region. C-c C-m C-b Format the buffer. C-c C-m C-l Recenter the `makeinfo' output buffer. C-c C-m C-k Kill the `makeinfo' formatting job. Typeset and Print ----------------- The TeX typesetting and printing commands are invoked by typing `C-c C-t' and then another control command: `C-r' for `texinfo-tex-region', `C-b' for `texinfo-tex-buffer', and so on. C-c C-t C-r Run TeX on the region. C-c C-t C-b Run `texi2dvi' on the buffer. C-c C-t C-i Run `texindex'. C-c C-t C-p Print the DVI file. C-c C-t C-q Show the print queue. C-c C-t C-d Delete a job from the print queue. C-c C-t C-k Kill the current TeX formatting job. C-c C-t C-x Quit a currently stopped TeX formatting job. C-c C-t C-l Recenter the output buffer. Other Updating Commands ----------------------- The remaining updating commands do not have standard keybindings because they are rarely used. M-x texinfo-insert-node-lines Insert missing `@node' lines in region. With `C-u' as a prefix argument, use section titles as node names. M-x texinfo-multiple-files-update Update a multi-file document. With `C-u 2' as a prefix argument, create or update all nodes and menus in all included files first. M-x texinfo-indent-menu-description Indent descriptions. M-x texinfo-sequential-node-update Insert node pointers in strict sequence. 3 Beginning a Texinfo File ************************** Certain pieces of information must be provided at the beginning of a Texinfo file, such as the name for the output file(s), the title of the document, and the Top node. A table of contents is also generally produced here. This chapter expands on the minimal complete Texinfo source file previously given (*note Six Parts::). It describes the numerous commands for handling the traditional frontmatter items in Texinfo. Straight text outside of any command before the Top node should be avoided. Such text is treated differently in the different output formats: visible in TeX and HTML, by default not shown in Info readers, and so on. 3.1 Sample Texinfo File Beginning ================================= The following sample shows what is needed. The elements given here are explained in more detail in the following sections. Other commands are often included at the beginning of Texinfo files, but the ones here are the most critical. *Note GNU Sample Texts::, for the full texts to be used in GNU manuals. \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename INFONAME.info @settitle NAME-OF-MANUAL VERSION @c %**end of header @copying This manual is for PROGRAM, version VERSION. Copyright @copyright{} YEARS COPYRIGHT-OWNER. @quotation Permission is granted to ... @end quotation @end copying @titlepage @title NAME-OF-MANUAL-WHEN-PRINTED @subtitle SUBTITLE-IF-ANY @subtitle SECOND-SUBTITLE @author AUTHOR @c The following two commands @c start the copyright page. @page @vskip 0pt plus 1filll @insertcopying Published by ... @end titlepage @c So the toc is printed at the start. @contents @ifnottex @node Top @top TITLE This manual is for PROGRAM, version VERSION. @end ifnottex @menu * First Chapter:: Getting started ... * Second Chapter:: ... ... * Copying:: Your rights and freedoms. @end menu @node First Chapter @chapter First Chapter @cindex first chapter @cindex chapter, first ... 3.2 Texinfo File Header ======================= Texinfo files start with at least three lines that provide Info and TeX with necessary information. These are the `\input texinfo' line, the `@settitle' line, and the `@setfilename' line. Also, if you want to format just part of the Texinfo file, you must write the `@settitle' and `@setfilename' lines between start-of-header and end-of-header lines. The start- and end-of-header lines are optional, but they do no harm, so you might as well always include them. Any command that affects document formatting as a whole makes sense to include in the header. `@synindex' (*note synindex::), for instance, is another command often included in the header. *Note GNU Sample Texts::, for complete sample texts. Thus, the beginning of a Texinfo file generally looks like this: \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename sample.info @settitle Sample Manual 1.0 @c %**end of header 3.2.1 The First Line 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: \input texinfo @c -*-texinfo-*- This line serves two functions: 1. When the file is processed by TeX, the `\input texinfo' command tells TeX to load the macros needed for processing a Texinfo file. These are in a file called `texinfo.tex', which should have been installed on your system along with either the TeX or Texinfo software. TeX uses the backslash, `\', to mark the beginning of a command, exactly as Texinfo uses `@'. The `texinfo.tex' file causes the switch from `\' to `@'; before the switch occurs, TeX requires `\', which is why it appears at the beginning of the file. 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode specification tells Emacs to use Texinfo mode. 3.2.2 Start of Header --------------------- A start-of-header line is a Texinfo comment that looks like this: @c %**start of header Write the start-of-header line on the second line of a Texinfo file. Follow the start-of-header line with `@setfilename' and `@settitle' lines and, optionally, with other commands that globally affect the document formatting, such as `@synindex' or `@footnotestyle'; and then by an end-of-header line (*note End of Header::). The start- and end-of-header lines allow you to format only part of a Texinfo file for Info or printing. *Note texinfo-format commands::. The odd string of characters, `%**', is to ensure that no other comment is accidentally taken for a start-of-header line. You can change it if you wish by setting the `tex-start-of-header' and/or `tex-end-of-header' Emacs variables. *Note Texinfo Mode Printing::. 3.2.3 `@setfilename': Set the output file name ---------------------------------------------- In order to serve as the primary input file for either `makeinfo' or TeX, a Texinfo file must contain a line that looks like this: @setfilename INFO-FILE-NAME Write the `@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 what would otherwise be a comment. The Info formatting commands ignore everything written before the `@setfilename' line, which is why the very first line of the file (the `\input' line) does not show up in the output. The `@setfilename' line specifies the name of the output file to be generated. This name must be different from the name of the Texinfo file. There are two conventions for choosing the name: you can either remove the extension (such as `.texi') entirely from the input file name, or, preferably, replace it with the `.info' extension. Although an explicit `.info' extension is preferable, 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', ..., `-10', `-11', and so on, to the original file name. (*Note Tag and Split Files::.) The subfile name `texinfo.info-10', for example, is too long for old systems with a 14-character limit on filenames; so the Info file name for this document is `texinfo' rather than `texinfo.info'. When `makeinfo' is running on operating systems such as MS-DOS which impose severe limits on file names, it may remove some characters from the original file name to leave enough space for the subfile suffix, thus producing files named `texin-10', `gcc.i12', etc. When producing HTML output, `makeinfo' will replace any extension with `html', or add `.html' if the given name has no extension. The `@setfilename' line produces no output when you typeset a manual with TeX, but it is nevertheless essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads `texinfo.cnf' if that file is present on your system (*note Preparing for TeX: Preparing for TeX.). 3.2.4 `@settitle': Set the document title ----------------------------------------- In order to be made into a printed manual, a Texinfo file must contain a line that looks like this: @settitle TITLE Write the `@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 what would otherwise be a comment. The `@settitle' command should precede everything that generates actual output. The best place for it is right after the `@setfilename' command (see the previous section). In the HTML file produced by `makeinfo', TITLE serves as the document `'. It also becomes the default document description in the `<head>' part (*note documentdescription::). The title in the `@settitle' command does not affect the title as it appears on the title page. Thus, the two do not need not match exactly. A practice we recommend is to include the version or edition number of the manual in the `@settitle' title; on the title page, the version number generally appears as a `@subtitle' so it would be omitted from the `@title'. *Note titlepage::. 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 `@chapter' command.) By default, no page footer is printed. Even if you are printing in a single-sided style, TeX looks for an `@settitle' command line, in case you include the manual title in the heading. TeX prints page headings only for that text that comes after the `@end titlepage' command in the Texinfo file, or that comes after an `@headings' command that turns on headings. (*Note The `@headings' Command: headings on off, for more information.) You may, if you wish, create your own, customized headings and footings. *Note Headings::, for a detailed discussion of this. 3.2.5 End of Header ------------------- Follow the header lines with an end-of-header line, which is a Texinfo comment that looks like this: @c %**end of header *Note Start of Header::. 3.3 Document Permissions ======================== The copyright notice and copying permissions for a document need to appear in several places in the various Texinfo output formats. Therefore, Texinfo provides a command (`@copying') to declare this text once, and another command (`@insertcopying') to insert the text at appropriate points. 3.3.1 `@copying': Declare Copying Permissions --------------------------------------------- The `@copying' command should be given very early in the document; the recommended location is right after the header material (*note Texinfo File Header::). It conventionally consists of a sentence or two about what the program is, identification of the documentation itself, the legal copyright line, and the copying permissions. Here is a skeletal example: @copying This manual is for PROGRAM (version VERSION, updated DATE), which ... Copyright @copyright{} YEARS COPYRIGHT-OWNER. @quotation Permission is granted to ... @end quotation @end copying The `@quotation' has no legal significance; it's there to improve readability in some contexts. *Note GNU Sample Texts::, for the full text to be used in GNU manuals. *Note GNU Free Documentation License::, for the license itself under which GNU and other free manuals are distributed. You need to include the license as an appendix to your document. The text of `@copying' is output as a comment at the beginning of Info, HTML, and XML output files. It is _not_ output implicitly in plain text or TeX; it's up to you to use `@insertcopying' to emit the copying information. See the next section for details. The `@copyright{}' command generates a `c' inside a circle in output formats that support this (print and HTML). In the other formats (Info and plain text), it generates `(C)'. The copyright notice itself has the following legally defined sequence: Copyright (C) YEARS COPYRIGHT-OWNER. The word `Copyright' must always be written in English, even if the document is otherwise written in another language. This is due to international law. The list of years should include all years in which a version was completed (even if it was released in a subsequent year). Ranges are not allowed; each year must be written out individually and in full, separated by commas. The copyright owner (or owners) is whoever holds legal copyright on the work. In the case of works assigned to the FSF, the owner is `Free Software Foundation, Inc.'. The copyright `line' may actually be split across multiple lines, both in the source document and in the output. This often happens for documents with a long history, having many different years of publication. If you do use several lines, do not indent any of them (or anything else in the `@copying' block) in the source file. *Note Copyright Notices: (maintain)Copyright Notices, for additional information. 3.3.2 `@insertcopying': Include Permissions Text ------------------------------------------------ The `@insertcopying' command is simply written on a line by itself, like this: @insertcopying This inserts the text previously defined by `@copying'. To meet legal requirements, it must be used on the copyright page in the printed manual (*note Copyright::). The `@copying' command itself causes the permissions text to appear in an Info file _before_ the first node. The text is also copied into the beginning of each split Info output file, as is legally necessary. This location implies a human reading the manual using Info does _not_ see this text (except when using the advanced Info command `g *'), but this does not matter for legal purposes, because the text is present. Similarly, the `@copying' text is automatically included at the beginning of each HTML output file, as an HTML comment. Again, this text is not visible (unless the reader views the HTML source). The permissions text defined by `@copying' also appears automatically at the beginning of the XML output file. 3.4 Title and Copyright Pages ============================= In hard copy output, the manual's name and author are usually printed on a title page. Copyright information is usually 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 appears in the printed manual. You may wish to include titlepage-like information for plain text output. Simply place any such leading material between `@ifplaintext' and `@end ifplaintext'; `makeinfo' includes this when writing plain text (`--no-headers'), along with an `@insertcopying'. 3.4.1 `@titlepage' ------------------ Start the material for the title page and following copyright page with `@titlepage' on a line by itself and end it with `@end titlepage' on a line by itself. The `@end titlepage' command starts a new page and turns on page numbering. (*Note Page Headings: 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 `@titlepage' and `@end titlepage' commands. You can force the table of contents to appear there with the `@setcontentsaftertitlepage' command (*note Contents::). By using the `@page' command you can force a page break within the region delineated by the `@titlepage' and `@end titlepage' commands and thereby create more than one unnumbered page. This is how the copyright page is produced. (The `@titlepage' command might perhaps have been better named the `@titleandadditionalpages' command, but that would have been rather long!) 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(1) 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 *note The Top Node::.) Texinfo provides two main methods for creating a title page. One method uses the `@titlefont', `@sp', and `@center' commands to generate a title page in which the words on the page are centered. The second method uses the `@title', `@subtitle', and `@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, or you may combine them; see the examples in the sections below. For extremely simple documents, and for the bastard title page in traditional book frontmatter, Texinfo also provides a command `@shorttitlepage' which takes the rest of the line as the title. The argument is typeset on a page by itself and followed by a blank page. ---------- Footnotes ---------- (1) We have found that it is helpful to refer to versions of independent 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. 3.4.2 `@titlefont', `@center', and `@sp' ---------------------------------------- You can use the `@titlefont', `@sp', and `@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.) Use the `@titlefont' command to select a large font suitable for the title itself. You can use `@titlefont' more than once if you have an especially long title. For HTML output, each `@titlefont' command produces an `<h1>' heading, but the HTML document `<title>' is not affected. For that, you must put an `@settitle' command before the `@titlefont' command (*note settitle::). For example: @titlefont{Texinfo} Use the `@center' command at the beginning of a line to center the remaining text on that line. Thus, @center @titlefont{Texinfo} centers the title, which in this example is "Texinfo" printed in the title font. Use the `@sp' command to insert vertical space. For example: @sp 2 This inserts two blank lines on the printed page. (*Note `@sp': sp, for more information about the `@sp' command.) A template for this method looks like this: @titlepage @sp 10 @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED} @sp 2 @center SUBTITLE-IF-ANY @sp 2 @center AUTHOR ... @end titlepage The spacing of the example fits an 8.5 by 11 inch manual. You can in fact use these commands anywhere, not just on a title page, but since they are not logical markup commands, we don't recommend them. 3.4.3 `@title', `@subtitle', and `@author' ------------------------------------------ You can use the `@title', `@subtitle', and `@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 `@sp' command is needed to adjust vertical spacing. Write the `@title', `@subtitle', or `@author' commands at the beginning of a line followed by the title, subtitle, or author. These commands are only effective in TeX output; it's an error to use them anywhere except within `@titlepage'. The `@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. Only a single line is allowed; the `@*' command may not be used to break the title into two lines. To handle very long titles, you may find it profitable to use both `@title' and `@titlefont'; see the final example in this section. The `@subtitle' command sets subtitles in a normal-sized font flush to the right-hand side of the page. The `@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 `@author' command line is followed by an `@page' command line.) There are two ways to use the `@author' command: you can write the name or names on the remaining part of the line that starts with an `@author' command: @author by Jane Smith and John Doe or you can write the names one above each other by using two (or more) `@author' commands: @author Jane Smith @author John Doe (Only the bottom name is underlined with a black rule.) A template for this method looks like this: @titlepage @title NAME-OF-MANUAL-WHEN-PRINTED @subtitle SUBTITLE-IF-ANY @subtitle SECOND-SUBTITLE @author AUTHOR @page ... @end titlepage You may also combine the `@titlefont' method described in the previous section and `@title' method described in this one. This may be useful if you have a very long title. Here is a real-life example: @titlepage @titlefont{GNU Software} @sp 1 @title for MS-Windows and MS-DOS @subtitle Edition @value{e} for Release @value{cde} @author by Daniel Hagerty, Melissa Weisshaus @author and Eli Zaretskii (The use of `@value' here is explained in *note value Example::. 3.4.4 Copyright Page -------------------- By international treaty, the copyright notice for a book must be either on the title page or on the back of the title page. 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 `@titlepage' and `@end titlepage' commands. Use the `@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, use the following incantation after `@page': @vskip 0pt plus 1filll This is a TeX command that is not supported by the Info formatting commands. The `@vskip' command inserts whitespace. The `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 `l's in the word `filll'; this is correct. To insert the copyright text itself, write `@insertcopying' next (*note Document Permissions::): @insertcopying Follow the copying text by the publisher, ISBN numbers, cover art credits, and other such information. Here is an example putting all this together: @titlepage ... @page @vskip 0pt plus 1filll @insertcopying Published by ... Cover art by ... @end titlepage 3.4.5 Heading Generation ------------------------ Like all `@end' commands (*note Quotations and Examples::), the `@end titlepage' command must be written at the beginning of a line by itself, with only one space between the `@end' and the `titlepage'. It 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). You can specify these formats in different ways: * The conventional way is to write an `@setchapternewpage' command before the title page commands, and then have the `@end titlepage' command start generating page headings in the manner desired. (*Note setchapternewpage::.) * Alternatively, you can use the `@headings' command to prevent page headings from being generated or to start them for either single or double-sided printing. (Write an `@headings' command immediately after the `@end titlepage' command. *Note The `@headings' Command: headings on off, for more information.) * Or, you may specify your own page heading and footing format. *Note Page Headings: Headings, for detailed information about page headings and footings. Most documents are formatted with the standard single-sided or double-sided format, using `@setchapternewpage odd' for double-sided printing and no `@setchapternewpage' command for single-sided printing. 3.4.6 The `@headings' Command ----------------------------- The `@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 `@setchapternewpage' command. You need the `@headings' command only if the `@setchapternewpage' command does not do what you want, or if you want to turn off predefined page headings prior to defining your own. Write an `@headings' command immediately after the `@end titlepage' command. You can use `@headings' as follows: `@headings off' Turn off printing of page headings. `@headings single' Turn on page headings appropriate for single-sided printing. `@headings double' Turn on page headings appropriate for double-sided printing. `@headings singleafter' `@headings doubleafter' Turn on `single' or `double' headings, respectively, after the current page is output. `@headings on' Turn on page headings: `single' if `@setchapternewpage on', `double' otherwise. For example, suppose you write `@setchapternewpage off' before the `@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 `@headings double' after the `@end titlepage' command. You can stop TeX from generating any page headings at all by writing `@headings off' on a line of its own immediately after the line containing the `@end titlepage' command, like this: @end titlepage @headings off The `@headings off' command overrides the `@end titlepage' command, which would otherwise cause TeX to print page headings. You can also specify your own style of page heading and footing. *Note Page Headings: Headings, for more information. 3.5 Generating a Table of Contents ================================== The `@chapter', `@section', and other structuring commands (*note Structuring::) 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 `@contents' and/or `@summarycontents' command(s). `@contents' Generates a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. Headings generated by `@majorheading', `@chapheading', and the other `@...heading' commands do not appear in the table of contents (*note Structuring Command Types::). `@shortcontents' `@summarycontents' (`@summarycontents' is a synonym for `@shortcontents'.) Generates a short or summary table of contents that lists only the chapters, appendices, and unnumbered chapters. Sections, subsections and subsubsections are omitted. Only a long manual needs a short table of contents in addition to the full table of contents. Both contents commands should be written on a line by themselves, and are best placed near the beginning of the file, after the `@end titlepage' (*note titlepage::). The contents commands automatically generate a chapter-like heading at the top of the first table of contents page, so don't include any sectioning command such as `@unnumbered' before them. Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are included in plain text output (generated by `makeinfo --no-headers'), unless `makeinfo' is writing its output to standard output. When `makeinfo' writes a short table of contents while producing HTML output, the links in the short table of contents point to corresponding entries in the full table of contents rather than the text of the document. The links in the full table of contents point to the main text of the document. In the past, the contents commands were sometimes placed at the end of the file, after any indices and just before the `@bye', but we no longer recommend this. However, since many existing Texinfo documents still do have the `@contents' at the end of the manual, if you are a user printing a manual, you may wish to force the contents to be printed after the title page. You can do this by specifying `@setcontentsaftertitlepage' and/or `@setshortcontentsaftertitlepage'. The first prints only the main contents after the `@end titlepage'; the second prints both the short contents and the main contents. In either case, any subsequent `@contents' or `@shortcontents' is ignored (unless, erroneously, no `@end titlepage' is ever encountered). You need to include the `@set...contentsaftertitlepage' commands early in the document (just after `@setfilename', for example). We recommend using `texi2dvi' (*note Format with texi2dvi::) to specify this without altering the source file at all. For example: texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi 3.6 The `Top' Node and Master Menu ================================== The `Top' node is the node in which a reader enters an Info manual. As such, it should begin with a brief description of the manual (including the version number), and end with a master menu for the whole manual. Of course you should include any other general information you feel a reader would find helpful. It is conventional and desirable to write an `@top' sectioning command line containing the title of the document immediately after the `@node Top' line (*note The `@top' Sectioning Command: makeinfo top command.). The contents of the `Top' node should appear only in the online output; none of it should appear in printed output, so enclose it between `@ifnottex' and `@end ifnottex' commands. (TeX does not print either an `@node' line or a menu; they appear only in Info; strictly speaking, you are not required to enclose these parts between `@ifnottex' and `@end ifnottex', but it is simplest to do so. *Note Conditionally Visible Text: Conditionals.) 3.6.1 Top Node Example ---------------------- Here is an example of a Top node. @ifnottex @node Top @top Sample Title @insertcopying @end ifnottex Additional general information. @menu * First Chapter:: * Second Chapter:: ... * Index:: @end menu 3.6.2 Parts of a Master Menu ---------------------------- A "master menu" is a detailed main menu listing all the nodes in a file. A master menu is enclosed in `@menu' and `@end menu' commands and does not appear in the printed document. Generally, a master menu is divided into parts. * The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections, and the appendices. * The second part contains nodes for the indices. * 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 `@detailmenu' before the first one, and `@end detailmenu' after the last; otherwise, `makeinfo' will get confused. 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. (*Note Writing a Menu::, for more information.) For example, the master menu for this manual looks like the following (but has many more entries): @menu * Copying Conditions:: Your rights. * Overview:: Texinfo in brief. ... * Command and Variable Index:: * General Index:: @detailmenu --- The Detailed Node Listing --- Overview of Texinfo * Reporting Bugs:: ... ... Beginning a Texinfo File * Sample Beginning:: ... ... @end detailmenu @end menu 3.7 Global Document Commands ============================ Besides the basic commands mentioned in the previous sections, here are additional commands which affect the document as a whole. They are generally all given before the Top node, if they are given at all. 3.7.1 `@documentdescription': Summary Text ------------------------------------------ When producing HTML output for a document, `makeinfo' writes a `<meta>' element in the `<head>' to give some idea of the content of the document. By default, this "description" is the title of the document, taken from the `@settitle' command (*note settitle::). To change this, use the `@documentdescription' environment, as in: @documentdescription descriptive text. @end documentdescription This will produce the following output in the `<head>' of the HTML: <meta name=description content="descriptive text."> `@documentdescription' must be specified before the first node of the document. 3.7.2 `@setchapternewpage': --------------------------- In an officially bound book, 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. You can use the `@setchapternewpage' command with various arguments to specify how TeX should start chapters and whether it should format headers for printing on one or both sides of the paper (single-sided or double-sided printing). Write the `@setchapternewpage' command at the beginning of a line followed by its argument. For example, you would write the following to cause each chapter to start on a fresh odd-numbered page: @setchapternewpage odd You can specify one of three alternatives with the `@setchapternewpage' command: `@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. `@setchapternewpage on' Cause TeX to start new chapters on new pages and to format page headers for single-sided printing. This is the form most often used for short reports or personal printing. This is the default. `@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. Texinfo does not have an `@setchapternewpage even' command, because there is no printing tradition of starting chapters or books on an even-numbered page. If you don't like the default headers that `@setchapternewpage' sets, you can explicit control them with the `@headings' command. *Note The `@headings' Command: headings on off. 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 and frontmatter pages are numbered with roman numerals and not in sequence with the rest of the document. Since an Info file does not have pages, the `@setchapternewpage' command has no effect on it. We recommend not including any `@setchapternewpage' command in your manual sources at all, since the desired output is not intrinsic to the document. For a particular hard copy run, if you don't want the default option (no blank pages, same headers on all pages) use the `--texinfo' option to `texi2dvi' to specify the output you want. 3.7.3 `@paragraphindent': Paragraph Indenting --------------------------------------------- The Texinfo processors may insert whitespace at the beginning of the first line of each paragraph, thereby indenting that paragraph. You can use the `@paragraphindent' command to specify this indentation. Write an `@paragraphindent' command at the beginning of a line followed by either `asis' or a number: @paragraphindent INDENT The indentation is according to the value of INDENT: `asis' Do not change the existing indentation (not implemented in TeX). `none' 0 Omit all indentation. N Indent by N space characters in Info output, by N ems in TeX. The default value of INDENT is 3. `@paragraphindent' is ignored for HTML output. It is best to write the `@paragraphindent' command before the end-of-header line at the beginning of a Texinfo file, so the region formatting commands indent paragraphs as specified. *Note Start of Header::. A peculiarity of the `texinfo-format-buffer' and `texinfo-format-region' commands is that they do not indent (nor fill) paragraphs that contain `@w' or `@*' commands. 3.7.4 `@firstparagraphindent': Indenting After Headings ------------------------------------------------------- As you can see in the present manual, the first paragraph in any section is not indented by default. Typographically, indentation is a paragraph separator, which means that it is unnecessary when a new section begins. This indentation is controlled with the `@firstparagraphindent' command: @firstparagraphindent WORD The first paragraph after a heading is indented according to the value of WORD: `none' Prevents the first paragraph from being indented (default). This option is ignored by `makeinfo' if `@paragraphindent asis' is in effect. `insert' Include normal paragraph indentation. This respects the paragraph indentation set by a `@paragraphindent' command (*note paragraphindent::). For HTML and XML output, the `@firstparagraphindent' setting is ignored. It is best to write the `@paragraphindent' command before the end-of-header line at the beginning of a Texinfo file, so the region formatting commands indent paragraphs as specified. *Note Start of Header::. 3.7.5 `@exampleindent': Environment Indenting --------------------------------------------- The Texinfo processors indent each line of `@example' and similar environments. You can use the `@exampleindent' command to specify this indentation. Write an `@exampleindent' command at the beginning of a line followed by either `asis' or a number: @exampleindent INDENT `@exampleindent' is ignored for HTML output. Otherwise, the indentation is according to the value of INDENT: `asis' Do not change the existing indentation (not implemented in TeX). 0 Omit all indentation. N Indent environments by N space characters in Info output, by N ems in TeX. The default value of INDENT is 5 spaces in Info, and 0.4in in TeX, which is somewhat less. (The reduction is to help TeX fit more characters onto physical lines.) It is best to write the `@exampleindent' command before the end-of-header line at the beginning of a Texinfo file, so the region formatting commands indent paragraphs as specified. *Note Start of Header::. 3.8 Software Copying Permissions ================================ 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, we recommend placing this right after 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. The copying and distribution information and the disclaimer are followed by an introduction or else by the first chapter of the manual. 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. 4 Ending a Texinfo File *********************** The end of a Texinfo file should include commands to create indices, and the `@bye' command to mark the last line to be processed. For example: @node Index @unnumbered Index @printindex cp @bye 4.1 Printing Indices and Menus ============================== 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 `@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 `@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 `texindex' (*note 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. Texinfo offers six separate types of predefined index, which suffice in most cases. *Note Indices::, for information on this, as well defining your own new indices, combining indices, and, most importantly advice on writing the actual index entries. This section focuses on printing indices, which is done with the `@printindex' command. `@printindex' takes one argument, a two-letter index abbreviation. It reads the corresponding sorted index file (for printed output), and formats it appropriately into an index. The `@printindex' command does not generate a chapter heading for the index, since different manuals have different needs. Consequently, you should precede the `@printindex' command with a suitable section or chapter command (usually `@appendix' or `@unnumbered') to supply the chapter heading and put the index into the table of contents. Precede the chapter heading with an `@node' line as usual. For example: @node Variable Index @unnumbered Variable Index @printindex vr @node Concept Index @unnumbered Concept Index @printindex cp If you have more than one index, we recommend placing the concept index last. * In printed output, `@printindex' produces a traditional two-column index, with dot leaders between the index terms and page numbers. * In Info output, `@printindex' produces a special menu containing the line number of the entry, relative to the start of the node. Info readers can use this to go to the exact line of an entry, not just the containing node. (Older Info readers will just go to the node.) Here's an example: * First index entry: Top. (line 7) The actual number of spaces is variable, to right-justify the line number; it's been reduced here to make the line fit in the printed manual. * In plain text output, `@printindex' produces the same menu, but the line numbers are relative to the start of the file, since that's more convenient for that format. * In HTML and Docbook output, `@printindex' produces links to the index entries. * In XML output, it simply records the index to be printed. It's not possible to generate an index when writing to standard output; `makeinfo' generates a warning in this case. 4.2 `@bye' File Ending ====================== An `@bye' command terminates Texinfo processing. None of the formatters read anything following `@bye'. The `@bye' command should be on a line by itself. If you wish, you may follow the `@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 `@bye' were within `@ignore' ... `@end ignore'. Also, you may follow the `@bye' line with a local variables list for Emacs. *Note Using Local Variables and the Compile Command: Compile-Command, for more information. 5 Chapter Structuring ********************* The "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 (*note Generating a Table of Contents: Contents.). The chapter structuring commands do not create an Info node structure, so normally you should put an `@node' command immediately before each chapter structuring command (*note 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. 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. 5.1 Tree Structure of Sections ============================== 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. Here is a diagram that shows a Texinfo file with three chapters, each of which has two sections. 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 In a Texinfo file that has this structure, the beginning of Chapter 2 looks like this: @node Chapter 2, Chapter 3, Chapter 1, top @chapter Chapter 2 The chapter structuring commands are described in the sections that follow; the `@node' and `@menu' commands are described in following chapters. (*Note Nodes::, and see *note Menus::.) 5.2 Structuring Command Types ============================= 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. The four groups are the `@chapter' series, the `@unnumbered' series, the `@appendix' series, and the `@heading' series. 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. * The `@chapter' and `@appendix' series of commands produce numbered or lettered entries both in the body of a printed work and in its table of contents. * The `@unnumbered' series of commands produce unnumbered entries both in the body of a printed work and in its table of contents. The `@top' command, which has a special use, is a member of this series (*note `@top': makeinfo top.). An `@unnumbered' section should be associated with a node and be a normal part of the document structure. * The `@heading' series of commands produce simple unnumbered headings that do not appear in a table of contents, are not associated with nodes, and cannot be cross-referenced. The heading commands never start a new page. * The `@majorheading' command is similar to `@chapheading', except that it generates a larger vertical whitespace before the heading. * When an `@setchapternewpage' command says to do so, the `@chapter', `@unnumbered', and `@appendix' commands start new pages in the printed manual; the `@heading' commands do not. Here are the four groups of chapter structuring commands: No new page Numbered Unnumbered Lettered/numbered Unnumbered In contents In contents In contents Not in contents `@top' `@majorheading' `@chapter' `@unnumbered' `@appendix' `@chapheading' `@section' `@unnumberedsec' `@appendixsec' `@heading' `@subsection' `@unnumberedsubsec' `@appendixsubsec' `@subheading' `@subsubsection'`@unnumberedsubsubsec' `@appendixsubsubsec' `@subsubheading' 5.3 `@top' ========== The `@top' command is a special sectioning command that you use only after an `@node Top' line at the beginning of a Texinfo file. The `@top' command tells the `makeinfo' formatter which node is the `Top' node, so it can use it as the root of the node tree if your manual uses implicit node pointers. It has the same typesetting effect as `@unnumbered' (*note `@unnumbered' and `@appendix': unnumbered & appendix.). For detailed information, see *note The `@top' Command: makeinfo top command. The `@top' node and its menu (if any) is conventionally wrapped in an `@ifnottex' conditional so that it will appear only in Info and HTML output, not TeX. 5.4 `@chapter' ============== `@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. For example, this chapter in this manual is entitled "Chapter Structuring"; the `@chapter' line looks like this: @chapter Chapter Structuring In TeX, the `@chapter' command creates a chapter in the document, specifying the chapter title. The chapter is numbered automatically. In Info, the `@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: Chapter Structuring ******************* Texinfo also provides a command `@centerchap', which is analogous to `@unnumbered', but centers its argument in the printed output. This kind of stylistic choice is not usually offered by Texinfo. 5.5 `@unnumbered' and `@appendix' ================================= Use the `@unnumbered' command to create a chapter that appears in a printed manual without chapter numbers of any kind. Use the `@appendix' command to create an appendix in a printed manual that is labelled by letter (`A', `B', ...) instead of by number. Write an `@appendix' or `@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. 5.6 `@majorheading', `@chapheading' =================================== The `@majorheading' and `@chapheading' commands put chapter-like headings in the body of a document. 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. In TeX, an `@majorheading' command generates a larger vertical whitespace before the heading than an `@chapheading' command but is otherwise the same. In Info, the `@majorheading' and `@chapheading' commands are equivalent to `@chapter': the title is printed on a line by itself with a line of asterisks underneath. (*Note `@chapter': chapter.) 5.7 `@section' ============== A `@section' command identifies a section within a chapter unit, whether created with `@chapter', `@unnumbered', or `@appendix', following the numbering scheme of the chapter-level command. Thus, within a `@chapter' chapter numbered `1', the section is numbered like `1.2'; within an `@appendix' "chapter" labeled `A', the section is numbered like `A.2'; within an `@unnumbered' chapter, the section gets no number. For example, this section is headed with an `@section' command and looks like this in the Texinfo file: @section @code{@@section} To create a section, write the `@section' command at the beginning of a line and follow it on the same line by the section title. The output is und