1 This is ../info/texinfo.info, produced by makeinfo version 4.6 from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
41 Texinfo is a documentation system that uses a single source file to
42 produce both on-line information and printed output.
44 The first part of this master menu lists the major nodes in this Info
45 document, including the @-command and concept indices. The rest of the
46 menu lists all the lower level nodes in the document.
48 This is Edition 3.12 of the Texinfo documentation, 27 February 1998.
52 * Copying:: Your rights.
53 * Overview:: Texinfo in brief.
54 * Texinfo Mode:: How to use Texinfo mode.
55 * Beginning a File:: What is at the beginning of a Texinfo file?
56 * Ending a File:: What is at the end of a Texinfo file?
57 * Structuring:: How to create chapters, sections, subsections,
58 appendices, and other parts.
59 * Nodes:: How to write nodes.
60 * Menus:: How to write menus.
61 * Cross References:: How to write cross references.
62 * Marking Text:: How to mark words and phrases as code,
63 keyboard input, meta-syntactic
64 variables, and the like.
65 * Quotations and Examples:: How to write quotations, examples, etc.
66 * Lists and Tables:: How to write lists and tables.
67 * Indices:: How to create indices.
68 * Insertions:: How to insert @-signs, braces, etc.
69 * Breaks:: How to force and prevent line and page breaks.
70 * Definition Commands:: How to describe functions and the like
72 * Footnotes:: How to write footnotes.
73 * Conditionals:: How to specify text for either TeX or Info.
74 * Macros:: Defining new Texinfo commands.
75 * Format/Print Hardcopy:: How to convert a Texinfo file to a file
76 for printing and how to print that file.
77 * Create an Info File:: Convert a Texinfo file into an Info file.
78 * Install an Info File:: Make an Info file accessible to users.
79 * Command List:: All the Texinfo @-commands.
80 * Tips:: Hints on how to write a Texinfo document.
81 * Sample Texinfo File:: A sample Texinfo file to look at.
82 * Sample Permissions:: Tell readers they have the right to copy
84 * Include Files:: How to incorporate other Texinfo files.
85 * Headings:: How to write page headings and footings.
86 * Catching Mistakes:: How to find formatting mistakes.
87 * Refilling Paragraphs:: All about paragraph refilling.
88 * Command Syntax:: A description of @-Command syntax.
89 * Obtaining TeX:: How to Obtain TeX.
90 * Command and Variable Index:: A menu containing commands and variables.
91 * Concept Index:: A menu covering many topics.
94 --- The Detailed Node Listing ---
98 * Using Texinfo:: Create a conventional printed book
100 * Info Files:: What is an Info file?
101 * Printed Books:: Characteristics of a printed book or manual.
102 * Formatting Commands:: @-commands are used for formatting.
103 * Conventions:: General rules for writing a Texinfo file.
104 * Comments:: How to write comments and mark regions that
105 the formatting commands will ignore.
106 * Minimum:: What a Texinfo file must have.
107 * Six Parts:: Usually, a Texinfo file has six parts.
108 * Short Sample:: A short sample Texinfo file.
113 * Texinfo Mode Overview:: How Texinfo mode can help you.
114 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
115 purpose editing features.
116 * Inserting:: How to insert frequently used @-commands.
117 * Showing the Structure:: How to show the structure of a file.
118 * Updating Nodes and Menus:: How to update or create new nodes and menus.
119 * Info Formatting:: How to format for Info.
120 * Printing:: How to format and print part or all of a file.
121 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
123 Updating Nodes and Menus
125 * Updating Commands:: Five major updating commands.
126 * Updating Requirements:: How to structure a Texinfo file for
127 using the updating command.
128 * Other Updating Commands:: How to indent descriptions, insert
129 missing nodes lines, and update
132 Beginning a Texinfo File
134 * Four Parts:: Four parts begin a Texinfo file.
135 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
136 * Header:: The very beginning of a Texinfo file.
137 * Info Summary and Permissions:: Summary and copying permissions for Info.
138 * Titlepage & Copyright Page:: Creating the title and copyright pages.
139 * The Top Node:: Creating the `Top' node and master menu.
140 * Software Copying Permissions:: Ensure that you and others continue to
141 have the right to use and share software.
143 The Texinfo File Header
145 * First Line:: The first line of a Texinfo file.
146 * Start of Header:: Formatting a region requires this.
147 * setfilename:: Tell Info the name of the Info file.
148 * settitle:: Create a title for the printed work.
149 * setchapternewpage:: Start chapters on right-hand pages.
150 * paragraphindent:: An option to specify paragraph indentation.
151 * End of Header:: Formatting a region requires this.
153 The Title and Copyright Pages
155 * titlepage:: Create a title for the printed document.
156 * titlefont center sp:: The `@titlefont', `@center',
158 * title subtitle author:: The `@title', `@subtitle',
159 and `@author' commands.
160 * Copyright & Permissions:: How to write the copyright notice and
161 include copying permissions.
162 * end titlepage:: Turn on page headings after the title and
164 * headings on off:: An option for turning headings on and off
165 and double or single sided printing.
167 The `Top' Node and Master Menu
169 * Title of Top Node:: Sketch what the file is about.
170 * Master Menu Parts:: A master menu has three or more parts.
172 Ending a Texinfo File
174 * Printing Indices & Menus:: How to print an index in hardcopy and
175 generate index menus in Info.
176 * Contents:: How to create a table of contents.
177 * File End:: How to mark the end of a file.
181 * Tree Structuring:: A manual is like an upside down tree ...
182 * Structuring Command Types:: How to divide a manual into parts.
183 * makeinfo top:: The `@top' command, part of the `Top' node.
185 * unnumbered & appendix::
186 * majorheading & chapheading::
188 * unnumberedsec appendixsec heading::
190 * unnumberedsubsec appendixsubsec subheading::
191 * subsubsection:: Commands for the lowest level sections.
192 * Raise/lower sections:: How to change commands' hierarchical level.
196 * Two Paths:: Different commands to structure
197 Info output and printed output.
198 * Node Menu Illustration:: A diagram, and sample nodes and menus.
199 * node:: How to write a node, in detail.
200 * makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
204 * Node Names:: How to choose node and pointer names.
205 * Writing a Node:: How to write an `@node' line.
206 * Node Line Tips:: Keep names short.
207 * Node Line Requirements:: Keep names unique, without @-commands.
208 * First Node:: How to write a `Top' node.
209 * makeinfo top command:: How to use the `@top' command.
210 * Top Node Summary:: Write a brief description for readers.
214 * Menu Location:: Put a menu in a short node.
215 * Writing a Menu:: What is a menu?
216 * Menu Parts:: A menu entry has three parts.
217 * Less Cluttered Menu Entry:: Two part menu entry.
218 * Menu Example:: Two and three part menu entries.
219 * Other Info Files:: How to refer to a different Info file.
223 * References:: What cross references are for.
224 * Cross Reference Commands:: A summary of the different commands.
225 * Cross Reference Parts:: A cross reference has several parts.
226 * xref:: Begin a reference with `See' ...
227 * Top Node Naming:: How to refer to the beginning of another file.
228 * ref:: A reference for the last part of a sentence.
229 * pxref:: How to write a parenthetical cross reference.
230 * inforef:: How to refer to an Info-only file.
231 * uref:: How to refer to a uniform resource locator.
235 * Reference Syntax:: What a reference looks like and requires.
236 * One Argument:: `@xref' with one argument.
237 * Two Arguments:: `@xref' with two arguments.
238 * Three Arguments:: `@xref' with three arguments.
239 * Four and Five Arguments:: `@xref' with four and five arguments.
241 Marking Words and Phrases
243 * Indicating:: How to indicate definitions, files, etc.
244 * Emphasis:: How to emphasize text.
246 Indicating Definitions, Commands, etc.
248 * Useful Highlighting:: Highlighting provides useful information.
249 * code:: How to indicate code.
250 * kbd:: How to show keyboard input.
251 * key:: How to specify keys.
252 * samp:: How to show a literal sequence of characters.
253 * var:: How to indicate a metasyntactic variable.
254 * file:: How to indicate the name of a file.
255 * dfn:: How to specify a definition.
256 * cite:: How to refer to a book that is not in Info.
257 * url:: How to indicate a world wide web reference.
258 * email:: How to indicate an electronic mail address.
262 * emph & strong:: How to emphasize text in Texinfo.
263 * Smallcaps:: How to use the small caps font.
264 * Fonts:: Various font commands for printed output.
265 * Customized Highlighting:: How to define highlighting commands.
267 Quotations and Examples
269 * Block Enclosing Commands:: Use different constructs for
271 * quotation:: How to write a quotation.
272 * example:: How to write an example in a fixed-width font.
273 * noindent:: How to prevent paragraph indentation.
274 * Lisp Example:: How to illustrate Lisp code.
275 * smallexample & smalllisp:: Forms for the `@smallbook' option.
276 * display:: How to write an example in the current font.
277 * format:: How to write an example that does not narrow
279 * exdent:: How to undo the indentation of a line.
280 * flushleft & flushright:: How to push text flushleft or flushright.
281 * cartouche:: How to draw cartouches around examples.
285 * Introducing Lists:: Texinfo formats lists for you.
286 * itemize:: How to construct a simple list.
287 * enumerate:: How to construct a numbered list.
288 * Two-column Tables:: How to construct a two-column table.
289 * Multi-column Tables:: How to construct generalized tables.
291 Making a Two-column Table
293 * table:: How to construct a two-column table.
294 * ftable vtable:: Automatic indexing for two-column tables.
295 * itemx:: How to put more entries in the first column.
299 * Multitable Column Widths:: Defining multitable column widths.
300 * Multitable Rows:: Defining multitable rows, with examples.
304 * Index Entries:: Choose different words for index entries.
305 * Predefined Indices:: Use different indices for different kinds
307 * Indexing Commands:: How to make an index entry.
308 * Combining Indices:: How to combine indices.
309 * New Indices:: How to define your own indices.
313 * syncodeindex:: How to merge two indices, using `@code'
314 font for the merged-from index.
315 * synindex:: How to merge two indices, using the
316 default font of the merged-to index.
320 * Braces Atsigns:: How to insert braces, `@'.
321 * Inserting Space:: How to insert the right amount of space
323 * Inserting Accents:: How to insert accents and special characters.
324 * Dots Bullets:: How to insert dots and bullets.
325 * TeX and copyright:: How to insert the TeX logo
326 and the copyright symbol.
327 * pounds:: How to insert the pounds currency symbol.
328 * minus:: How to insert a minus sign.
329 * math:: How to format a mathematical expression.
330 * Glyphs:: How to indicate results of evaluation,
331 expansion of macros, errors, etc.
332 * Images:: How to include graphics.
334 Inserting @ and Braces
336 * Inserting An Atsign:: How to insert `@'.
337 * Inserting Braces:: How to insert `{' and `}'.
341 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
342 * Ending a Sentence:: Sometimes it does.
343 * Multiple Spaces:: Inserting multiple spaces.
344 * dmn:: How to format a dimension.
346 Inserting Ellipsis, Dots, and Bullets
348 * dots:: How to insert dots ...
349 * bullet:: How to insert a bullet.
351 Inserting TeX and the Copyright Symbol
353 * tex:: How to insert the TeX logo.
354 * copyright symbol:: How to use `@copyright'{}.
359 * result:: How to show the result of expression.
360 * expansion:: How to indicate an expansion.
361 * Print Glyph:: How to indicate printed output.
362 * Error Glyph:: How to indicate an error message.
363 * Equivalence:: How to indicate equivalence.
364 * Point Glyph:: How to indicate the location of point.
375 Making and Preventing Breaks
377 * Break Commands:: Cause and prevent splits.
378 * Line Breaks:: How to force a single line to use two lines.
379 * - and hyphenation:: How to tell TeX about hyphenation points.
380 * w:: How to prevent unwanted line breaks.
381 * sp:: How to insert blank lines.
382 * page:: How to force the start of a new page.
383 * group:: How to prevent unwanted page breaks.
384 * need:: Another way to prevent unwanted page breaks.
388 * Def Cmd Template:: How to structure a description using a
390 * Optional Arguments:: How to handle optional and repeated arguments.
391 * deffnx:: How to group two or more `first' lines.
392 * Def Cmds in Detail:: All the definition commands.
393 * Def Cmd Conventions:: Conventions for writing definitions.
394 * Sample Function Definition::
396 The Definition Commands
398 * Functions Commands:: Commands for functions and similar entities.
399 * Variables Commands:: Commands for variables and similar entities.
400 * Typed Functions:: Commands for functions in typed languages.
401 * Typed Variables:: Commands for variables in typed languages.
402 * Abstract Objects:: Commands for object-oriented programming.
403 * Data Types:: The definition command for data types.
407 * Footnote Commands:: How to write a footnote in Texinfo.
408 * Footnote Styles:: Controlling how footnotes appear in Info.
410 Conditionally Visible Text
412 * Conditional Commands:: Specifying text for HTML, Info, or TeX.
413 * Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
414 * Raw Formatter Commands:: Using raw TeX or HTML commands.
415 * set clear value:: Designating which text to format (for
416 all output formats); and how to set a
417 flag to a string that you can insert.
419 `@set', `@clear', and `@value'
421 * ifset ifclear:: Format a region if a flag is set.
422 * value:: Replace a flag with a string.
423 * value Example:: An easy way to update edition information.
425 Macros: Defining New Texinfo Commands
427 * Defining Macros:: Both defining and undefining new commands.
428 * Invoking Macros:: Using a macro, once you've defined it.
430 Format and Print Hardcopy
432 * Use TeX:: Use TeX to format for hardcopy.
433 * Format with tex/texindex:: How to format in a shell.
434 * Format with texi2dvi:: A simpler way to use the shell.
435 * Print with lpr:: How to print.
436 * Within Emacs:: How to format and print from an Emacs shell.
437 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
438 * Compile-Command:: How to print using Emacs's compile command.
439 * Requirements Summary:: TeX formatting requirements summary.
440 * Preparing for TeX:: What you need to do to use TeX.
441 * Overfull hboxes:: What are and what to do with overfull hboxes.
442 * smallbook:: How to print small format books and manuals.
443 * A4 Paper:: How to print on European A4 paper.
444 * Cropmarks and Magnification:: How to print marks to indicate the size
445 of pages and how to print scaled up output.
447 Creating an Info File
449 * makeinfo advantages:: `makeinfo' provides better error checking.
450 * Invoking makeinfo:: How to run `makeinfo' from a shell.
451 * makeinfo options:: Specify fill-column and other options.
452 * Pointer Validation:: How to check that pointers point somewhere.
453 * makeinfo in Emacs:: How to run `makeinfo' from Emacs.
454 * texinfo-format commands:: Two Info formatting commands written
455 in Emacs Lisp are an alternative
457 * Batch Formatting:: How to format for Info in Emacs Batch mode.
458 * Tag and Split Files:: How tagged and split files help Info
461 Installing an Info File
463 * Directory file:: The top level menu for all Info files.
464 * New Info File:: Listing a new info file.
465 * Other Info Directories:: How to specify Info files that are
466 located in other directories.
467 * Installing Dir Entries:: How to specify what menu entry to add
468 to the Info directory.
469 * Invoking install-info:: `install-info' options.
473 * Inserting Permissions:: How to put permissions in your document.
474 * ifinfo Permissions:: Sample `ifinfo' copying permissions.
475 * Titlepage Permissions:: Sample Titlepage copying permissions.
479 * Using Include Files:: How to use the `@include' command.
480 * texinfo-multiple-files-update:: How to create and update nodes and
481 menus when using included files.
482 * Include File Requirements:: What `texinfo-multiple-files-update' expects.
483 * Sample Include File:: A sample outer file with included files
484 within it; and a sample included file.
485 * Include Files Evolution:: How use of the `@include' command
486 has changed over time.
490 * Headings Introduced:: Conventions for using page headings.
491 * Heading Format:: Standard page heading formats.
492 * Heading Choice:: How to specify the type of page heading.
493 * Custom Headings:: How to create your own headings and footings.
497 * makeinfo Preferred:: `makeinfo' finds errors.
498 * Debugging with Info:: How to catch errors with Info formatting.
499 * Debugging with TeX:: How to catch errors with TeX formatting.
500 * Using texinfo-show-structure:: How to use `texinfo-show-structure'.
501 * Using occur:: How to list all lines containing a pattern.
502 * Running Info-Validate:: How to find badly referenced nodes.
504 Finding Badly Referenced Nodes
506 * Using Info-validate:: How to run `Info-validate'.
507 * Unsplit:: How to create an unsplit file.
508 * Tagifying:: How to tagify a file.
509 * Splitting:: How to split a file manually.
514 File: texinfo.info, Node: Copying, Next: Overview, Prev: Top, Up: Top
516 Texinfo Copying Conditions
517 **************************
519 The programs currently being distributed that relate to Texinfo include
520 portions of GNU Emacs, plus other separate programs (including
521 `makeinfo', `info', `texindex', and `texinfo.tex'). These programs are
522 "free"; this means that everyone is free to use them and free to
523 redistribute them on a free basis. The Texinfo-related programs are
524 not in the public domain; they are copyrighted and there are
525 restrictions on their distribution, but these restrictions are designed
526 to permit everything that a good cooperating citizen would want to do.
527 What is not allowed is to try to prevent others from further sharing
528 any version of these programs that they might get from you.
530 Specifically, we want to make sure that you have the right to give
531 away copies of the programs that relate to Texinfo, that you receive
532 source code or else can get it if you want it, that you can change these
533 programs or use pieces of them in new free programs, and that you know
534 you can do these things.
536 To make sure that everyone has such rights, we have to forbid you to
537 deprive anyone else of these rights. For example, if you distribute
538 copies of the Texinfo related programs, you must give the recipients all
539 the rights that you have. You must make sure that they, too, receive or
540 can get the source code. And you must tell them their rights.
542 Also, for our own protection, we must make certain that everyone finds
543 out that there is no warranty for the programs that relate to Texinfo.
544 If these programs are modified by someone else and passed on, we want
545 their recipients to know that what they have is not what we distributed,
546 so that any problems introduced by others will not reflect on our
549 The precise conditions of the licenses for the programs currently
550 being distributed that relate to Texinfo are found in the General Public
551 Licenses that accompany them.
554 File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: Top
559 "Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system
560 that uses a single source file to produce both on-line information and
561 printed output. This means that instead of writing two different
562 documents, one for the on-line help or other on-line information and
563 the other for a typeset manual or other printed work, you need write
564 only one document. When the work is revised, you need revise only one
565 document. (You can read the on-line information, known as an "Info
566 file", with an Info documentation-reading program.)
570 * Using Texinfo:: Create a conventional printed book
572 * Info Files:: What is an Info file?
573 * Printed Books:: Characteristics of a printed book or manual.
574 * Formatting Commands:: @-commands are used for formatting.
575 * Conventions:: General rules for writing a Texinfo file.
576 * Comments:: How to write comments and mark regions that
577 the formatting commands will ignore.
578 * Minimum:: What a Texinfo file must have.
579 * Six Parts:: Usually, a Texinfo file has six parts.
580 * Short Sample:: A short sample Texinfo file.
584 File: texinfo.info, Node: Overview-Footnotes, Up: Overview
586 (1) Note that the first syllable of "Texinfo" is pronounced like
587 "speck", not "hex". This odd pronunciation is derived from, but is not
588 the same as, the pronunciation of TeX. In the word TeX, the `X' is
589 actually the Greek letter "chi" rather than the English letter "ex".
590 Pronounce TeX as if the `X' were the last sound in the name `Bach'; but
591 pronounce Texinfo as if the `x' were a `k'. Spell "Texinfo" with a
592 capital "T" and write the other letters in lower case.
595 File: texinfo.info, Node: Using Texinfo, Next: Info Files, Prev: Overview, Up: Overview
600 Using Texinfo, you can create a printed document with the normal
601 features of a book, including chapters, sections, cross references, and
602 indices. From the same Texinfo source file, you can create a
603 menu-driven, on-line Info file with nodes, menus, cross references, and
604 indices. You can, if you wish, make the chapters and sections of the
605 printed document correspond to the nodes of the on-line information;
606 and you use the same cross references and indices for both the Info
607 file and the printed work. `The XEmacs User's Manual' is a good
608 example of a Texinfo file, as is this manual.
610 To make a printed document, you process a Texinfo source file with the
611 TeX typesetting program. This creates a DVI file that you can typeset
612 and print as a book or report. (Note that the Texinfo language is
613 completely different from TeX's usual language, plain TeX.) If you do
614 not have TeX, but do have `troff' or `nroff', you can use the
615 `texi2roff' program instead.
617 To make an Info file, you process a Texinfo source file with the
618 `makeinfo' utility or Emacs's `texinfo-format-buffer' command; this
619 creates an Info file that you can install on-line.
621 TeX and `texi2roff' work with many types of printers; similarly, Info
622 works with almost every type of computer terminal. This power makes
623 Texinfo a general purpose system, but brings with it a constraint,
624 which is that a Texinfo file may contain only the customary
625 "typewriter" characters (letters, numbers, spaces, and punctuation
626 marks) but no special graphics.
628 A Texinfo file is a plain ASCII file containing text and "@-commands"
629 (words preceded by an `@') that tell the typesetting and formatting
630 programs what to do. You may edit a Texinfo file with any text editor;
631 but it is especially convenient to use GNU Emacs since that editor has
632 a special mode, called Texinfo mode, that provides various
633 Texinfo-related features. (*Note Texinfo Mode::.)
635 Before writing a Texinfo source file, you should become familiar with
636 the Info documentation reading program and learn about nodes, menus,
637 cross references, and the rest. (*note info: (info)Top, for more
640 You can use Texinfo to create both on-line help and printed manuals;
641 moreover, Texinfo is freely redistributable. For these reasons, Texinfo
642 is the format in which documentation for GNU utilities and libraries is
646 File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Using Texinfo, Up: Overview
651 An Info file is a Texinfo file formatted so that the Info documentation
652 reading program can operate on it. (`makeinfo' and
653 `texinfo-format-buffer' are two commands that convert a Texinfo file
656 Info files are divided into pieces called "nodes", each of which
657 contains the discussion of one topic. Each node has a name, and
658 contains both text for the user to read and pointers to other nodes,
659 which are identified by their names. The Info program displays one node
660 at a time, and provides commands with which the user can move to other
663 *note info: (info)Top, for more information about using Info.
665 Each node of an Info file may have any number of child nodes that
666 describe subtopics of the node's topic. The names of child nodes are
667 listed in a "menu" within the parent node; this allows you to use
668 certain Info commands to move to one of the child nodes. Generally, an
669 Info file is organized like a book. If a node is at the logical level
670 of a chapter, its child nodes are at the level of sections; likewise,
671 the child nodes of sections are at the level of subsections.
673 All the children of any one parent are linked together in a
674 bidirectional chain of `Next' and `Previous' pointers. The `Next'
675 pointer provides a link to the next section, and the `Previous' pointer
676 provides a link to the previous section. This means that all the nodes
677 that are at the level of sections within a chapter are linked together.
678 Normally the order in this chain is the same as the order of the
679 children in the parent's menu. Each child node records the parent node
680 name as its `Up' pointer. The last child has no `Next' pointer, and the
681 first child has the parent both as its `Previous' and as its `Up'
682 pointer.(1) (*note Info Files-Footnote-1::)
684 The book-like structuring of an Info file into nodes that correspond
685 to chapters, sections, and the like is a matter of convention, not a
686 requirement. The `Up', `Previous', and `Next' pointers of a node can
687 point to any other nodes, and a menu can contain any other nodes.
688 Thus, the node structure can be any directed graph. But it is usually
689 more comprehensible to follow a structure that corresponds to the
690 structure of chapters and sections in a printed book or report.
692 In addition to menus and to `Next', `Previous', and `Up' pointers,
693 Info provides pointers of another kind, called references, that can be
694 sprinkled throughout the text. This is usually the best way to
695 represent links that do not fit a hierarchical structure.
697 Usually, you will design a document so that its nodes match the
698 structure of chapters and sections in the printed output. But
699 occasionally there are times when this is not right for the material
700 being discussed. Therefore, Texinfo uses separate commands to specify
701 the node structure for the Info file and the section structure for the
704 Generally, you enter an Info file through a node that by convention is
705 named `Top'. This node normally contains just a brief summary of the
706 file's purpose, and a large menu through which the rest of the file is
707 reached. From this node, you can either traverse the file
708 systematically by going from node to node, or you can go to a specific
709 node listed in the main menu, or you can search the index menus and then
710 go directly to the node that has the information you want.
711 Alternatively, with the standalone Info program, you can specify
712 specific menu items on the command line (*note Top: (info)Top.).
714 If you want to read through an Info file in sequence, as if it were a
715 printed manual, you can hit <SPC> repeatedly, or you get the whole file
716 with the advanced Info command `g *'. (*note Advanced Info commands:
719 The `dir' file in the `info' directory serves as the departure point
720 for the whole Info system. From it, you can reach the `Top' nodes of
721 each of the documents in a complete Info system.
724 File: texinfo.info, Node: Info Files-Footnotes, Up: Info Files
726 (1) In some documents, the first child has no `Previous' pointer.
727 Occasionally, the last child has the node name of the next following
728 higher level node as its `Next' pointer.
731 File: texinfo.info, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview
736 A Texinfo file can be formatted and typeset as a printed book or manual.
737 To do this, you need TeX, a powerful, sophisticated typesetting program
738 written by Donald Knuth.(1) (*note Printed Books-Footnote-1::)
740 A Texinfo-based book is similar to any other typeset, printed work: it
741 can have a title page, copyright page, table of contents, and preface,
742 as well as chapters, numbered or unnumbered sections and subsections,
743 page headers, cross references, footnotes, and indices.
745 You can use Texinfo to write a book without ever having the intention
746 of converting it into on-line information. You can use Texinfo for
747 writing a printed novel, and even to write a printed memo, although
748 this latter application is not recommended since electronic mail is so
751 TeX is a general purpose typesetting program. Texinfo provides a
752 file called `texinfo.tex' that contains information (definitions or
753 "macros") that TeX uses when it typesets a Texinfo file.
754 (`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX
755 commands, which TeX can then process to create the typeset document.)
756 `texinfo.tex' contains the specifications for printing a document.
758 Most often, documents are printed on 8.5 inch by 11 inch pages (216mm
759 by 280mm; this is the default size), but you can also print for 7 inch
760 by 9.25 inch pages (178mm by 235mm; the `@smallbook' size) or on
761 European A4 size paper (`@afourpaper'). (*Note Printing "Small" Books:
762 smallbook. Also, see *Note Printing on A4 Paper: A4 Paper.)
764 By changing the parameters in `texinfo.tex', you can change the size
765 of the printed document. In addition, you can change the style in
766 which the printed document is formatted; for example, you can change the
767 sizes and fonts used, the amount of indentation for each paragraph, the
768 degree to which words are hyphenated, and the like. By changing the
769 specifications, you can make a book look dignified, old and serious, or
770 light-hearted, young and cheery.
772 TeX is freely distributable. It is written in a superset of Pascal
773 called WEB and can be compiled either in Pascal or (by using a
774 conversion program that comes with the TeX distribution) in C. (*Note
775 TeX Mode: (xemacs)TeX Mode, for information about TeX.)
777 TeX is very powerful and has a great many features. Because a
778 Texinfo file must be able to present information both on a
779 character-only terminal in Info form and in a typeset book, the
780 formatting commands that Texinfo supports are necessarily limited.
782 *Note How to Obtain TeX: Obtaining TeX.
785 File: texinfo.info, Node: Printed Books-Footnotes, Up: Printed Books
787 (1) You can also use the `texi2roff' program if you do not have TeX;
788 since Texinfo is designed for use with TeX, `texi2roff' is not
789 described here. `texi2roff' is not part of the standard GNU
793 File: texinfo.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview
798 In a Texinfo file, the commands that tell TeX how to typeset the
799 printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
800 create an Info file are preceded by `@'; they are called "@-commands".
801 For example, `@node' is the command to indicate a node and `@chapter'
802 is the command to indicate the start of a chapter.
804 *Please note:* All the @-commands, with the exception of the
805 `@TeX{}' command, must be written entirely in lower case.
807 The Texinfo @-commands are a strictly limited set of constructs. The
808 strict limits make it possible for Texinfo files to be understood both
809 by TeX and by the code that converts them into Info files. You can
810 display Info files on any terminal that displays alphabetic and numeric
811 characters. Similarly, you can print the output generated by TeX on a
812 wide variety of printers.
814 Depending on what they do or what arguments(1) (*note Formatting
815 Commands-Footnote-1::) they take, you need to write @-commands on lines
816 of their own or as part of sentences:
818 * Write a command such as `@noindent' at the beginning of a line as
819 the only text on the line. (`@noindent' prevents the beginning of
820 the next line from being indented as the beginning of a paragraph.)
822 * Write a command such as `@chapter' at the beginning of a line
823 followed by the command's arguments, in this case the chapter
824 title, on the rest of the line. (`@chapter' creates chapter
827 * Write a command such as `@dots{}' wherever you wish but usually
828 within a sentence. (`@dots{}' creates dots ...)
830 * Write a command such as `@code{SAMPLE-CODE}' wherever you wish
831 (but usually within a sentence) with its argument, SAMPLE-CODE in
832 this example, between the braces. (`@code' marks text as being
835 * Write a command such as `@example' at the beginning of a line of
836 its own; write the body-text on following lines; and write the
837 matching `@end' command, `@end example' in this case, at the
838 beginning of a line of its own after the body-text. (`@example'
839 ... `@end example' indents and typesets body-text as an example.)
841 As a general rule, a command requires braces if it mingles among other
842 text; but it does not need braces if it starts a line of its own. The
843 non-alphabetic commands, such as `@:', are exceptions to the rule; they
846 As you gain experience with Texinfo, you will rapidly learn how to
847 write the different commands: the different ways to write commands make
848 it easier to write and read Texinfo files than if all commands followed
849 exactly the same syntax. (For details about @-command syntax, see
850 *Note @-Command Syntax: Command Syntax.)
853 File: texinfo.info, Node: Formatting Commands-Footnotes, Up: Formatting Commands
855 (1) The word "argument" comes from the way it is used in mathematics
856 and does not refer to a disputation between two people; it refers to the
857 information presented to the command. According to the `Oxford English
858 Dictionary', the word derives from the Latin for "to make clear,
859 prove"; thus it came to mean `the evidence offered as proof', which is
860 to say, `the information offered', which led to its mathematical
861 meaning. In its other thread of derivation, the word came to mean `to
862 assert in a manner against which others may make counter assertions',
863 which led to the meaning of `argument' as a disputation.
866 File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview
868 General Syntactic Conventions
869 =============================
871 All printable ASCII characters except `@', `{' and `}' can appear in a
872 Texinfo file and stand for themselves. `@' is the escape character
873 which introduces commands. `{' and `}' should be used only to surround
874 arguments to certain commands. To put one of these special characters
875 into the document, put an `@' character in front of it, like this:
876 `@@', `@{', and `@}'.
878 It is customary in TeX to use doubled single-quote characters to
879 begin and end quotations: ` ` and ' ' (but without a space between the
880 two single-quote characters). This convention should be followed in
881 Texinfo files. TeX converts doubled single-quote characters to left-
882 and right-hand doubled quotation marks and Info converts doubled
883 single-quote characters to ASCII double-quotes: ` ` and ' ' to " .
885 Use three hyphens in a row, `---', for a dash--like this. In TeX, a
886 single or double hyphen produces a printed dash that is shorter than
887 the usual typeset dash. Info reduces three hyphens to two for display
890 To prevent a paragraph from being indented in the printed manual, put
891 the command `@noindent' on a line by itself before the paragraph.
893 If you mark off a region of the Texinfo file with the `@iftex' and
894 `@end iftex' commands, that region will appear only in the printed
895 copy; in that region, you can use certain commands borrowed from plain
896 TeX that you cannot use in Info. Likewise, if you mark off a region
897 with the `@ifinfo' and `@end ifinfo' commands, that region will appear
898 only in the Info file; in that region, you can use Info commands that
899 you cannot use in TeX. Similarly for `@ifhtml ... @end ifhtml',
900 `@ifnothtml ... @end ifnothtml', `@ifnotinfo ... @end ifnotinfo',
901 `@ifnottex ... @end ifnottex', *Note Conditionals::.
903 *Caution:* Do not use tabs in a Texinfo file! TeX uses
904 variable-width fonts, which means that it cannot predefine a tab
905 to work in all circumstances. Consequently, TeX treats tabs like
906 single spaces, and that is not what they look like. Furthermore,
907 `makeinfo' does nothing special with tabs, and thus a tab character
908 in your input file may appear differently in the output.
910 To avoid this problem, Texinfo mode causes GNU Emacs to insert
911 multiple spaces when you press the <TAB> key.
913 Also, you can run `untabify' in Emacs to convert tabs in a region
919 File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview
924 You can write comments in a Texinfo file that will not appear in either
925 the Info file or the printed manual by using the `@comment' command
926 (which may be abbreviated to `@c'). Such comments are for the person
927 who reads the Texinfo file. All the text on a line that follows either
928 `@comment' or `@c' is a comment; the rest of the line does not appear
929 in either the Info file or the printed manual. (Often, you can write
930 the `@comment' or `@c' in the middle of a line, and only the text that
931 follows after the `@comment' or `@c' command does not appear; but some
932 commands, such as `@settitle' and `@setfilename', work on a whole line.
933 You cannot use `@comment' or `@c' in a line beginning with such a
936 You can write long stretches of text that will not appear in either
937 the Info file or the printed manual by using the `@ignore' and `@end
938 ignore' commands. Write each of these commands on a line of its own,
939 starting each command at the beginning of the line. Text between these
940 two commands does not appear in the processed output. You can use
941 `@ignore' and `@end ignore' for writing comments. Often, `@ignore' and
942 `@end ignore' is used to enclose a part of the copying permissions that
943 applies to the Texinfo source file of a document, but not to the Info
944 or printed version of the document.
947 File: texinfo.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview
949 What a Texinfo File Must Have
950 =============================
952 By convention, the names of Texinfo files end with one of the
953 extensions `.texinfo', `.texi', or `.tex'. The longer extension is
954 preferred since it describes more clearly to a human reader the nature
955 of the file. The shorter extensions are for operating systems that
956 cannot handle long file names.
958 In order to be made into a printed manual and an Info file, a Texinfo
959 file *must* begin with lines like this:
962 @setfilename INFO-FILE-NAME
963 @settitle NAME-OF-MANUAL
965 The contents of the file follow this beginning, and then you *must* end
966 a Texinfo file with a line like this:
970 The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
971 which tells TeX how to translate the Texinfo @-commands into TeX
972 typesetting commands. (Note the use of the backslash, `\'; this is
973 correct for TeX.) The `@setfilename' line provides a name for the Info
974 file and tells TeX to open auxiliary files. The `@settitle' line
975 specifies a title for the page headers (or footers) of the printed
978 The `@bye' line at the end of the file on a line of its own tells the
979 formatters that the file is ended and to stop formatting.
981 Usually, you will not use quite such a spare format, but will include
982 mode setting and start-of-header and end-of-header lines at the
983 beginning of a Texinfo file, like this:
985 \input texinfo @c -*-texinfo-*-
986 @c %**start of header
987 @setfilename INFO-FILE-NAME
988 @settitle NAME-OF-MANUAL
991 In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
992 mode when you edit the file.
994 The `@c' lines which surround the `@setfilename' and `@settitle'
995 lines are optional, but you need them in order to run TeX or Info on
996 just part of the file. (*Note Start of Header::, for more information.)
998 Furthermore, you will usually provide a Texinfo file with a title
999 page, indices, and the like. But the minimum, which can be useful for
1000 short documents, is just the three lines at the beginning and the one
1004 File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview
1006 Six Parts of a Texinfo File
1007 ===========================
1009 Generally, a Texinfo file contains more than the minimal beginning and
1010 end--it usually contains six parts:
1013 The "Header" names the file, tells TeX which definitions' file to
1014 use, and performs other "housekeeping" tasks.
1016 2. Summary Description and Copyright
1017 The "Summary Description and Copyright" segment describes the
1018 document and contains the copyright notice and copying permissions
1019 for the Info file. The segment must be enclosed between `@ifinfo'
1020 and `@end ifinfo' commands so that the formatters place it only in
1023 3. Title and Copyright
1024 The "Title and Copyright" segment contains the title and copyright
1025 pages and copying permissions for the printed manual. The segment
1026 must be enclosed between `@titlepage' and `@end titlepage'
1027 commands. The title and copyright page appear only in the printed
1030 4. `Top' Node and Master Menu
1031 The "Master Menu" contains a complete menu of all the nodes in the
1032 whole Info file. It appears only in the Info file, in the `Top'
1036 The "Body" of the document may be structured like a traditional
1037 book or encyclopedia or it may be free form.
1040 The "End" contains commands for printing indices and generating
1041 the table of contents, and the `@bye' command on a line of its own.
1044 File: texinfo.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview
1046 A Short Sample Texinfo File
1047 ===========================
1049 Here is a complete but very short Texinfo file, in six parts. The first
1050 three parts of the file, from `\input texinfo' through to `@end
1051 titlepage', look more intimidating than they are. Most of the material
1052 is standard boilerplate; when you write a manual, simply insert the
1053 names for your own manual in this segment. (*Note Beginning a File::.)
1055 In the following, the sample text is _indented_; comments on it are
1056 not. The complete file, without any comments, is shown in *Note Sample
1062 The header does not appear in either the Info file or the printed
1063 output. It sets various parameters, including the name of the Info
1064 file and the title used in the header.
1066 \input texinfo @c -*-texinfo-*-
1067 @c %**start of header
1068 @setfilename sample.info
1069 @settitle Sample Document
1072 @setchapternewpage odd
1074 Part 2: Summary Description and Copyright
1075 -----------------------------------------
1077 The summary description and copyright segment does not appear in the
1081 This is a short example of a complete Texinfo file.
1083 Copyright @copyright{} 1990 Free Software Foundation, Inc.
1086 Part 3: Titlepage and Copyright
1087 -------------------------------
1089 The titlepage segment does not appear in the Info file.
1093 @comment The title is printed in a large font.
1094 @center @titlefont{Sample Title}
1096 @c The following two commands start the copyright page.
1098 @vskip 0pt plus 1filll
1099 Copyright @copyright{} 1990 Free Software Foundation, Inc.
1102 Part 4: `Top' Node and Master Menu
1103 ----------------------------------
1105 The `Top' node contains the master menu for the Info file. Since a
1106 printed manual uses a table of contents rather than a menu, the master
1107 menu appears only in the Info file.
1109 @node Top, First Chapter, , (dir)
1110 @comment node-name, next, previous, up
1113 * First Chapter:: The first chapter is the
1114 only chapter in this sample.
1115 * Concept Index:: This index has two entries.
1118 Part 5: The Body of the Document
1119 ---------------------------------
1121 The body segment contains all the text of the document, but not the
1122 indices or table of contents. This example illustrates a node and a
1123 chapter containing an enumerated list.
1125 @node First Chapter, Concept Index, Top, Top
1126 @comment node-name, next, previous, up
1127 @chapter First Chapter
1128 @cindex Sample index entry
1130 This is the contents of the first chapter.
1131 @cindex Another sample index entry
1133 Here is a numbered list.
1137 This is the first item.
1140 This is the second item.
1143 The @code{makeinfo} and @code{texinfo-format-buffer}
1144 commands transform a Texinfo file such as this into
1145 an Info file; and @TeX{} typesets it for a printed
1148 Part 6: The End of the Document
1149 -------------------------------
1151 The end segment contains commands both for generating an index in a node
1152 and unnumbered chapter of its own and for generating the table of
1153 contents; and it contains the `@bye' command that marks the end of the
1156 @node Concept Index, , First Chapter, Top
1157 @comment node-name, next, previous, up
1158 @unnumbered Concept Index
1168 Here is what the contents of the first chapter of the sample look like:
1171 This is the contents of the first chapter.
1173 Here is a numbered list.
1175 1. This is the first item.
1177 2. This is the second item.
1179 The `makeinfo' and `texinfo-format-buffer' commands transform a
1180 Texinfo file such as this into an Info file; and TeX typesets it
1181 for a printed manual.
1184 File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
1189 Richard M. Stallman wrote Edition 1.0 of this manual.
1190 Robert J. Chassell revised and extended it, starting with Edition 1.1.
1191 Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
1192 starting with Edition 2.22.
1194 Our thanks go out to all who helped improve this work, particularly to
1195 Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
1196 reported mistakes and obscurities; our special thanks go to Melissa
1197 Weisshaus for her frequent and often tedious reviews of nearly similar
1198 editions. Our mistakes are our own.
1200 Please send suggestions and corrections to:
1205 Please include the manual's edition number and update date in your
1209 File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
1214 You may edit a Texinfo file with any text editor you choose. A Texinfo
1215 file is no different from any other ASCII file. However, GNU Emacs
1216 comes with a special mode, called Texinfo mode, that provides Emacs
1217 commands and tools to help ease your work.
1219 This chapter describes features of GNU Emacs' Texinfo mode but not any
1220 features of the Texinfo formatting language. If you are reading this
1221 manual straight through from the beginning, you may want to skim through
1222 this chapter briefly and come back to it after reading succeeding
1223 chapters which describe the Texinfo formatting language in detail.
1227 * Texinfo Mode Overview:: How Texinfo mode can help you.
1228 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1229 purpose editing features.
1230 * Inserting:: How to insert frequently used @-commands.
1231 * Showing the Structure:: How to show the structure of a file.
1232 * Updating Nodes and Menus:: How to update or create new nodes and menus.
1233 * Info Formatting:: How to format for Info.
1234 * Printing:: How to format and print part or all of a file.
1235 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1238 File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
1240 Texinfo Mode Overview
1241 =====================
1243 Texinfo mode provides special features for working with Texinfo files:
1245 * Insert frequently used @-commands.
1247 * Automatically create `@node' lines.
1249 * Show the structure of a Texinfo source file.
1251 * Automatically create or update the `Next', `Previous', and `Up'
1254 * Automatically create or update menus.
1256 * Automatically create a master menu.
1258 * Format a part or all of a file for Info.
1260 * Typeset and print part or all of a file.
1262 Perhaps the two most helpful features are those for inserting
1263 frequently used @-commands and for creating node pointers and menus.
1266 File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
1268 The Usual GNU Emacs Editing Commands
1269 ====================================
1271 In most cases, the usual Text mode commands work the same in Texinfo
1272 mode as they do in Text mode. Texinfo mode adds new editing commands
1273 and tools to GNU Emacs' general purpose editing features. The major
1274 difference concerns filling. In Texinfo mode, the paragraph separation
1275 variable and syntax table are redefined so that Texinfo commands that
1276 should be on lines of their own are not inadvertently included in
1277 paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
1278 paragraph but not mix an indexing command on a line adjacent to it into
1281 In addition, Texinfo mode sets the `page-delimiter' variable to the
1282 value of `texinfo-chapter-level-regexp'; by default, this is a regular
1283 expression matching the commands for chapters and their equivalents,
1284 such as appendices. With this value for the page delimiter, you can
1285 jump from chapter title to chapter title with the `C-x ]'
1286 (`forward-page') and `C-x [' (`backward-page') commands and narrow to a
1287 chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
1288 (xemacs)Pages, for details about the page commands.)
1290 You may name a Texinfo file however you wish, but the convention is to
1291 end a Texinfo file name with one of the three extensions `.texinfo',
1292 `.texi', or `.tex'. A longer extension is preferred, since it is
1293 explicit, but a shorter extension may be necessary for operating
1294 systems that limit the length of file names. GNU Emacs automatically
1295 enters Texinfo mode when you visit a file with a `.texinfo' or `.texi'
1296 extension. Also, Emacs switches to Texinfo mode when you visit a file
1297 that has `-*-texinfo-*-' in its first line. If ever you are in another
1298 mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
1300 Like all other Emacs features, you can customize or enhance Texinfo
1301 mode as you wish. In particular, the keybindings are very easy to
1302 change. The keybindings described here are the default or standard
1306 File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
1308 Inserting Frequently Used Commands
1309 ==================================
1311 Texinfo mode provides commands to insert various frequently used
1312 @-commands into the buffer. You can use these commands to save
1315 The insert commands are invoked by typing `C-c' twice and then the
1316 first letter of the @-command:
1319 `M-x texinfo-insert-@code'
1320 Insert `@code{}' and put the cursor between the braces.
1323 `M-x texinfo-insert-@dfn'
1324 Insert `@dfn{}' and put the cursor between the braces.
1327 `M-x texinfo-insert-@end'
1328 Insert `@end' and attempt to insert the correct following word,
1329 such as `example' or `table'. (This command does not handle
1330 nested lists correctly, but inserts the word appropriate to the
1331 immediately preceding list.)
1334 `M-x texinfo-insert-@item'
1335 Insert `@item' and put the cursor at the beginning of the next
1339 `M-x texinfo-insert-@kbd'
1340 Insert `@kbd{}' and put the cursor between the braces.
1343 `M-x texinfo-insert-@node'
1344 Insert `@node' and a comment line listing the sequence for the
1345 `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
1348 `M-x texinfo-insert-@noindent'
1349 Insert `@noindent' and put the cursor at the beginning of the next
1353 `M-x texinfo-insert-@samp'
1354 Insert `@samp{}' and put the cursor between the braces.
1357 `M-x texinfo-insert-@table'
1358 Insert `@table' followed by a <SPC> and leave the cursor after the
1362 `M-x texinfo-insert-@var'
1363 Insert `@var{}' and put the cursor between the braces.
1366 `M-x texinfo-insert-@example'
1367 Insert `@example' and put the cursor at the beginning of the next
1371 `M-x texinfo-insert-braces'
1372 Insert `{}' and put the cursor between the braces.
1377 Move from between a pair of braces forward past the closing brace.
1378 Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
1379 however, more mnemonic; hence the two keybindings. (Also, you can
1380 move out from between braces by typing `C-f'.)
1382 To put a command such as `@code{...}' around an _existing_ word,
1383 position the cursor in front of the word and type `C-u 1 C-c C-c c'.
1384 This makes it easy to edit existing plain text. The value of the
1385 prefix argument tells Emacs how many words following point to include
1386 between braces--`1' for one word, `2' for two words, and so on. Use a
1387 negative argument to enclose the previous word or words. If you do not
1388 specify a prefix argument, Emacs inserts the @-command string and
1389 positions the cursor between the braces. This feature works only for
1390 those @-commands that operate on a word or words within one line, such
1391 as `@kbd' and `@var'.
1393 This set of insert commands was created after analyzing the frequency
1394 with which different @-commands are used in the `GNU Emacs Manual' and
1395 the `GDB Manual'. If you wish to add your own insert commands, you can
1396 bind a keyboard macro to a key, use abbreviations, or extend the code
1399 `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
1400 that works differently from the other insert commands. It inserts a
1401 node's section or chapter title in the space for the description in a
1402 menu entry line. (A menu entry has three parts, the entry name, the
1403 node name, and the description. Only the node name is required, but a
1404 description helps explain what the node is about. *Note The Parts of a
1407 To use `texinfo-start-menu-description', position point in a menu
1408 entry line and type `C-c C-c C-d'. The command looks for and copies
1409 the title that goes with the node name, and inserts the title as a
1410 description; it positions point at beginning of the inserted text so you
1411 can edit it. The function does not insert the title if the menu entry
1412 line already contains a description.
1414 This command is only an aid to writing descriptions; it does not do
1415 the whole job. You must edit the inserted text since a title tends to
1416 use the same words as a node name but a useful description uses
1420 File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
1422 Showing the Section Structure of a File
1423 =======================================
1425 You can show the section structure of a Texinfo file by using the `C-c
1426 C-s' command (`texinfo-show-structure'). This command shows the
1427 section structure of a Texinfo file by listing the lines that begin
1428 with the @-commands for `@chapter', `@section', and the like. It
1429 constructs what amounts to a table of contents. These lines are
1430 displayed in another buffer called the `*Occur*' buffer. In that
1431 buffer, you can position the cursor over one of the lines and use the
1432 `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
1433 corresponding spot in the Texinfo file.
1436 `M-x texinfo-show-structure'
1437 Show the `@chapter', `@section', and such lines of a Texinfo file.
1440 `M-x occur-mode-goto-occurrence'
1441 Go to the line in the Texinfo file corresponding to the line under
1442 the cursor in the `*Occur*' buffer.
1444 If you call `texinfo-show-structure' with a prefix argument by typing
1445 `C-u C-c C-s', it will list not only those lines with the @-commands
1446 for `@chapter', `@section', and the like, but also the `@node' lines.
1447 (This is how the `texinfo-show-structure' command worked without an
1448 argument in the first version of Texinfo. It was changed because
1449 `@node' lines clutter up the `*Occur*' buffer and are usually not
1450 needed.) You can use `texinfo-show-structure' with a prefix argument
1451 to check whether the `Next', `Previous', and `Up' pointers of an
1452 `@node' line are correct.
1454 Often, when you are working on a manual, you will be interested only
1455 in the structure of the current chapter. In this case, you can mark
1456 off the region of the buffer that you are interested in by using the
1457 `C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
1458 will work on only that region. To see the whole buffer again, use
1459 `C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more
1460 information about the narrowing commands.)
1462 In addition to providing the `texinfo-show-structure' command,
1463 Texinfo mode sets the value of the page delimiter variable to match the
1464 chapter-level @-commands. This enables you to use the `C-x ]'
1465 (`forward-page') and `C-x [' (`backward-page') commands to move forward
1466 and backward by chapter, and to use the `C-x p' (`narrow-to-page')
1467 command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more
1468 information about the page commands.
1471 File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
1473 Updating Nodes and Menus
1474 ========================
1476 Texinfo mode provides commands for automatically creating or updating
1477 menus and node pointers. The commands are called "update" commands
1478 because their most frequent use is for updating a Texinfo file after
1479 you have worked on it; but you can use them to insert the `Next',
1480 `Previous', and `Up' pointers into an `@node' line that has none and to
1481 create menus in a file that has none.
1483 If you do not use the updating commands, you need to write menus and
1484 node pointers by hand, which is a tedious task.
1488 * Updating Commands:: Five major updating commands.
1489 * Updating Requirements:: How to structure a Texinfo file for
1490 using the updating command.
1491 * Other Updating Commands:: How to indent descriptions, insert
1492 missing nodes lines, and update
1496 File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
1498 The Updating Commands
1499 ---------------------
1501 You can use the updating commands
1503 * to insert or update the `Next', `Previous', and `Up' pointers of a
1506 * to insert or update the menu for a section, and
1508 * to create a master menu for a Texinfo source file.
1510 You can also use the commands to update all the nodes and menus in a
1511 region or in a whole Texinfo file.
1513 The updating commands work only with conventional Texinfo files, which
1514 are structured hierarchically like books. In such files, a structuring
1515 command line must follow closely after each `@node' line, except for
1516 the `Top' `@node' line. (A "structuring command line" is a line
1517 beginning with `@chapter', `@section', or other similar command.)
1519 You can write the structuring command line on the line that follows
1520 immediately after an `@node' line or else on the line that follows
1521 after a single `@comment' line or a single `@ifinfo' line. You cannot
1522 interpose more than one line between the `@node' line and the
1523 structuring command line; and you may interpose only an `@comment' line
1524 or an `@ifinfo' line.
1526 Commands which work on a whole buffer require that the `Top' node be
1527 followed by a node with an `@chapter' or equivalent-level command.
1528 Note that the menu updating commands will not create a main or master
1529 menu for a Texinfo file that has only `@chapter'-level nodes! The menu
1530 updating commands only create menus _within_ nodes for lower level
1531 nodes. To create a menu of chapters, you must provide a `Top' node.
1533 The menu updating commands remove menu entries that refer to other
1534 Info files since they do not refer to nodes within the current buffer.
1535 This is a deficiency. Rather than use menu entries, you can use cross
1536 references to refer to other Info files. None of the updating commands
1537 affect cross references.
1539 Texinfo mode has five updating commands that are used most often: two
1540 are for updating the node pointers or menu of a single node (or a
1541 region); two are for updating every node pointer and menu in a file;
1542 and one, the `texinfo-master-menu' command, is for creating a master
1543 menu for a complete file, and optionally, for updating every node and
1544 menu in the whole Texinfo file.
1546 The `texinfo-master-menu' command is the primary command:
1549 `M-x texinfo-master-menu'
1550 Create or update a master menu that includes all the other menus
1551 (incorporating the descriptions from pre-existing menus, if any).
1553 With an argument (prefix argument, `C-u,' if interactive), first
1554 create or update all the nodes and all the regular menus in the
1555 buffer before constructing the master menu. (*Note The Top Node
1556 and Master Menu: The Top Node, for more about a master menu.)
1558 For `texinfo-master-menu' to work, the Texinfo file must have a
1559 `Top' node and at least one subsequent node.
1561 After extensively editing a Texinfo file, you can type the
1564 C-u M-x texinfo-master-menu
1568 This updates all the nodes and menus completely and all at once.
1570 The other major updating commands do smaller jobs and are designed for
1571 the person who updates nodes and menus as he or she writes a Texinfo
1577 `M-x texinfo-update-node'
1578 Insert the `Next', `Previous', and `Up' pointers for the node that
1579 point is within (i.e., for the `@node' line preceding point). If
1580 the `@node' line has pre-existing `Next', `Previous', or `Up'
1581 pointers in it, the old pointers are removed and new ones inserted.
1582 With an argument (prefix argument, `C-u', if interactive), this
1583 command updates all `@node' lines in the region (which is the text
1584 between point and mark).
1587 `M-x texinfo-make-menu'
1588 Create or update the menu in the node that point is within. With
1589 an argument (`C-u' as prefix argument, if interactive), the
1590 command makes or updates menus for the nodes which are either
1591 within or a part of the region.
1593 Whenever `texinfo-make-menu' updates an existing menu, the
1594 descriptions from that menu are incorporated into the new menu.
1595 This is done by copying descriptions from the existing menu to the
1596 entries in the new menu that have the same node names. If the
1597 node names are different, the descriptions are not copied to the
1601 `M-x texinfo-every-node-update'
1602 Insert or update the `Next', `Previous', and `Up' pointers for
1603 every node in the buffer.
1606 `M-x texinfo-all-menus-update'
1607 Create or update all the menus in the buffer. With an argument
1608 (`C-u' as prefix argument, if interactive), first insert or update
1609 all the node pointers before working on the menus.
1611 If a master menu exists, the `texinfo-all-menus-update' command
1612 updates it; but the command does not create a new master menu if
1613 none already exists. (Use the `texinfo-master-menu' command for
1616 When working on a document that does not merit a master menu, you
1617 can type the following:
1621 C-u M-x texinfo-all-menus-update
1623 This updates all the nodes and menus.
1625 The `texinfo-column-for-description' variable specifies the column to
1626 which menu descriptions are indented. By default, the value is 32
1627 although it is often useful to reduce it to as low as 24. You can set
1628 the variable with the `M-x edit-options' command (*note Editing
1629 Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
1630 command (*note Examining and Setting Variables: (xemacs)Examining.).
1632 Also, the `texinfo-indent-menu-description' command may be used to
1633 indent existing menu descriptions to a specified column. Finally, if
1634 you wish, you can use the `texinfo-insert-node-lines' command to insert
1635 missing `@node' lines into a file. (*Note Other Updating Commands::,
1636 for more information.)
1639 File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
1641 Updating Requirements
1642 ---------------------
1644 To use the updating commands, you must organize the Texinfo file
1645 hierarchically with chapters, sections, subsections, and the like.
1646 When you construct the hierarchy of the manual, do not `jump down' more
1647 than one level at a time: you can follow the `Top' node with a chapter,
1648 but not with a section; you can follow a chapter with a section, but
1649 not with a subsection. However, you may `jump up' any number of levels
1650 at one time--for example, from a subsection to a chapter.
1652 Each `@node' line, with the exception of the line for the `Top' node,
1653 must be followed by a line with a structuring command such as
1654 `@chapter', `@section', or `@unnumberedsubsec'.
1656 Each `@node' line/structuring-command line combination must look
1659 @node Comments, Minimum, Conventions, Overview
1660 @comment node-name, next, previous, up
1663 or like this (without the `@comment' line):
1665 @node Comments, Minimum, Conventions, Overview
1668 In this example, `Comments' is the name of both the node and the
1669 section. The next node is called `Minimum' and the previous node is
1670 called `Conventions'. The `Comments' section is within the `Overview'
1671 node, which is specified by the `Up' pointer. (Instead of an
1672 `@comment' line, you can write an `@ifinfo' line.)
1674 If a file has a `Top' node, it must be called `top' or `Top' and be
1675 the first node in the file.
1677 The menu updating commands create a menu of sections within a chapter,
1678 a menu of subsections within a section, and so on. This means that you
1679 must have a `Top' node if you want a menu of chapters.
1681 Incidentally, the `makeinfo' command will create an Info file for a
1682 hierarchically organized Texinfo file that lacks `Next', `Previous' and
1683 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
1684 formatted with `makeinfo', you have no need for the `update node'
1685 commands. (*Note Creating an Info File: Create an Info File, for more
1686 information about `makeinfo'.) However, both `makeinfo' and the
1687 `texinfo-format-...' commands require that you insert menus in the file.
1690 File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
1692 Other Updating Commands
1693 -----------------------
1695 In addition to the five major updating commands, Texinfo mode possesses
1696 several less frequently used updating commands:
1698 `M-x texinfo-insert-node-lines'
1699 Insert `@node' lines before the `@chapter', `@section', and other
1700 sectioning commands wherever they are missing throughout a region
1703 With an argument (`C-u' as prefix argument, if interactive), the
1704 `texinfo-insert-node-lines' command not only inserts `@node' lines
1705 but also inserts the chapter or section titles as the names of the
1706 corresponding nodes. In addition, it inserts the titles as node
1707 names in pre-existing `@node' lines that lack names. Since node
1708 names should be more concise than section or chapter titles, you
1709 must manually edit node names so inserted.
1711 For example, the following marks a whole buffer as a region and
1712 inserts `@node' lines and titles throughout:
1714 C-x h C-u M-x texinfo-insert-node-lines
1716 (Note that this command inserts titles as node names in `@node'
1717 lines; the `texinfo-start-menu-description' command (*note
1718 Inserting Frequently Used Commands: Inserting.) inserts titles as
1719 descriptions in menu entries, a different action. However, in both
1720 cases, you need to edit the inserted text.)
1722 `M-x texinfo-multiple-files-update'
1723 Update nodes and menus in a document built from several separate
1724 files. With `C-u' as a prefix argument, create and insert a
1725 master menu in the outer file. With a numeric prefix argument,
1726 such as `C-u 2', first update all the menus and all the `Next',
1727 `Previous', and `Up' pointers of all the included files before
1728 creating and inserting a master menu in the outer file. The
1729 `texinfo-multiple-files-update' command is described in the
1730 appendix on `@include' files. *Note
1731 texinfo-multiple-files-update::.
1733 `M-x texinfo-indent-menu-description'
1734 Indent every description in the menu following point to the
1735 specified column. You can use this command to give yourself more
1736 space for descriptions. With an argument (`C-u' as prefix
1737 argument, if interactive), the `texinfo-indent-menu-description'
1738 command indents every description in every menu in the region.
1739 However, this command does not indent the second and subsequent
1740 lines of a multi-line description.
1742 `M-x texinfo-sequential-node-update'
1743 Insert the names of the nodes immediately following and preceding
1744 the current node as the `Next' or `Previous' pointers regardless
1745 of those nodes' hierarchical level. This means that the `Next'
1746 node of a subsection may well be the next chapter. Sequentially
1747 ordered nodes are useful for novels and other documents that you
1748 read through sequentially. (However, in Info, the `g *' command
1749 lets you look through the file sequentially, so sequentially
1750 ordered nodes are not strictly necessary.) With an argument
1751 (prefix argument, if interactive), the
1752 `texinfo-sequential-node-update' command sequentially updates all
1753 the nodes in the region.
1756 File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
1761 Texinfo mode provides several commands for formatting part or all of a
1762 Texinfo file for Info. Often, when you are writing a document, you
1763 want to format only part of a file--that is, a region.
1765 You can use either the `texinfo-format-region' or the
1766 `makeinfo-region' command to format a region:
1769 `M-x texinfo-format-region'
1771 `M-x makeinfo-region'
1772 Format the current region for Info.
1774 You can use either the `texinfo-format-buffer' or the
1775 `makeinfo-buffer' command to format a whole buffer:
1778 `M-x texinfo-format-buffer'
1780 `M-x makeinfo-buffer'
1781 Format the current buffer for Info.
1783 For example, after writing a Texinfo file, you can type the following:
1787 C-u M-x texinfo-master-menu
1789 This updates all the nodes and menus. Then type the following to create
1796 For TeX or the Info formatting commands to work, the file _must_
1797 include a line that has `@setfilename' in its header.
1799 *Note Create an Info File::, for details about Info formatting.
1802 File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
1804 Formatting and Printing
1805 =======================
1807 Typesetting and printing a Texinfo file is a multi-step process in which
1808 you first create a file for printing (called a DVI file), and then
1809 print the file. Optionally, you may also create indices. To do this,
1810 you must run the `texindex' command after first running the `tex'
1811 typesetting command; and then you must run the `tex' command again. Or
1812 else run the `texi2dvi' command which automatically creates indices as
1813 needed (*note Format with texi2dvi::).
1815 Often, when you are writing a document, you want to typeset and print
1816 only part of a file to see what it will look like. You can use the
1817 `texinfo-tex-region' and related commands for this purpose. Use the
1818 `texinfo-tex-buffer' command to format all of a buffer.
1821 `M-x texinfo-tex-buffer'
1822 Run `texi2dvi' on the buffer. In addition to running TeX on the
1823 buffer, this command automatically creates or updates indices as
1827 `M-x texinfo-tex-region'
1828 Run TeX on the region.
1831 `M-x texinfo-texindex'
1832 Run `texindex' to sort the indices of a Texinfo file formatted with
1833 `texinfo-tex-region'. The `texinfo-tex-region' command does not
1834 run `texindex' automatically; it only runs the `tex' typesetting
1835 command. You must run the `texinfo-tex-region' command a second
1836 time after sorting the raw index files with the `texindex'
1837 command. (Usually, you do not format an index when you format a
1838 region, only when you format a buffer. Now that the `texi2dvi'
1839 command exists, there is little or no need for this command.)
1842 `M-x texinfo-tex-print'
1843 Print the file (or the part of the file) previously formatted with
1844 `texinfo-tex-buffer' or `texinfo-tex-region'.
1846 For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
1847 _must_ start with a `\input texinfo' line and must include an
1848 `@settitle' line. The file must end with `@bye' on a line by itself.
1849 (When you use `texinfo-tex-region', you must surround the `@settitle'
1850 line with start-of-header and end-of-header lines.)
1852 *Note Format/Print Hardcopy::, for a description of the other TeX
1853 related commands, such as `tex-show-print-queue'.
1856 File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
1858 Texinfo Mode Summary
1859 ====================
1861 In Texinfo mode, each set of commands has default keybindings that
1862 begin with the same keys. All the commands that are custom-created for
1863 Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
1868 The insert commands are invoked by typing `C-c' twice and then the
1869 first letter of the @-command to be inserted. (It might make more
1870 sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
1873 C-c C-c c Insert `@code'.
1874 C-c C-c d Insert `@dfn'.
1875 C-c C-c e Insert `@end'.
1876 C-c C-c i Insert `@item'.
1877 C-c C-c n Insert `@node'.
1878 C-c C-c s Insert `@samp'.
1879 C-c C-c v Insert `@var'.
1880 C-c C-c { Insert braces.
1882 C-c C-c } Move out of enclosing braces.
1884 C-c C-c C-d Insert a node's section title
1885 in the space for the description
1886 in a menu entry line.
1891 The `texinfo-show-structure' command is often used within a narrowed
1894 C-c C-s List all the headings.
1896 The Master Update Command
1897 -------------------------
1899 The `texinfo-master-menu' command creates a master menu; and can be
1900 used to update every node and menu in a file as well.
1903 M-x texinfo-master-menu
1904 Create or update a master menu.
1906 C-u C-c C-u m With `C-u' as a prefix argument, first
1907 create or update all nodes and regular
1908 menus, and then create a master menu.
1913 The update pointer commands are invoked by typing `C-c C-u' and then
1914 either `C-n' for `texinfo-update-node' or `C-e' for
1915 `texinfo-every-node-update'.
1917 C-c C-u C-n Update a node.
1918 C-c C-u C-e Update every node in the buffer.
1923 Invoke the update menu commands by typing `C-c C-u' and then either
1924 `C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
1925 To update both nodes and menus at the same time, precede `C-c C-u C-a'
1928 C-c C-u C-m Make or update a menu.
1930 C-c C-u C-a Make or update all
1933 C-u C-c C-u C-a With `C-u' as a prefix argument,
1934 first create or update all nodes and
1935 then create or update all menus.
1940 The Info formatting commands that are written in Emacs Lisp are invoked
1941 by typing `C-c C-e' and then either `C-r' for a region or `C-b' for the
1944 The Info formatting commands that are written in C and based on the
1945 `makeinfo' program are invoked by typing `C-c C-m' and then either
1946 `C-r' for a region or `C-b' for the whole buffer.
1948 Use the `texinfo-format...' commands:
1950 C-c C-e C-r Format the region.
1951 C-c C-e C-b Format the buffer.
1955 C-c C-m C-r Format the region.
1956 C-c C-m C-b Format the buffer.
1957 C-c C-m C-l Recenter the `makeinfo' output buffer.
1958 C-c C-m C-k Kill the `makeinfo' formatting job.
1963 The TeX typesetting and printing commands are invoked by typing `C-c
1964 C-t' and then another control command: `C-r' for `texinfo-tex-region',
1965 `C-b' for `texinfo-tex-buffer', and so on.
1967 C-c C-t C-r Run TeX on the region.
1968 C-c C-t C-b Run `texi2dvi' on the buffer.
1969 C-c C-t C-i Run `texindex'.
1970 C-c C-t C-p Print the DVI file.
1971 C-c C-t C-q Show the print queue.
1972 C-c C-t C-d Delete a job from the print queue.
1973 C-c C-t C-k Kill the current TeX formatting job.
1974 C-c C-t C-x Quit a currently stopped TeX formatting job.
1975 C-c C-t C-l Recenter the output buffer.
1977 Other Updating Commands
1978 -----------------------
1980 The `other updating commands' do not have standard keybindings because
1981 they are rarely used.
1983 M-x texinfo-insert-node-lines
1984 Insert missing `@node' lines in region.
1985 With `C-u' as a prefix argument,
1986 use section titles as node names.
1988 M-x texinfo-multiple-files-update
1989 Update a multi-file document.
1990 With `C-u 2' as a prefix argument,
1991 create or update all nodes and menus
1992 in all included files first.
1994 M-x texinfo-indent-menu-description
1995 Indent descriptions.
1997 M-x texinfo-sequential-node-update
1998 Insert node pointers in strict sequence.
2001 File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
2003 Beginning a Texinfo File
2004 ************************
2006 Certain pieces of information must be provided at the beginning of a
2007 Texinfo file, such as the name of the file and the title of the
2012 * Four Parts:: Four parts begin a Texinfo file.
2013 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
2014 * Header:: The very beginning of a Texinfo file.
2015 * Info Summary and Permissions:: Summary and copying permissions for Info.
2016 * Titlepage & Copyright Page:: Creating the title and copyright pages.
2017 * The Top Node:: Creating the `Top' node and master menu.
2018 * Software Copying Permissions:: Ensure that you and others continue to
2019 have the right to use and share software.
2022 File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
2024 Four Parts Begin a File
2025 =======================
2027 Generally, the beginning of a Texinfo file has four parts:
2029 1. The header, delimited by special comment lines, that includes the
2030 commands for naming the Texinfo file and telling TeX what
2031 definitions file to use when processing the Texinfo file.
2033 2. A short statement of what the file is about, with a copyright
2034 notice and copying permissions. This is enclosed in `@ifinfo' and
2035 `@end ifinfo' commands so that the formatters place it only in the
2038 3. A title page and copyright page, with a copyright notice and
2039 copying permissions. This is enclosed between `@titlepage' and
2040 `@end titlepage' commands. The title and copyright page appear
2041 only in the printed manual.
2043 4. The `Top' node that contains a menu for the whole Info file. The
2044 contents of this node appear only in the Info file.
2046 Also, optionally, you may include the copying conditions for a program
2047 and a warranty disclaimer. The copying section will be followed by an
2048 introduction or else by the first chapter of the manual.
2050 Since the copyright notice and copying permissions for the Texinfo
2051 document (in contrast to the copying permissions for a program) are in
2052 parts that appear only in the Info file or only in the printed manual,
2053 this information must be given twice.
2056 File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
2058 Sample Texinfo File Beginning
2059 =============================
2061 The following sample shows what is needed.
2063 \input texinfo @c -*-texinfo-*-
2064 @c %**start of header
2065 @setfilename NAME-OF-INFO-FILE
2066 @settitle NAME-OF-MANUAL
2067 @setchapternewpage odd
2071 This file documents ...
2073 Copyright YEAR COPYRIGHT-OWNER
2075 Permission is granted to ...
2078 @c This title page illustrates only one of the
2079 @c two methods of forming a title page.
2082 @title NAME-OF-MANUAL-WHEN-PRINTED
2083 @subtitle SUBTITLE-IF-ANY
2084 @subtitle SECOND-SUBTITLE
2087 @c The following two commands
2088 @c start the copyright page.
2090 @vskip 0pt plus 1filll
2091 Copyright @copyright{} YEAR COPYRIGHT-OWNER
2095 Permission is granted to ...
2098 @node Top, Overview, , (dir)
2101 This document describes ...
2103 This document applies to version ...
2104 of the program named ...
2108 * Copying:: Your rights and freedoms.
2109 * First Chapter:: Getting started ...
2110 * Second Chapter:: ...
2115 @node First Chapter, Second Chapter, top, top
2116 @comment node-name, next, previous, up
2117 @chapter First Chapter
2118 @cindex Index entry for First Chapter
2121 File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
2123 The Texinfo File Header
2124 =======================
2126 Texinfo files start with at least three lines that provide Info and TeX
2127 with necessary information. These are the `\input texinfo' line, the
2128 `@settitle' line, and the `@setfilename' line. If you want to run TeX
2129 on just a part of the Texinfo File, you must write the `@settitle' and
2130 `@setfilename' lines between start-of-header and end-of-header lines.
2132 Thus, the beginning of a Texinfo file looks like this:
2134 \input texinfo @c -*-texinfo-*-
2135 @setfilename sample.info
2136 @settitle Sample Document
2140 \input texinfo @c -*-texinfo-*-
2141 @c %**start of header
2142 @setfilename sample.info
2143 @settitle Sample Document
2148 * First Line:: The first line of a Texinfo file.
2149 * Start of Header:: Formatting a region requires this.
2150 * setfilename:: Tell Info the name of the Info file.
2151 * settitle:: Create a title for the printed work.
2152 * setchapternewpage:: Start chapters on right-hand pages.
2153 * paragraphindent:: An option to specify paragraph indentation.
2154 * End of Header:: Formatting a region requires this.
2157 File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header
2159 The First Line of a Texinfo File
2160 --------------------------------
2162 Every Texinfo file that is to be the top-level input to TeX must begin
2163 with a line that looks like this:
2165 \input texinfo @c -*-texinfo-*-
2167 This line serves two functions:
2169 1. When the file is processed by TeX, the `\input texinfo' command
2170 tells TeX to load the macros needed for processing a Texinfo file.
2171 These are in a file called `texinfo.tex', which is usually located
2172 in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
2173 `\', to mark the beginning of a command, just as Texinfo uses `@'.
2174 The `texinfo.tex' file causes the switch from `\' to `@'; before
2175 the switch occurs, TeX requires `\', which is why it appears at
2176 the beginning of the file.
2178 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
2179 specification tells Emacs to use Texinfo mode.
2182 File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
2187 Write a start-of-header line on the second line of a Texinfo file.
2188 Follow the start-of-header line with `@setfilename' and `@settitle'
2189 lines and, optionally, with other command lines, such as `@smallbook'
2190 or `@footnotestyle'; and then by an end-of-header line (*note End of
2193 With these lines, you can format part of a Texinfo file for Info or
2194 typeset part for printing.
2196 A start-of-header line looks like this:
2198 @c %**start of header
2200 The odd string of characters, `%**', is to ensure that no other
2201 comment is accidentally taken for a start-of-header line.
2204 File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
2209 In order to serve as the primary input file for either `makeinfo' or
2210 TeX, a Texinfo file must contain a line that looks like this:
2212 @setfilename INFO-FILE-NAME
2214 Write the `@setfilename' command at the beginning of a line and
2215 follow it on the same line by the Info file name. Do not write anything
2216 else on the line; anything on the line after the command is considered
2217 part of the file name, including what would otherwise be a comment.
2219 The `@setfilename' line specifies the name of the Info file to be
2220 generated. This name should be different from the name of the Texinfo
2221 file. There are two conventions for choosing the name: you can either
2222 remove the `.texi' extension from the input file name, or replace it
2223 with the `.info' extension.
2225 Some operating systems cannot handle long file names. You can run
2226 into a problem even when the file name you specify is itself short
2227 enough. This occurs because the Info formatters split a long Info file
2228 into short indirect subfiles, and name them by appending `-1', `-2',
2229 ..., `-10', `-11', and so on, to the original file name. (*Note Tag
2230 Files and Split Files: Tag and Split Files.) The subfile name
2231 `texinfo.info-10', for example, is too long for some systems; so the
2232 Info file name for this document is `texinfo' rather than
2235 The Info formatting commands ignore everything written before the
2236 `@setfilename' line, which is why the very first line of the file (the
2237 `\input' line) does not show up in the output.
2239 The `@setfilename' line produces no output when you typeset a manual
2240 with TeX, but it nevertheless is essential: it opens the index,
2241 cross-reference, and other auxiliary files used by Texinfo, and also
2242 reads `texinfo.cnf' if that file is present on your system (*note
2243 Preparing to Use TeX: Preparing for TeX.).
2246 File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
2251 In order to be made into a printed manual, a Texinfo file must contain
2252 a line that looks like this:
2256 Write the `@settitle' command at the beginning of a line and follow
2257 it on the same line by the title. This tells TeX the title to use in a
2258 header or footer. Do not write anything else on the line; anything on
2259 the line after the command is considered part of the title, including a
2262 Conventionally, when TeX formats a Texinfo file for double-sided
2263 output, the title is printed in the left-hand (even-numbered) page
2264 headings and the current chapter title is printed in the right-hand
2265 (odd-numbered) page headings. (TeX learns the title of each chapter
2266 from each `@chapter' command.) Page footers are not printed.
2268 Even if you are printing in a single-sided style, TeX looks for an
2269 `@settitle' command line, in case you include the manual title in the
2272 The `@settitle' command should precede everything that generates
2273 actual output in TeX.
2275 Although the title in the `@settitle' command is usually the same as
2276 the title on the title page, it does not affect the title as it appears
2277 on the title page. Thus, the two do not need not match exactly; and
2278 the title in the `@settitle' command can be a shortened or expanded
2279 version of the title as it appears on the title page. (*Note
2280 `@titlepage': titlepage.)
2282 TeX prints page headings only for that text that comes after the
2283 `@end titlepage' command in the Texinfo file, or that comes after an
2284 `@headings' command that turns on headings. (*Note The `@headings'
2285 Command: headings on off, for more information.)
2287 You may, if you wish, create your own, customized headings and
2288 footings. *Note Page Headings: Headings, for a detailed discussion of
2292 File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header
2294 `@setchapternewpage'
2295 --------------------
2297 In a book or a manual, text is usually printed on both sides of the
2298 paper, chapters start on right-hand pages, and right-hand pages have
2299 odd numbers. But in short reports, text often is printed only on one
2300 side of the paper. Also in short reports, chapters sometimes do not
2301 start on new pages, but are printed on the same page as the end of the
2302 preceding chapter, after a small amount of vertical whitespace.
2304 You can use the `@setchapternewpage' command with various arguments
2305 to specify how TeX should start chapters and whether it should typeset
2306 pages for printing on one or both sides of the paper (single-sided or
2307 double-sided printing).
2309 Write the `@setchapternewpage' command at the beginning of a line
2310 followed by its argument.
2312 For example, you would write the following to cause each chapter to
2313 start on a fresh odd-numbered page:
2315 @setchapternewpage odd
2317 You can specify one of three alternatives with the
2318 `@setchapternewpage' command:
2320 `@setchapternewpage off'
2321 Cause TeX to typeset a new chapter on the same page as the last
2322 chapter, after skipping some vertical whitespace. Also, cause TeX
2323 to format page headers for single-sided printing. (You can
2324 override the headers format with the `@headings double' command;
2325 see *Note The `@headings' Command: headings on off.)
2327 `@setchapternewpage on'
2328 Cause TeX to start new chapters on new pages and to typeset page
2329 headers for single-sided printing. This is the form most often
2330 used for short reports.
2332 This alternative is the default.
2334 `@setchapternewpage odd'
2335 Cause TeX to start new chapters on new, odd-numbered pages
2336 (right-handed pages) and to typeset for double-sided printing.
2337 This is the form most often used for books and manuals.
2339 Texinfo does not have an `@setchapternewpage even' command.
2341 (You can countermand or modify an `@setchapternewpage' command with an
2342 `@headings' command. *Note The `@headings' Command: headings on off.)
2344 At the beginning of a manual or book, pages are not numbered--for
2345 example, the title and copyright pages of a book are not numbered. By
2346 convention, table of contents pages are numbered with roman numerals
2347 and not in sequence with the rest of the document.
2349 Since an Info file does not have pages, the `@setchapternewpage'
2350 command has no effect on it.
2352 Usually, you do not write an `@setchapternewpage' command for
2353 single-sided printing, but accept the default which is to typeset for
2354 single-sided printing and to start new chapters on new pages. Usually,
2355 you write an `@setchapternewpage odd' command for double-sided printing.
2358 File: texinfo.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header
2363 The Info formatting commands may insert spaces at the beginning of the
2364 first line of each paragraph, thereby indenting that paragraph. You
2365 can use the `@paragraphindent' command to specify the indentation.
2366 Write an `@paragraphindent' command at the beginning of a line followed
2367 by either `asis' or a number. The template is:
2369 @paragraphindent INDENT
2371 The Info formatting commands indent according to the value of INDENT:
2373 * If the value of INDENT is `asis', the Info formatting commands do
2374 not change the existing indentation.
2376 * If the value of INDENT is zero, the Info formatting commands delete
2377 existing indentation.
2379 * If the value of INDENT is greater than zero, the Info formatting
2380 commands indent the paragraph by that number of spaces.
2382 The default value of INDENT is `asis'.
2384 Write the `@paragraphindent' command before or shortly after the
2385 end-of-header line at the beginning of a Texinfo file. (If you write
2386 the command between the start-of-header and end-of-header lines, the
2387 region formatting commands indent paragraphs as specified.)
2389 A peculiarity of the `texinfo-format-buffer' and
2390 `texinfo-format-region' commands is that they do not indent (nor fill)
2391 paragraphs that contain `@w' or `@*' commands. *Note Refilling
2392 Paragraphs::, for a detailed description of what goes on.
2395 File: texinfo.info, Node: End of Header, Prev: paragraphindent, Up: Header
2400 Follow the header lines with an end-of-header line. An end-of-header
2401 line looks like this:
2405 If you include the `@setchapternewpage' command between the
2406 start-of-header and end-of-header lines, TeX will typeset a region as
2407 that command specifies. Similarly, if you include an `@smallbook'
2408 command between the start-of-header and end-of-header lines, TeX will
2409 typeset a region in the "small" book format.
2411 The reason for the odd string of characters (`%**') is so that the
2412 `texinfo-tex-region' command does not accidentally find something that
2413 it should not when it is looking for the header.
2415 The start-of-header line and the end-of-header line are Texinfo mode
2416 variables that you can change.
2419 File: texinfo.info, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File
2421 Summary and Copying Permissions for Info
2422 ========================================
2424 The title page and the copyright page appear only in the printed copy of
2425 the manual; therefore, the same information must be inserted in a
2426 section that appears only in the Info file. This section usually
2427 contains a brief description of the contents of the Info file, a
2428 copyright notice, and copying permissions.
2430 The copyright notice should read:
2432 Copyright YEAR COPYRIGHT-OWNER
2434 and be put on a line by itself.
2436 Standard text for the copyright permissions is contained in an
2437 appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
2438 Permissions, for the complete text.
2440 The permissions text appears in an Info file _before_ the first node.
2441 This mean that a reader does _not_ see this text when reading the file
2442 using Info, except when using the advanced Info command `g *'.
2445 File: texinfo.info, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File
2447 The Title and Copyright Pages
2448 =============================
2450 A manual's name and author are usually printed on a title page.
2451 Sometimes copyright information is printed on the title page as well;
2452 more often, copyright information is printed on the back of the title
2455 The title and copyright pages appear in the printed manual, but not
2456 in the Info file. Because of this, it is possible to use several
2457 slightly obscure TeX typesetting commands that cannot be used in an
2458 Info file. In addition, this part of the beginning of a Texinfo file
2459 contains the text of the copying permissions that will appear in the
2462 *Note Titlepage Copying Permissions: Titlepage Permissions, for the
2463 standard text for the copyright permissions.
2467 * titlepage:: Create a title for the printed document.
2468 * titlefont center sp:: The `@titlefont', `@center',
2470 * title subtitle author:: The `@title', `@subtitle',
2471 and `@author' commands.
2472 * Copyright & Permissions:: How to write the copyright notice and
2473 include copying permissions.
2474 * end titlepage:: Turn on page headings after the title and
2476 * headings on off:: An option for turning headings on and off
2477 and double or single sided printing.
2480 File: texinfo.info, Node: titlepage, Next: titlefont center sp, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page
2485 Start the material for the title page and following copyright page with
2486 `@titlepage' on a line by itself and end it with `@end titlepage' on a
2489 The `@end titlepage' command starts a new page and turns on page
2490 numbering. (*Note Page Headings: Headings, for details about how to
2491 generate page headings.) All the material that you want to appear on
2492 unnumbered pages should be put between the `@titlepage' and `@end
2493 titlepage' commands. By using the `@page' command you can force a page
2494 break within the region delineated by the `@titlepage' and `@end
2495 titlepage' commands and thereby create more than one unnumbered page.
2496 This is how the copyright page is produced. (The `@titlepage' command
2497 might perhaps have been better named the `@titleandadditionalpages'
2498 command, but that would have been rather long!)
2500 When you write a manual about a computer program, you should write the
2501 version of the program to which the manual applies on the title page.
2502 If the manual changes more frequently than the program or is
2503 independent of it, you should also include an edition number(1) (*note
2504 titlepage-Footnote-1::) for the manual. This helps readers keep track
2505 of which manual is for which version of the program. (The `Top' node
2506 should also contain this information; see *Note `@top': makeinfo top.)
2508 Texinfo provides two main methods for creating a title page. One
2509 method uses the `@titlefont', `@sp', and `@center' commands to generate
2510 a title page in which the words on the page are centered.
2512 The second method uses the `@title', `@subtitle', and `@author'
2513 commands to create a title page with black rules under the title and
2514 author lines and the subtitle text set flush to the right hand side of
2515 the page. With this method, you do not specify any of the actual
2516 formatting of the title page. You specify the text you want, and
2517 Texinfo does the formatting. You may use either method.
2519 For extremely simple applications, Texinfo also provides a command
2520 `@shorttitlepage' which takes a single argument as the title. The
2521 argument is typeset on a page by itself and followed by a blank page.
2524 File: texinfo.info, Node: titlepage-Footnotes, Up: titlepage
2526 (1) We have found that it is helpful to refer to versions of manuals
2527 as `editions' and versions of programs as `versions'; otherwise, we
2528 find we are liable to confuse each other in conversation by referring
2529 to both the documentation and the software with the same words.
2532 File: texinfo.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page
2534 `@titlefont', `@center', and `@sp'
2535 ----------------------------------
2537 You can use the `@titlefont', `@sp', and `@center' commands to create a
2538 title page for a printed document. (This is the first of the two
2539 methods for creating a title page in Texinfo.)
2541 Use the `@titlefont' command to select a large font suitable for the
2548 Use the `@center' command at the beginning of a line to center the
2549 remaining text on that line. Thus,
2551 @center @titlefont{Texinfo}
2553 centers the title, which in this example is "Texinfo" printed in the
2556 Use the `@sp' command to insert vertical space. For example:
2560 This inserts two blank lines on the printed page. (*Note `@sp': sp,
2561 for more information about the `@sp' command.)
2563 A template for this method looks like this:
2567 @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
2569 @center SUBTITLE-IF-ANY
2575 The spacing of the example fits an 8 1/2 by 11 inch manual.
2578 File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page
2580 `@title', `@subtitle', and `@author'
2581 ------------------------------------
2583 You can use the `@title', `@subtitle', and `@author' commands to create
2584 a title page in which the vertical and horizontal spacing is done for
2585 you automatically. This contrasts with the method described in the
2586 previous section, in which the `@sp' command is needed to adjust
2589 Write the `@title', `@subtitle', or `@author' commands at the
2590 beginning of a line followed by the title, subtitle, or author.
2592 The `@title' command produces a line in which the title is set flush
2593 to the left-hand side of the page in a larger than normal font. The
2594 title is underlined with a black rule.
2596 The `@subtitle' command sets subtitles in a normal-sized font flush
2597 to the right-hand side of the page.
2599 The `@author' command sets the names of the author or authors in a
2600 middle-sized font flush to the left-hand side of the page on a line
2601 near the bottom of the title page. The names are underlined with a
2602 black rule that is thinner than the rule that underlines the title.
2603 (The black rule only occurs if the `@author' command line is followed
2604 by an `@page' command line.)
2606 There are two ways to use the `@author' command: you can write the
2607 name or names on the remaining part of the line that starts with an
2610 @author by Jane Smith and John Doe
2612 or you can write the names one above each other by using two (or more)
2618 (Only the bottom name is underlined with a black rule.)
2620 A template for this method looks like this:
2623 @title NAME-OF-MANUAL-WHEN-PRINTED
2624 @subtitle SUBTITLE-IF-ANY
2625 @subtitle SECOND-SUBTITLE
2631 Contrast this form with the form of a title page written using the
2632 `@sp', `@center', and `@titlefont' commands:
2636 @center @titlefont{Name of Manual When Printed}
2638 @center Subtitle, If Any
2640 @center Second subtitle
2648 File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page
2650 Copyright Page and Permissions
2651 ------------------------------
2653 By international treaty, the copyright notice for a book should be
2654 either on the title page or on the back of the title page. The
2655 copyright notice should include the year followed by the name of the
2656 organization or person who owns the copyright.
2658 When the copyright notice is on the back of the title page, that page
2659 is customarily not numbered. Therefore, in Texinfo, the information on
2660 the copyright page should be within `@titlepage' and `@end titlepage'
2663 Use the `@page' command to cause a page break. To push the copyright
2664 notice and the other text on the copyright page towards the bottom of
2665 the page, you can write a somewhat mysterious line after the `@page'
2666 command that reads like this:
2668 @vskip 0pt plus 1filll
2670 This is a TeX command that is not supported by the Info formatting
2671 commands. The `@vskip' command inserts whitespace. The `0pt plus
2672 1filll' means to put in zero points of mandatory whitespace, and as
2673 much optional whitespace as needed to push the following text to the
2674 bottom of the page. Note the use of three `l's in the word `filll';
2675 this is the correct usage in TeX.
2677 In a printed manual, the `@copyright{}' command generates a `c'
2678 inside a circle. (In Info, it generates `(C)'.) The copyright notice
2679 itself has the following legally defined sequence:
2681 Copyright (C) YEAR COPYRIGHT-OWNER
2683 It is customary to put information on how to get a manual after the
2684 copyright notice, followed by the copying permissions for the manual.
2686 Note that permissions must be given here as well as in the summary
2687 segment within `@ifinfo' and `@end ifinfo' that immediately follows the
2688 header since this text appears only in the printed manual and the
2689 `ifinfo' text appears only in the Info file.
2691 *Note Sample Permissions::, for the standard text.
2694 File: texinfo.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page
2699 An `@end titlepage' command on a line by itself not only marks the end
2700 of the title and copyright pages, but also causes TeX to start
2701 generating page headings and page numbers.
2703 To repeat what is said elsewhere, Texinfo has two standard page
2704 heading formats, one for documents which are printed on one side of
2705 each sheet of paper (single-sided printing), and the other for
2706 documents which are printed on both sides of each sheet (double-sided
2707 printing). (*Note `@setchapternewpage': setchapternewpage.) You can
2708 specify these formats in different ways:
2710 * The conventional way is to write an `@setchapternewpage' command
2711 before the title page commands, and then have the `@end titlepage'
2712 command start generating page headings in the manner desired.
2713 (*Note `@setchapternewpage': setchapternewpage.)
2715 * Alternatively, you can use the `@headings' command to prevent page
2716 headings from being generated or to start them for either single or
2717 double-sided printing. (Write an `@headings' command immediately
2718 after the `@end titlepage' command. *Note The `@headings'
2719 Command: headings on off, for more information.)
2721 * Or, you may specify your own page heading and footing format.
2722 *Note Page Headings: Headings, for detailed information about page
2723 headings and footings.
2725 Most documents are formatted with the standard single-sided or
2726 double-sided format, using `@setchapternewpage odd' for double-sided
2727 printing and no `@setchapternewpage' command for single-sided printing.
2730 File: texinfo.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page
2732 The `@headings' Command
2733 -----------------------
2735 The `@headings' command is rarely used. It specifies what kind of page
2736 headings and footings to print on each page. Usually, this is
2737 controlled by the `@setchapternewpage' command. You need the
2738 `@headings' command only if the `@setchapternewpage' command does not
2739 do what you want, or if you want to turn off pre-defined page headings
2740 prior to defining your own. Write an `@headings' command immediately
2741 after the `@end titlepage' command.
2743 You can use `@headings' as follows:
2746 Turn off printing of page headings.
2749 Turn on page headings appropriate for single-sided printing.
2752 Turn on page headings appropriate for double-sided printing. The
2753 two commands, `@headings on' and `@headings double', are
2756 `@headings singleafter'
2757 `@headings doubleafter'
2758 Turn on `single' or `double' headings, respectively, after the
2759 current page is output.
2762 Turn on page headings: `single' if `@setchapternewpage on',
2765 For example, suppose you write `@setchapternewpage off' before the
2766 `@titlepage' command to tell TeX to start a new chapter on the same
2767 page as the end of the last chapter. This command also causes TeX to
2768 typeset page headers for single-sided printing. To cause TeX to
2769 typeset for double sided printing, write `@headings double' after the
2770 `@end titlepage' command.
2772 You can stop TeX from generating any page headings at all by writing
2773 `@headings off' on a line of its own immediately after the line
2774 containing the `@end titlepage' command, like this:
2779 The `@headings off' command overrides the `@end titlepage' command,
2780 which would otherwise cause TeX to print page headings.
2782 You can also specify your own style of page heading and footing.
2783 *Note Page Headings: Headings, for more information.
2786 File: texinfo.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File
2788 The `Top' Node and Master Menu
2789 ==============================
2791 The `Top' node is the node from which you enter an Info file.
2793 A `Top' node should contain a brief description of the Info file and
2794 an extensive, master menu for the whole Info file. This helps the
2795 reader understand what the Info file is about. Also, you should write
2796 the version number of the program to which the Info file applies; or,
2797 at least, the edition number.
2799 The contents of the `Top' node should appear only in the Info file;
2800 none of it should appear in printed output, so enclose it between
2801 `@ifinfo' and `@end ifinfo' commands. (TeX does not print either an
2802 `@node' line or a menu; they appear only in Info; strictly speaking,
2803 you are not required to enclose these parts between `@ifinfo' and `@end
2804 ifinfo', but it is simplest to do so. *Note Conditionally Visible
2805 Text: Conditionals.)
2809 * Title of Top Node:: Sketch what the file is about.
2810 * Master Menu Parts:: A master menu has three or more parts.
2813 File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Prev: The Top Node, Up: The Top Node
2818 Sometimes, you will want to place an `@top' sectioning command line
2819 containing the title of the document immediately after the `@node Top'
2820 line (*note The `@top' Sectioning Command: makeinfo top command., for
2823 For example, the beginning of the Top node of this manual contains an
2824 `@top' sectioning command, a short description, and edition and version
2825 information. It looks like this:
2831 @node Top, Copying, , (dir)
2834 Texinfo is a documentation system...
2841 * Copying:: Texinfo is freely
2843 * Overview:: What is Texinfo?
2847 In a `Top' node, the `Previous', and `Up' nodes usually refer to the
2848 top level directory of the whole Info system, which is called `(dir)'.
2849 The `Next' node refers to the first node that follows the main or master
2850 menu, which is usually the copying permissions, introduction, or first
2854 File: texinfo.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node
2856 Parts of a Master Menu
2857 ----------------------
2859 A "master menu" is a detailed main menu listing all the nodes in a file.
2861 A master menu is enclosed in `@menu' and `@end menu' commands and
2862 does not appear in the printed document.
2864 Generally, a master menu is divided into parts.
2866 * The first part contains the major nodes in the Texinfo file: the
2867 nodes for the chapters, chapter-like sections, and the appendices.
2869 * The second part contains nodes for the indices.
2871 * The third and subsequent parts contain a listing of the other,
2872 lower level nodes, often ordered by chapter. This way, rather
2873 than go through an intermediary menu, an inquirer can go directly
2874 to a particular node when searching for specific information.
2875 These menu items are not required; add them if you think they are a
2876 convenience. If you do use them, put `@detailmenu' before the
2877 first one, and `@end detailmenu' after the last; otherwise,
2878 `makeinfo' will get confused.
2880 Each section in the menu can be introduced by a descriptive line. So
2881 long as the line does not begin with an asterisk, it will not be
2882 treated as a menu entry. (*Note Writing a Menu::, for more
2885 For example, the master menu for this manual looks like the following
2886 (but has many more entries):
2889 * Copying:: Texinfo is freely
2891 * Overview:: What is Texinfo?
2892 * Texinfo Mode:: Special features in GNU Emacs.
2895 * Command and Variable Index::
2896 An entry for each @-command.
2897 * Concept Index:: An entry for each concept.
2900 --- The Detailed Node Listing ---
2904 * Info Files:: What is an Info file?
2905 * Printed Manuals:: Characteristics of
2912 * Info on a Region:: Formatting part of a file
2920 File: texinfo.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File
2922 Software Copying Permissions
2923 ============================
2925 If the Texinfo file has a section containing the "General Public
2926 License" and the distribution information and a warranty disclaimer for
2927 the software that is documented, this section usually follows the `Top'
2928 node. The General Public License is very important to Project GNU
2929 software. It ensures that you and others will continue to have a right
2930 to use and share the software.
2932 The copying and distribution information and the disclaimer are
2933 followed by an introduction or else by the first chapter of the manual.
2935 Although an introduction is not a required part of a Texinfo file, it
2936 is very helpful. Ideally, it should state clearly and concisely what
2937 the file is about and who would be interested in reading it. In
2938 general, an introduction would follow the licensing and distribution
2939 information, although sometimes people put it earlier in the document.
2940 Usually, an introduction is put in an `@unnumbered' section. (*Note
2941 The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
2944 File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top
2946 Ending a Texinfo File
2947 *********************
2949 The end of a Texinfo file should include the commands that create
2950 indices and generate detailed and summary tables of contents. And it
2951 must include the `@bye' command that marks the last line processed by
2956 @node Concept Index, , Variables Index, Top
2957 @c node-name, next, previous, up
2958 @unnumbered Concept Index
2967 * Printing Indices & Menus:: How to print an index in hardcopy and
2968 generate index menus in Info.
2969 * Contents:: How to create a table of contents.
2970 * File End:: How to mark the end of a file.
2973 File: texinfo.info, Node: Printing Indices & Menus, Next: Contents, Prev: Ending a File, Up: Ending a File
2975 Index Menus and Printing an Index
2976 =================================
2978 To print an index means to include it as part of a manual or Info file.
2979 This does not happen automatically just because you use `@cindex' or
2980 other index-entry generating commands in the Texinfo file; those just
2981 cause the raw data for the index to be accumulated. To generate an
2982 index, you must include the `@printindex' command at the place in the
2983 document where you want the index to appear. Also, as part of the
2984 process of creating a printed manual, you must run a program called
2985 `texindex' (*note Format/Print Hardcopy::) to sort the raw data to
2986 produce a sorted index file. The sorted index file is what is actually
2987 used to print the index.
2989 Texinfo offers six different types of predefined index: the concept
2990 index, the function index, the variables index, the keystroke index, the
2991 program index, and the data type index (*note Predefined Indices::).
2992 Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
2993 and `tp'. You may merge indices, or put them into separate sections
2994 (*note Combining Indices::); or you may define your own indices (*note
2995 Defining New Indices: New Indices.).
2997 The `@printindex' command takes a two-letter index name, reads the
2998 corresponding sorted index file and formats it appropriately into an
3001 The `@printindex' command does not generate a chapter heading for the
3002 index. Consequently, you should precede the `@printindex' command with
3003 a suitable section or chapter command (usually `@unnumbered') to supply
3004 the chapter heading and put the index into the table of contents.
3005 Precede the `@unnumbered' command with an `@node' line.
3009 @node Variable Index, Concept Index, Function Index, Top
3010 @comment node-name, next, previous, up
3011 @unnumbered Variable Index
3015 @node Concept Index, , Variable Index, Top
3016 @comment node-name, next, previous, up
3017 @unnumbered Concept Index
3025 (Readers often prefer that the concept index come last in a book, since
3026 that makes it easiest to find.)
3029 File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File
3031 Generating a Table of Contents
3032 ==============================
3034 The `@chapter', `@section', and other structuring commands supply the
3035 information to make up a table of contents, but they do not cause an
3036 actual table to appear in the manual. To do this, you must use the
3037 `@contents' and `@summarycontents' commands:
3040 Generate a table of contents in a printed manual, including all
3041 chapters, sections, subsections, etc., as well as appendices and
3042 unnumbered chapters. (Headings generated by the `@heading' series
3043 of commands do not appear in the table of contents.) The
3044 `@contents' command should be written on a line by itself.
3048 (`@summarycontents' is a synonym for `@shortcontents'; the two
3049 commands are exactly the same.)
3051 Generate a short or summary table of contents that lists only the
3052 chapters (and appendices and unnumbered chapters). Omit sections,
3053 subsections and subsubsections. Only a long manual needs a short
3054 table of contents in addition to the full table of contents.
3056 Write the `@shortcontents' command on a line by itself right
3057 _before_ the `@contents' command.
3059 The table of contents commands automatically generate a chapter-like
3060 heading at the top of the first table of contents page. Write the table
3061 of contents commands at the very end of a Texinfo file, just before the
3062 `@bye' command, following any index sections--anything in the Texinfo
3063 file after the table of contents commands will be omitted from the
3066 When you print a manual with a table of contents, the table of
3067 contents are printed last and numbered with roman numerals. You need
3068 to place those pages in their proper place, after the title page,
3069 yourself. (This is the only collating you need to do for a printed
3070 manual. The table of contents is printed last because it is generated
3071 after the rest of the manual is typeset.)
3073 Here is an example of where to write table of contents commands:
3080 Since an Info file uses menus instead of tables of contents, the Info
3081 formatting commands ignore the `@contents' and `@shortcontents'
3085 File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File
3090 An `@bye' command terminates TeX or Info formatting. None of the
3091 formatting commands see any of the file following `@bye'. The `@bye'
3092 command should be on a line by itself.
3094 If you wish, you may follow the `@bye' line with notes. These notes
3095 will not be formatted and will not appear in either Info or a printed
3096 manual; it is as if text after `@bye' were within `@ignore' ... `@end
3097 ignore'. Also, you may follow the `@bye' line with a local variables
3098 list. *Note Using Local Variables and the Compile Command:
3099 Compile-Command, for more information.
3102 File: texinfo.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top
3107 The "chapter structuring" commands divide a document into a hierarchy of
3108 chapters, sections, subsections, and subsubsections. These commands
3109 generate large headings; they also provide information for the table of
3110 contents of a printed manual (*note Generating a Table of Contents:
3113 The chapter structuring commands do not create an Info node structure,
3114 so normally you should put an `@node' command immediately before each
3115 chapter structuring command (*note Nodes::). The only time you are
3116 likely to use the chapter structuring commands without using the node
3117 structuring commands is if you are writing a document that contains no
3118 cross references and will never be transformed into Info format.
3120 It is unlikely that you will ever write a Texinfo file that is
3121 intended only as an Info file and not as a printable document. If you
3122 do, you might still use chapter structuring commands to create a
3123 heading at the top of each node--but you don't need to.
3127 * Tree Structuring:: A manual is like an upside down tree ...
3128 * Structuring Command Types:: How to divide a manual into parts.
3129 * makeinfo top:: The `@top' command, part of the `Top' node.
3131 * unnumbered & appendix::
3132 * majorheading & chapheading::
3134 * unnumberedsec appendixsec heading::
3136 * unnumberedsubsec appendixsubsec subheading::
3137 * subsubsection:: Commands for the lowest level sections.
3138 * Raise/lower sections:: How to change commands' hierarchical level.
3141 File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Prev: Structuring, Up: Structuring
3143 Tree Structure of Sections
3144 ==========================
3146 A Texinfo file is usually structured like a book with chapters,
3147 sections, subsections, and the like. This structure can be visualized
3148 as a tree (or rather as an upside-down tree) with the root at the top
3149 and the levels corresponding to chapters, sections, subsection, and
3152 Here is a diagram that shows a Texinfo file with three chapters, each
3153 of which has two sections.
3157 -------------------------------------
3159 Chapter 1 Chapter 2 Chapter 3
3161 -------- -------- --------
3163 Section Section Section Section Section Section
3164 1.1 1.2 2.1 2.2 3.1 3.2
3166 In a Texinfo file that has this structure, the beginning of Chapter 2
3169 @node Chapter 2, Chapter 3, Chapter 1, top
3172 The chapter structuring commands are described in the sections that
3173 follow; the `@node' and `@menu' commands are described in following
3174 chapters. (*Note Nodes::, and see *Note Menus::.)
3177 File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring
3179 Types of Structuring Commands
3180 =============================
3182 The chapter structuring commands fall into four groups or series, each
3183 of which contains structuring commands corresponding to the
3184 hierarchical levels of chapters, sections, subsections, and
3187 The four groups are the `@chapter' series, the `@unnumbered' series,
3188 the `@appendix' series, and the `@heading' series.
3190 Each command produces titles that have a different appearance on the
3191 printed page or Info file; only some of the commands produce titles
3192 that are listed in the table of contents of a printed book or manual.
3194 * The `@chapter' and `@appendix' series of commands produce numbered
3195 or lettered entries both in the body of a printed work and in its
3198 * The `@unnumbered' series of commands produce unnumbered entries
3199 both in the body of a printed work and in its table of contents.
3200 The `@top' command, which has a special use, is a member of this
3201 series (*note `@top': makeinfo top.).
3203 * The `@heading' series of commands produce unnumbered headings that
3204 do not appear in a table of contents. The heading commands never
3207 * The `@majorheading' command produces results similar to using the
3208 `@chapheading' command but generates a larger vertical whitespace
3211 * When an `@setchapternewpage' command says to do so, the
3212 `@chapter', `@unnumbered', and `@appendix' commands start new
3213 pages in the printed manual; the `@heading' commands do not.
3215 Here are the four groups of chapter structuring commands:
3219 Numbered Unnumbered Lettered and numbered Unnumbered
3220 In contents In contents In contents Not in contents
3223 @chapter @unnumbered @appendix @chapheading
3224 @section @unnumberedsec @appendixsec @heading
3225 @subsection @unnumberedsubsec @appendixsubsec @subheading
3226 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
3229 File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring
3234 The `@top' command is a special sectioning command that you use only
3235 after an `@node Top' line at the beginning of a Texinfo file. The
3236 `@top' command tells the `makeinfo' formatter which node is the `Top'
3237 node. It has the same typesetting effect as `@unnumbered' (*note
3238 `@unnumbered': (`@appendix')unnumbered & appendix.). For detailed
3239 information, see *Note The `@top' Command: makeinfo top command.
3242 File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring
3247 `@chapter' identifies a chapter in the document. Write the command at
3248 the beginning of a line and follow it on the same line by the title of
3251 For example, this chapter in this manual is entitled "Chapter
3252 Structuring"; the `@chapter' line looks like this:
3254 @chapter Chapter Structuring
3256 In TeX, the `@chapter' command creates a chapter in the document,
3257 specifying the chapter title. The chapter is numbered automatically.
3259 In Info, the `@chapter' command causes the title to appear on a line
3260 by itself, with a line of asterisks inserted underneath. Thus, in
3261 Info, the above example produces the following output:
3266 Texinfo also provides a command `@centerchap', which is analogous to
3267 `@unnumbered', but centers its argument in the printed output. This
3268 kind of stylistic choice is not usually offered by Texinfo.
3271 File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring
3273 `@unnumbered', `@appendix'
3274 ==========================
3276 Use the `@unnumbered' command to create a chapter that appears in a
3277 printed manual without chapter numbers of any kind. Use the
3278 `@appendix' command to create an appendix in a printed manual that is
3279 labelled by letter instead of by number.
3281 For Info file output, the `@unnumbered' and `@appendix' commands are
3282 equivalent to `@chapter': the title is printed on a line by itself with
3283 a line of asterisks underneath. (*Note `@chapter': chapter.)
3285 To create an appendix or an unnumbered chapter, write an `@appendix'
3286 or `@unnumbered' command at the beginning of a line and follow it on
3287 the same line by the title, as you would if you were creating a chapter.
3290 File: texinfo.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring
3292 `@majorheading', `@chapheading'
3293 ===============================
3295 The `@majorheading' and `@chapheading' commands put chapter-like
3296 headings in the body of a document.
3298 However, neither command causes TeX to produce a numbered heading or
3299 an entry in the table of contents; and neither command causes TeX to
3300 start a new page in a printed manual.
3302 In TeX, an `@majorheading' command generates a larger vertical
3303 whitespace before the heading than an `@chapheading' command but is
3306 In Info, the `@majorheading' and `@chapheading' commands are
3307 equivalent to `@chapter': the title is printed on a line by itself with
3308 a line of asterisks underneath. (*Note `@chapter': chapter.)
3311 File: texinfo.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring
3316 In a printed manual, an `@section' command identifies a numbered
3317 section within a chapter. The section title appears in the table of
3318 contents. In Info, an `@section' command provides a title for a
3319 segment of text, underlined with `='.
3321 This section is headed with an `@section' command and looks like this
3322 in the Texinfo file:
3324 @section @code{@@section}
3326 To create a section, write the `@section' command at the beginning of
3327 a line and follow it on the same line by the section title.
3331 @section This is a section
3341 File: texinfo.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring
3343 `@unnumberedsec', `@appendixsec', `@heading'
3344 ============================================
3346 The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
3347 respectively, the unnumbered, appendix-like, and heading-like
3348 equivalents of the `@section' command. (*Note `@section': section.)
3351 The `@unnumberedsec' command may be used within an unnumbered
3352 chapter or within a regular chapter or appendix to provide an
3357 `@appendixsection' is a longer spelling of the `@appendixsec'
3358 command; the two are synonymous.
3360 Conventionally, the `@appendixsec' or `@appendixsection' command
3361 is used only within appendices.
3364 You may use the `@heading' command anywhere you wish for a
3365 section-style heading that will not appear in the table of
3369 File: texinfo.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring
3371 The `@subsection' Command
3372 =========================
3374 Subsections are to sections as sections are to chapters. (*Note
3375 `@section': section.) In Info, subsection titles are underlined with
3378 @subsection This is a subsection
3382 This is a subsection
3383 --------------------
3385 In a printed manual, subsections are listed in the table of contents
3386 and are numbered three levels deep.
3389 File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
3391 The `@subsection'-like Commands
3392 ===============================
3394 The `@unnumberedsubsec', `@appendixsubsec', and `@subheading' commands
3395 are, respectively, the unnumbered, appendix-like, and heading-like
3396 equivalents of the `@subsection' command. (*Note `@subsection':
3399 In Info, the `@subsection'-like commands generate a title underlined
3400 with hyphens. In a printed manual, an `@subheading' command produces a
3401 heading like that of a subsection except that it is not numbered and
3402 does not appear in the table of contents. Similarly, an
3403 `@unnumberedsubsec' command produces an unnumbered heading like that of
3404 a subsection and an `@appendixsubsec' command produces a
3405 subsection-like heading labelled with a letter and numbers; both of
3406 these commands produce headings that appear in the table of contents.
3409 File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
3411 The `subsub' Commands
3412 =====================
3414 The fourth and lowest level sectioning commands in Texinfo are the
3415 `subsub' commands. They are:
3418 Subsubsections are to subsections as subsections are to sections.
3419 (*Note `@subsection': subsection.) In a printed manual,
3420 subsubsection titles appear in the table of contents and are
3421 numbered four levels deep.
3423 `@unnumberedsubsubsec'
3424 Unnumbered subsubsection titles appear in the table of contents of
3425 a printed manual, but lack numbers. Otherwise, unnumbered
3426 subsubsections are the same as subsubsections. In Info, unnumbered
3427 subsubsections look exactly like ordinary subsubsections.
3429 `@appendixsubsubsec'
3430 Conventionally, appendix commands are used only for appendices and
3431 are lettered and numbered appropriately in a printed manual. They
3432 also appear in the table of contents. In Info, appendix
3433 subsubsections look exactly like ordinary subsubsections.
3436 The `@subsubheading' command may be used anywhere that you need a
3437 small heading that will not appear in the table of contents. In
3438 Info, subsubheadings look exactly like ordinary subsubsection
3441 In Info, `subsub' titles are underlined with periods. For example,
3443 @subsubsection This is a subsubsection
3447 This is a subsubsection
3448 .......................
3451 File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring
3453 `@raisesections' and `@lowersections'
3454 =====================================
3456 The `@raisesections' and `@lowersections' commands raise and lower the
3457 hierarchical level of chapters, sections, subsections and the like.
3458 The `@raisesections' command changes sections to chapters, subsections
3459 to sections, and so on. The `@lowersections' command changes chapters
3460 to sections, sections to subsections, and so on.
3462 An `@lowersections' command is useful if you wish to include text
3463 that is written as an outer or standalone Texinfo file in another
3464 Texinfo file as an inner, included file. If you write the command at
3465 the beginning of the file, all your `@chapter' commands are formatted
3466 as if they were `@section' commands, all your `@section' command are
3467 formatted as if they were `@subsection' commands, and so on.
3469 `@raisesections' raises a command one level in the chapter
3470 structuring hierarchy:
3474 @subsection @section,
3476 @heading @chapheading,
3479 `@lowersections' lowers a command one level in the chapter
3480 structuring hierarchy:
3485 @subsection @subsubsection,
3486 @heading @subheading,
3489 An `@raisesections' or `@lowersections' command changes only those
3490 structuring commands that follow the command in the Texinfo file.
3491 Write an `@raisesections' or `@lowersections' command on a line of its
3494 An `@lowersections' command cancels an `@raisesections' command, and
3495 vice versa. Typically, the commands are used like this:
3498 @include somefile.texi
3501 Without the `@raisesections', all the subsequent sections in your
3502 document will be lowered.
3504 Repeated use of the commands continue to raise or lower the
3505 hierarchical level a step at a time.
3507 An attempt to raise above `chapters' reproduces chapter commands; an
3508 attempt to lower below `subsubsections' reproduces subsubsection
3512 File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
3517 "Nodes" are the primary segments of a Texinfo file. They do not
3518 themselves impose a hierarchic or any other kind of structure on a file.
3519 Nodes contain "node pointers" that name other nodes, and can contain
3520 "menus" which are lists of nodes. In Info, the movement commands can
3521 carry you to a pointed-to node or to a node listed in a menu. Node
3522 pointers and menus provide structure for Info files just as chapters,
3523 sections, subsections, and the like, provide structure for printed
3528 * Two Paths:: Different commands to structure
3529 Info output and printed output.
3530 * Node Menu Illustration:: A diagram, and sample nodes and menus.
3531 * node:: How to write a node, in detail.
3532 * makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
3535 File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Prev: Nodes, Up: Nodes
3540 The node and menu commands and the chapter structuring commands are
3541 independent of each other:
3543 * In Info, node and menu commands provide structure. The chapter
3544 structuring commands generate headings with different kinds of
3545 underlining--asterisks for chapters, hyphens for sections, and so
3546 on; they do nothing else.
3548 * In TeX, the chapter structuring commands generate chapter and
3549 section numbers and tables of contents. The node and menu
3550 commands provide information for cross references; they do nothing
3553 You can use node pointers and menus to structure an Info file any way
3554 you want; and you can write a Texinfo file so that its Info output has a
3555 different structure than its printed output. However, most Texinfo
3556 files are written such that the structure for the Info output
3557 corresponds to the structure for the printed output. It is not
3558 convenient to do otherwise.
3560 Generally, printed output is structured in a tree-like hierarchy in
3561 which the chapters are the major limbs from which the sections branch
3562 out. Similarly, node pointers and menus are organized to create a
3563 matching structure in the Info output.
3566 File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes
3568 Node and Menu Illustration
3569 ==========================
3571 Here is a copy of the diagram shown earlier that illustrates a Texinfo
3572 file with three chapters, each of which contains two sections.
3574 Note that the "root" is at the top of the diagram and the "leaves"
3575 are at the bottom. This is how such a diagram is drawn conventionally;
3576 it illustrates an upside-down tree. For this reason, the root node is
3577 called the `Top' node, and `Up' node pointers carry you closer to the
3582 -------------------------------------
3584 Chapter 1 Chapter 2 Chapter 3
3586 -------- -------- --------
3588 Section Section Section Section Section Section
3589 1.1 1.2 2.1 2.2 3.1 3.2
3591 Write the beginning of the node for Chapter 2 like this:
3593 @node Chapter 2, Chapter 3, Chapter 1, top
3594 @comment node-name, next, previous, up
3596 This `@node' line says that the name of this node is "Chapter 2", the
3597 name of the `Next' node is "Chapter 3", the name of the `Previous' node
3598 is "Chapter 1", and the name of the `Up' node is "Top".
3600 *Please Note:* `Next' refers to the next node at the same
3601 hierarchical level in the manual, not necessarily to the next node
3602 within the Texinfo file. In the Texinfo file, the subsequent node
3603 may be at a lower level--a section-level node may follow a
3604 chapter-level node, and a subsection-level node may follow a
3605 section-level node. `Next' and `Previous' refer to nodes at the
3606 _same_ hierarchical level. (The `Top' node contains the exception
3607 to this rule. Since the `Top' node is the only node at that
3608 level, `Next' refers to the first following node, which is almost
3609 always a chapter or chapter-level node.)
3611 To go to Sections 2.1 and 2.2 using Info, you need a menu inside
3612 Chapter 2. (*Note Menus::.) You would write the menu just before the
3613 beginning of Section 2.1, like this:
3616 * Sect. 2.1:: Description of this section.
3620 Write the node for Sect. 2.1 like this:
3622 @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
3623 @comment node-name, next, previous, up
3625 In Info format, the `Next' and `Previous' pointers of a node usually
3626 lead to other nodes at the same level--from chapter to chapter or from
3627 section to section (sometimes, as shown, the `Previous' pointer points
3628 up); an `Up' pointer usually leads to a node at the level above (closer
3629 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
3630 to `leaves'). (A cross reference can point to a node at any level; see
3631 *Note Cross References::.)
3633 Usually, an `@node' command and a chapter structuring command are
3634 used in sequence, along with indexing commands. (You may follow the
3635 `@node' line with a comment line that reminds you which pointer is
3638 Here is the beginning of the chapter in this manual called "Ending a
3639 Texinfo File". This shows an `@node' line followed by a comment line,
3640 an `@chapter' line, and then by indexing lines.
3642 @node Ending a File, Structuring, Beginning a File, Top
3643 @comment node-name, next, previous, up
3644 @chapter Ending a Texinfo File
3645 @cindex Ending a Texinfo file
3646 @cindex Texinfo file ending
3650 File: texinfo.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes
3655 A "node" is a segment of text that begins at an `@node' command and
3656 continues until the next `@node' command. The definition of node is
3657 different from that for chapter or section. A chapter may contain
3658 sections and a section may contain subsections; but a node cannot
3659 contain subnodes; the text of a node continues only until the next
3660 `@node' command in the file. A node usually contains only one chapter
3661 structuring command, the one that follows the `@node' line. On the
3662 other hand, in printed output nodes are used only for cross references,
3663 so a chapter or section may contain any number of nodes. Indeed, a
3664 chapter usually contains several nodes, one for each section,
3665 subsection, and subsubsection.
3667 To create a node, write an `@node' command at the beginning of a
3668 line, and follow it with four arguments, separated by commas, on the
3669 rest of the same line. These arguments are the name of the node, and
3670 the names of the `Next', `Previous', and `Up' pointers, in that order.
3671 You may insert spaces before each pointer if you wish; the spaces are
3672 ignored. You must write the name of the node, and the names of the
3673 `Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
3674 the formatters fail. (*note info: (info)Top, for more information
3675 about nodes in Info.)
3677 Usually, you write one of the chapter-structuring command lines
3678 immediately after an `@node' line--for example, an `@section' or
3679 `@subsection' line. (*Note Types of Structuring Commands: Structuring
3682 *Please note:* The GNU Emacs Texinfo mode updating commands work
3683 only with Texinfo files in which `@node' lines are followed by
3684 chapter structuring lines. *Note Updating Requirements::.
3686 TeX uses `@node' lines to identify the names to use for cross
3687 references. For this reason, you must write `@node' lines in a Texinfo
3688 file that you intend to format for printing, even if you do not intend
3689 to format it for Info. (Cross references, such as the one at the end
3690 of this sentence, are made with `@xref' and its related commands; see
3691 *Note Cross References::.)
3695 * Node Names:: How to choose node and pointer names.
3696 * Writing a Node:: How to write an `@node' line.
3697 * Node Line Tips:: Keep names short.
3698 * Node Line Requirements:: Keep names unique, without @-commands.
3699 * First Node:: How to write a `Top' node.
3700 * makeinfo top command:: How to use the `@top' command.
3701 * Top Node Summary:: Write a brief description for readers.
3704 File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: node, Up: node
3706 Choosing Node and Pointer Names
3707 -------------------------------
3709 The name of a node identifies the node. The pointers enable you to
3710 reach other nodes and consist of the names of those nodes.
3712 Normally, a node's `Up' pointer contains the name of the node whose
3713 menu mentions that node. The node's `Next' pointer contains the name
3714 of the node that follows that node in that menu and its `Previous'
3715 pointer contains the name of the node that precedes it in that menu.
3716 When a node's `Previous' node is the same as its `Up' node, both node
3717 pointers name the same node.
3719 Usually, the first node of a Texinfo file is the `Top' node, and its
3720 `Up' and `Previous' pointers point to the `dir' file, which contains
3721 the main menu for all of Info.
3723 The `Top' node itself contains the main or master menu for the manual.
3724 Also, it is helpful to include a brief description of the manual in the
3725 `Top' node. *Note First Node::, for information on how to write the
3726 first node of a Texinfo file.
3729 File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node
3731 How to Write an `@node' Line
3732 ----------------------------
3734 The easiest way to write an `@node' line is to write `@node' at the
3735 beginning of a line and then the name of the node, like this:
3739 If you are using GNU Emacs, you can use the update node commands
3740 provided by Texinfo mode to insert the names of the pointers; or you
3741 can leave the pointers out of the Texinfo file and let `makeinfo'
3742 insert node pointers into the Info file it creates. (*Note Texinfo
3743 Mode::, and *Note makeinfo Pointer Creation::.)
3745 Alternatively, you can insert the `Next', `Previous', and `Up'
3746 pointers yourself. If you do this, you may find it helpful to use the
3747 Texinfo mode keyboard command `C-c C-c n'. This command inserts
3748 `@node' and a comment line listing the names of the pointers in their
3749 proper order. The comment line helps you keep track of which arguments
3750 are for which pointers. This comment line is especially useful if you
3751 are not familiar with Texinfo.
3753 The template for a node line with `Next', `Previous', and `Up'
3754 pointers looks like this:
3756 @node NODE-NAME, NEXT, PREVIOUS, UP
3758 If you wish, you can ignore `@node' lines altogether in your first
3759 draft and then use the `texinfo-insert-node-lines' command to create
3760 `@node' lines for you. However, we do not recommend this practice. It
3761 is better to name the node itself at the same time that you write a
3762 segment so you can easily make cross references. A large number of
3763 cross references are an especially important feature of a good Info
3766 After you have inserted an `@node' line, you should immediately write
3767 an @-command for the chapter or section and insert its name. Next (and
3768 this is important!), put in several index entries. Usually, you will
3769 find at least two and often as many as four or five ways of referring
3770 to the node in the index. Use them all. This will make it much easier
3771 for people to find the node.
3774 File: texinfo.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node
3779 Here are three suggestions:
3781 * Try to pick node names that are informative but short.
3783 In the Info file, the file name, node name, and pointer names are
3784 all inserted on one line, which may run into the right edge of the
3785 window. (This does not cause a problem with Info, but is ugly.)
3787 * Try to pick node names that differ from each other near the
3788 beginnings of their names. This way, it is easy to use automatic
3789 name completion in Info.
3791 * By convention, node names are capitalized just as they would be for
3792 section or chapter titles--initial and significant words are
3793 capitalized; others are not.
3796 File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node
3798 `@node' Line Requirements
3799 -------------------------
3801 Here are several requirements for `@node' lines:
3803 * All the node names for a single Info file must be unique.
3805 Duplicates confuse the Info movement commands. This means, for
3806 example, that if you end every chapter with a summary, you must
3807 name each summary node differently. You cannot just call each one
3808 "Summary". You may, however, duplicate the titles of chapters,
3809 sections, and the like. Thus you can end each chapter in a book
3810 with a section called "Summary", so long as the node names for
3811 those sections are all different.
3813 * A pointer name must be the name of a node.
3815 The node to which a pointer points may come before or after the
3816 node containing the pointer.
3818 * You cannot use any of the Texinfo @-commands in a node name;
3819 @-commands confuse Info.
3821 Thus, the beginning of the section called `@chapter' looks like
3824 @node chapter, unnumbered & appendix, makeinfo top, Structuring
3825 @comment node-name, next, previous, up
3826 @section @code{@@chapter}
3829 * You cannot use commas or apostrophes within a node name; these
3830 confuse TeX or the Info formatters.
3832 For example, the following is a section title:
3834 @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
3836 The corresponding node name is:
3838 unnumberedsec appendixsec heading
3840 * Case is significant.
3843 File: texinfo.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node
3848 The first node of a Texinfo file is the "Top" node, except in an
3849 included file (*note Include Files::). The Top node contains the main
3850 or master menu for the document, and a short summary of the document
3851 (*note Top Node Summary::).
3853 The Top node (which must be named `top' or `Top') should have as its
3854 `Up' node the name of a node in another file, where there is a menu
3855 that leads to this file. Specify the file name in parentheses. If the
3856 file is to be installed directly in the Info directory file, use
3857 `(dir)' as the parent of the Top node; this is short for `(dir)top',
3858 and specifies the Top node in the `dir' file, which contains the main
3859 menu for the Info system as a whole. For example, the `@node Top' line
3860 of this manual looks like this:
3862 @node Top, Copying, , (dir)
3864 (You can use the Texinfo updating commands or the `makeinfo' utility to
3865 insert these pointers automatically.)
3867 Do not define the `Previous' node of the Top node to be `(dir)', as
3868 it causes confusing behavior for users: if you are in the Top node and
3869 hit <DEL> to go backwards, you wind up in the middle of some other
3870 entry in the `dir' file, which has nothing to do with what you were
3873 *Note Install an Info File::, for more information about installing
3874 an Info file in the `info' directory.
3877 File: texinfo.info, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node
3879 The `@top' Sectioning Command
3880 -----------------------------
3882 A special sectioning command, `@top', has been created for use with the
3883 `@node Top' line. The `@top' sectioning command tells `makeinfo' that
3884 it marks the `Top' node in the file. It provides the information that
3885 `makeinfo' needs to insert node pointers automatically. Write the
3886 `@top' command at the beginning of the line immediately following the
3887 `@node Top' line. Write the title on the remaining part of the same
3888 line as the `@top' command.
3890 In Info, the `@top' sectioning command causes the title to appear on a
3891 line by itself, with a line of asterisks inserted underneath.
3893 In TeX and `texinfo-format-buffer', the `@top' sectioning command is
3894 merely a synonym for `@unnumbered'. Neither of these formatters
3895 require an `@top' command, and do nothing special with it. You can use
3896 `@chapter' or `@unnumbered' after the `@node Top' line when you use
3897 these formatters. Also, you can use `@chapter' or `@unnumbered' when
3898 you use the Texinfo updating commands to create or update pointers and
3902 File: texinfo.info, Node: Top Node Summary, Prev: makeinfo top command, Up: node
3904 The `Top' Node Summary
3905 ----------------------
3907 You can help readers by writing a summary in the `Top' node, after the
3908 `@top' line, before the main or master menu. The summary should
3909 briefly describe the document. In Info, this summary will appear just
3910 before the master menu. In a printed manual, this summary will appear
3911 on a page of its own.
3913 If you do not want the summary to appear on a page of its own in a
3914 printed manual, you can enclose the whole of the `Top' node, including
3915 the `@node Top' line and the `@top' sectioning command line or other
3916 sectioning command line between `@ifinfo' and `@end ifinfo'. This
3917 prevents any of the text from appearing in the printed output. (*note
3918 Conditionally Visible Text: Conditionals.). You can repeat the brief
3919 description from the `Top' node within `@iftex' ... `@end iftex' at the
3920 beginning of the first chapter, for those who read the printed manual.
3921 This saves paper and may look neater.
3923 You should write the version number of the program to which the manual
3924 applies in the summary. This helps the reader keep track of which
3925 manual is for which version of the program. If the manual changes more
3926 frequently than the program or is independent of it, you should also
3927 include an edition number for the manual. (The title page should also
3928 contain this information: see *Note `@titlepage': titlepage.)
3931 File: texinfo.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes
3933 Creating Pointers with `makeinfo'
3934 =================================
3936 The `makeinfo' program has a feature for automatically creating node
3937 pointers for a hierarchically organized file that lacks them.
3939 When you take advantage of this feature, you do not need to write the
3940 `Next', `Previous', and `Up' pointers after the name of a node.
3941 However, you must write a sectioning command, such as `@chapter' or
3942 `@section', on the line immediately following each truncated `@node'
3943 line. You cannot write a comment line after a node line; the section
3944 line must follow it immediately.
3946 In addition, you must follow the `Top' `@node' line with a line
3947 beginning with `@top' to mark the `Top' node in the file. *Note `@top':
3950 Finally, you must write the name of each node (except for the `Top'
3951 node) in a menu that is one or more hierarchical levels above the
3952 node's hierarchical level.
3954 This node pointer insertion feature in `makeinfo' is an alternative
3955 to the menu and pointer creation and update commands in Texinfo mode.
3956 (*Note Updating Nodes and Menus::.) It is especially helpful to people
3957 who do not use GNU Emacs for writing Texinfo documents.
3960 File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top
3965 "Menus" contain pointers to subordinate nodes.(1) (*note
3966 Menus-Footnote-1::) In Info, you use menus to go to such nodes. Menus
3967 have no effect in printed manuals and do not appear in them.
3969 By convention, a menu is put at the end of a node since a reader who
3970 uses the menu may not see text that follows it.
3972 A node that has a menu should _not_ contain much text. If you have a
3973 lot of text and a menu, move most of the text into a new subnode--all
3978 * Menu Location:: Put a menu in a short node.
3979 * Writing a Menu:: What is a menu?
3980 * Menu Parts:: A menu entry has three parts.
3981 * Less Cluttered Menu Entry:: Two part menu entry.
3982 * Menu Example:: Two and three part menu entries.
3983 * Other Info Files:: How to refer to a different Info file.
3986 File: texinfo.info, Node: Menus-Footnotes, Up: Menus
3988 (1) Menus can carry you to any node, regardless of the hierarchical
3989 structure; even to nodes in a different Info file. However, the GNU
3990 Emacs Texinfo mode updating commands work only to create menus of
3991 subordinate nodes. Conventionally, cross references are used to refer
3995 File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Prev: Menus, Up: Menus
3997 Menus Need Short Nodes
3998 ======================
4000 A reader can easily see a menu that is close to the beginning of the
4001 node. The node should be short. As a practical matter, you should
4002 locate a menu within 20 lines of the beginning of the node. Otherwise,
4003 a reader with a terminal that displays only a few lines may miss the
4004 menu and its associated text.
4006 The short text before a menu may look awkward in a printed manual. To
4007 avoid this, you can write a menu near the beginning of its node and
4008 follow the menu by an `@node' line, and then an `@heading' line located
4009 within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line,
4010 and title appear only in the Info file, not the printed document.
4012 For example, the preceding two paragraphs follow an Info-only menu,
4013 `@node' line, and heading, and look like this:
4016 * Menu Location:: Put a menu in a short node.
4017 * Writing a Menu:: What is a menu?
4018 * Menu Parts:: A menu entry has three parts.
4019 * Less Cluttered Menu Entry:: Two part menu entry.
4020 * Menu Example:: Two and three part entries.
4021 * Other Info Files:: How to refer to a different
4025 @node Menu Location, Writing a Menu, , Menus
4027 @heading Menus Need Short Nodes
4030 The Texinfo file for this document contains more than a dozen
4031 examples of this procedure. One is at the beginning of this chapter;
4032 another is at the beginning of the "Cross References" chapter.
4035 File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus
4040 A menu consists of an `@menu' command on a line by itself followed by
4041 menu entry lines or menu comment lines and then by an `@end menu'
4042 command on a line by itself.
4044 A menu looks like this:
4047 Larger Units of Text
4049 * Files:: All about handling files.
4050 * Multiples: Buffers. Multiple buffers; editing
4051 several files at once.
4054 In a menu, every line that begins with an `* ' is a "menu entry".
4055 (Note the space after the asterisk.) A line that does not start with
4056 an `* ' may also appear in a menu. Such a line is not a menu entry but
4057 is a menu comment line that appears in the Info file. In the example
4058 above, the line `Larger Units of Text' is a menu comment line; the two
4059 lines starting with `* ' are menu entries.
4062 File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus
4067 A menu entry has three parts, only the second of which is required:
4069 1. The menu entry name (optional).
4071 2. The name of the node (required).
4073 3. A description of the item (optional).
4075 The template for a menu entry looks like this:
4077 * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION
4079 Follow the menu entry name with a single colon and follow the node
4080 name with tab, comma, period, or newline.
4082 In Info, a user selects a node with the `m' (`Info-menu') command.
4083 The menu entry name is what the user types after the `m' command.
4085 The third part of a menu entry is a descriptive phrase or sentence.
4086 Menu entry names and node names are often short; the description
4087 explains to the reader what the node is about. A useful description
4088 complements the node name rather than repeats it. The description,
4089 which is optional, can spread over two or more lines; if it does, some
4090 authors prefer to indent the second line while others prefer to align it
4091 with the first (and all others). It's up to you.
4094 File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus
4096 Less Cluttered Menu Entry
4097 =========================
4099 When the menu entry name and node name are the same, you can write the
4100 name immediately after the asterisk and space at the beginning of the
4101 line and follow the name with two colons.
4105 * Name:: DESCRIPTION
4109 * Name: Name. DESCRIPTION
4111 You should use the node name for the menu entry name whenever
4112 possible, since it reduces visual clutter in the menu.
4115 File: texinfo.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus
4120 A menu looks like this in Texinfo:
4123 * menu entry name: Node name. A short description.
4124 * Node name:: This form is preferred.
4131 * menu entry name: Node name. A short description.
4132 * Node name:: This form is preferred.
4134 Here is an example as you might see it in a Texinfo file:
4137 Larger Units of Text
4139 * Files:: All about handling files.
4140 * Multiples: Buffers. Multiple buffers; editing
4141 several files at once.
4147 Larger Units of Text
4149 * Files:: All about handling files.
4150 * Multiples: Buffers. Multiple buffers; editing
4151 several files at once.
4153 In this example, the menu has two entries. `Files' is both a menu
4154 entry name and the name of the node referred to by that name.
4155 `Multiples' is the menu entry name; it refers to the node named
4156 `Buffers'. The line `Larger Units of Text' is a comment; it appears in
4157 the menu, but is not an entry.
4159 Since no file name is specified with either `Files' or `Buffers',
4160 they must be the names of nodes in the same Info file (*note Referring
4161 to Other Info Files: Other Info Files.).
4164 File: texinfo.info, Node: Other Info Files, Prev: Menu Example, Up: Menus
4166 Referring to Other Info Files
4167 =============================
4169 You can create a menu entry that enables a reader in Info to go to a
4170 node in another Info file by writing the file name in parentheses just
4171 before the node name. In this case, you should use the three-part menu
4172 entry format, which saves the reader from having to type the file name.
4174 The format looks like this:
4177 * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION
4178 * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
4181 For example, to refer directly to the `Outlining' and `Rebinding'
4182 nodes in the `XEmacs User's Manual', you would write a menu like this:
4185 * Outlining: (xemacs)Outline Mode. The major mode for
4187 * Rebinding: (xemacs)Rebinding. How to redefine the
4191 If you do not list the node name, but only name the file, then Info
4192 presumes that you are referring to the `Top' node.
4194 The `dir' file that contains the main menu for Info has menu entries
4195 that list only file names. These take you directly to the `Top' nodes
4196 of each Info document. (*Note Install an Info File::.)
4200 * Info: (info). Documentation browsing system.
4201 * Emacs: (emacs). The extensible, self-documenting
4204 (The `dir' top level directory for the Info system is an Info file, not
4205 a Texinfo file, but a menu entry looks the same in both types of file.)
4207 Note that the GNU Emacs Texinfo mode menu updating commands only work
4208 with nodes within the current buffer, so you cannot use them to create
4209 menus that refer to other files. You must write such menus by hand.
4212 File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top
4217 "Cross references" are used to refer the reader to other parts of the
4218 same or different Texinfo files. In Texinfo, nodes are the places to
4219 which cross references can refer.
4223 * References:: What cross references are for.
4224 * Cross Reference Commands:: A summary of the different commands.
4225 * Cross Reference Parts:: A cross reference has several parts.
4226 * xref:: Begin a reference with `See' ...
4227 * Top Node Naming:: How to refer to the beginning of another file.
4228 * ref:: A reference for the last part of a sentence.
4229 * pxref:: How to write a parenthetical cross reference.
4230 * inforef:: How to refer to an Info-only file.
4231 * uref:: How to refer to a uniform resource locator.
4234 File: texinfo.info, Node: References, Next: Cross Reference Commands, Prev: Cross References, Up: Cross References
4236 What References Are For
4237 =======================
4239 Often, but not always, a printed document should be designed so that
4240 it can be read sequentially. People tire of flipping back and forth to
4241 find information that should be presented to them as they need it.
4243 However, in any document, some information will be too detailed for
4244 the current context, or incidental to it; use cross references to
4245 provide access to such information. Also, an on-line help system or a
4246 reference manual is not like a novel; few read such documents in
4247 sequence from beginning to end. Instead, people look up what they
4248 need. For this reason, such creations should contain many cross
4249 references to help readers find other information that they may not
4252 In a printed manual, a cross reference results in a page reference,
4253 unless it is to another manual altogether, in which case the cross
4254 reference names that manual.
4256 In Info, a cross reference results in an entry that you can follow
4257 using the Info `f' command. (*note Some advanced Info commands:
4260 The various cross reference commands use nodes to define cross
4261 reference locations. This is evident in Info, in which a cross
4262 reference takes you to the specified node. TeX also uses nodes to
4263 define cross reference locations, but the action is less obvious. When
4264 TeX generates a DVI file, it records nodes' page numbers and uses the
4265 page numbers in making references. Thus, if you are writing a manual
4266 that will only be printed, and will not be used on-line, you must
4267 nonetheless write `@node' lines to name the places to which you make
4271 File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References
4273 Different Cross Reference Commands
4274 ==================================
4276 There are four different cross reference commands:
4279 Used to start a sentence in the printed manual saying `See ...'
4280 or an Info cross-reference saying `*Note NAME: NODE.'.
4283 Used within or, more often, at the end of a sentence; same as
4284 `@xref' for Info; produces just the reference in the printed
4285 manual without a preceding `See'.
4288 Used within parentheses to make a reference that suits both an Info
4289 file and a printed book. Starts with a lower case `see' within the
4290 printed manual. (`p' is for `parenthesis'.)
4293 Used to make a reference to an Info file for which there is no
4296 (The `@cite' command is used to make references to books and manuals
4297 for which there is no corresponding Info file and, therefore, no node
4298 to which to point. *Note `@cite': cite.)
4301 File: texinfo.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References
4303 Parts of a Cross Reference
4304 ==========================
4306 A cross reference command requires only one argument, which is the name
4307 of the node to which it refers. But a cross reference command may
4308 contain up to four additional arguments. By using these arguments, you
4309 can provide a cross reference name for Info, a topic description or
4310 section title for the printed output, the name of a different Info
4311 file, and the name of a different printed manual.
4313 Here is a simple cross reference example:
4323 See Section NNN [Node name], page PPP.
4325 Here is an example of a full five-part cross reference:
4327 @xref{Node name, Cross Reference Name, Particular Topic,
4328 info-file-name, A Printed Manual}, for details.
4332 *Note Cross Reference Name: (info-file-name)Node name,
4337 See section "Particular Topic" in A Printed Manual, for details.
4341 The five possible arguments for a cross reference are:
4343 1. The node name (required). This is the node to which the cross
4344 reference takes you. In a printed document, the location of the
4345 node provides the page reference only for references within the
4348 2. The cross reference name for the Info reference, if it is to be
4349 different from the node name. If you include this argument, it
4350 becomes the first part of the cross reference. It is usually
4353 3. A topic description or section name. Often, this is the title of
4354 the section. This is used as the name of the reference in the
4355 printed manual. If omitted, the node name is used.
4357 4. The name of the Info file in which the reference is located, if it
4358 is different from the current file. You need not include any
4359 `.info' suffix on the file name, since Info readers try appending
4362 5. The name of a printed manual from a different Texinfo file.
4364 The template for a full five argument cross reference looks like this:
4366 @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
4367 INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
4369 Cross references with one, two, three, four, and five arguments are
4370 described separately following the description of `@xref'.
4372 Write a node name in a cross reference in exactly the same way as in
4373 the `@node' line, including the same capitalization; otherwise, the
4374 formatters may not find the reference.
4376 You can write cross reference commands within a paragraph, but note
4377 how Info and TeX format the output of each of the various commands:
4378 write `@xref' at the beginning of a sentence; write `@pxref' only
4379 within parentheses, and so on.
4382 File: texinfo.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References
4387 The `@xref' command generates a cross reference for the beginning of a
4388 sentence. The Info formatting commands convert it into an Info cross
4389 reference, which the Info `f' command can use to bring you directly to
4390 another node. The TeX typesetting commands convert it into a page
4391 reference, or a reference to another book or manual.
4395 * Reference Syntax:: What a reference looks like and requires.
4396 * One Argument:: `@xref' with one argument.
4397 * Two Arguments:: `@xref' with two arguments.
4398 * Three Arguments:: `@xref' with three arguments.
4399 * Four and Five Arguments:: `@xref' with four and five arguments.
4402 File: texinfo.info, Node: Reference Syntax, Next: One Argument, Prev: xref, Up: xref
4404 What a Reference Looks Like and Requires
4405 ----------------------------------------
4407 Most often, an Info cross reference looks like this:
4413 *Note CROSS-REFERENCE-NAME: NODE-NAME.
4415 In TeX, a cross reference looks like this:
4417 See Section SECTION-NUMBER [NODE-NAME], page PAGE.
4421 See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
4423 The `@xref' command does not generate a period or comma to end the
4424 cross reference in either the Info file or the printed output. You
4425 must write that period or comma yourself; otherwise, Info will not
4426 recognize the end of the reference. (The `@pxref' command works
4427 differently. *Note `@pxref': pxref.)
4429 *Please note:* A period or comma *must* follow the closing brace
4430 of an `@xref'. It is required to terminate the cross reference.
4431 This period or comma will appear in the output, both in the Info
4432 file and in the printed manual.
4434 `@xref' must refer to an Info node by name. Use `@node' to define
4435 the node (*note Writing a Node::).
4437 `@xref' is followed by several arguments inside braces, separated by
4438 commas. Whitespace before and after these commas is ignored.
4440 A cross reference requires only the name of a node; but it may contain
4441 up to four additional arguments. Each of these variations produces a
4442 cross reference that looks somewhat different.
4444 *Please note:* Commas separate arguments in a cross reference;
4445 avoid including them in the title or other part lest the formatters
4446 mistake them for separators.
4449 File: texinfo.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref
4451 `@xref' with One Argument
4452 -------------------------
4454 The simplest form of `@xref' takes one argument, the name of another
4455 node in the same Info file. The Info formatters produce output that
4456 the Info readers can use to jump to the reference; TeX produces output
4457 that specifies the page and section number for you.
4461 @xref{Tropical Storms}.
4465 *Note Tropical Storms::.
4469 See Section 3.1 [Tropical Storms], page 24.
4471 (Note that in the preceding example the closing brace is followed by a
4474 You can write a clause after the cross reference, like this:
4476 @xref{Tropical Storms}, for more info.
4480 *Note Tropical Storms::, for more info.
4482 See Section 3.1 [Tropical Storms], page 24, for more info.
4484 (Note that in the preceding example the closing brace is followed by a
4485 comma, and then by the clause, which is followed by a period.)
4488 File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref
4490 `@xref' with Two Arguments
4491 --------------------------
4493 With two arguments, the second is used as the name of the Info cross
4494 reference, while the first is still the name of the node to which the
4495 cross reference points.
4497 The template is like this:
4499 @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
4503 @xref{Electrical Effects, Lightning}.
4507 *Note Lightning: Electrical Effects.
4511 See Section 5.2 [Electrical Effects], page 57.
4513 (Note that in the preceding example the closing brace is followed by a
4514 period; and that the node name is printed, not the cross reference
4517 You can write a clause after the cross reference, like this:
4519 @xref{Electrical Effects, Lightning}, for more info.
4522 *Note Lightning: Electrical Effects, for more info.
4526 See Section 5.2 [Electrical Effects], page 57, for more info.
4528 (Note that in the preceding example the closing brace is followed by a
4529 comma, and then by the clause, which is followed by a period.)
4532 File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref
4534 `@xref' with Three Arguments
4535 ----------------------------
4537 A third argument replaces the node name in the TeX output. The third
4538 argument should be the name of the section in the printed output, or
4539 else state the topic discussed by that section. Often, you will want to
4540 use initial upper case letters so it will be easier to read when the
4541 reference is printed. Use a third argument when the node name is
4542 unsuitable because of syntax or meaning.
4544 Remember to avoid placing a comma within the title or topic section of
4545 a cross reference, or within any other section. The formatters divide
4546 cross references into arguments according to the commas; a comma within
4547 a title or other section will divide it into two arguments. In a
4548 reference, you need to write a title such as "Clouds, Mist, and Fog"
4551 Also, remember to write a comma or period after the closing brace of a
4552 `@xref' to terminate the cross reference. In the following examples, a
4553 clause follows a terminating comma.
4555 The template is like this:
4557 @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
4561 @xref{Electrical Effects, Lightning, Thunder and Lightning},
4566 *Note Lightning: Electrical Effects, for details.
4570 See Section 5.2 [Thunder and Lightning], page 57, for details.
4572 If a third argument is given and the second one is empty, then the
4573 third argument serves both. (Note how two commas, side by side, mark
4574 the empty second argument.)
4576 @xref{Electrical Effects, , Thunder and Lightning},
4581 *Note Thunder and Lightning: Electrical Effects, for details.
4585 See Section 5.2 [Thunder and Lightning], page 57, for details.
4587 As a practical matter, it is often best to write cross references with
4588 just the first argument if the node name and the section title are the
4589 same, and with the first and third arguments if the node name and title
4592 Here are several examples from `The GNU Awk User's Guide':
4594 @xref{Sample Program}.
4596 @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
4597 @xref{Close Output, , Closing Output Files and Pipes},
4598 for more information.
4599 @xref{Regexp, , Regular Expressions as Patterns}.
4602 File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref
4604 `@xref' with Four and Five Arguments
4605 ------------------------------------
4607 In a cross reference, a fourth argument specifies the name of another
4608 Info file, different from the file in which the reference appears, and
4609 a fifth argument specifies its title as a printed manual.
4611 Remember that a comma or period must follow the closing brace of an
4612 `@xref' command to terminate the cross reference. In the following
4613 examples, a clause follows a terminating comma.
4617 @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
4618 INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
4622 @xref{Electrical Effects, Lightning, Thunder and Lightning,
4623 weather, An Introduction to Meteorology}, for details.
4627 *Note Lightning: (weather)Electrical Effects, for details.
4629 The name of the Info file is enclosed in parentheses and precedes the
4632 In a printed manual, the reference looks like this:
4634 See section "Thunder and Lightning" in An Introduction to
4635 Meteorology, for details.
4637 The title of the printed manual is typeset in italics; and the
4638 reference lacks a page number since TeX cannot know to which page a
4639 reference refers when that reference is to another manual.
4641 Often, you will leave out the second argument when you use the long
4642 version of `@xref'. In this case, the third argument, the topic
4643 description, will be used as the cross reference name in Info.
4645 The template looks like this:
4647 @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
4648 PRINTED-MANUAL-TITLE}, for details.
4652 *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
4656 See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
4660 @xref{Electrical Effects, , Thunder and Lightning,
4661 weather, An Introduction to Meteorology}, for details.
4665 *Note Thunder and Lightning: (weather)Electrical Effects,
4670 See section "Thunder and Lightning" in An Introduction to
4671 Meteorology, for details.
4673 On rare occasions, you may want to refer to another Info file that is
4674 within a single printed manual--when multiple Texinfo files are
4675 incorporated into the same TeX run but make separate Info files. In
4676 this case, you need to specify only the fourth argument, and not the
4680 File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References
4685 In a cross reference, you must always name a node. This means that in
4686 order to refer to a whole manual, you must identify the `Top' node by
4687 writing it as the first argument to the `@xref' command. (This is
4688 different from the way you write a menu entry; see *Note Referring to
4689 Other Info Files: Other Info Files.) At the same time, to provide a
4690 meaningful section topic or title in the printed cross reference
4691 (instead of the word `Top'), you must write an appropriate entry for
4692 the third argument to the `@xref' command.
4694 Thus, to make a cross reference to `The GNU Make Manual', write:
4696 @xref{Top, , Overview, make, The GNU Make Manual}.
4700 *Note Overview: (make)Top.
4704 See section "Overview" in The GNU Make Manual.
4706 In this example, `Top' is the name of the first node, and `Overview' is
4707 the name of the first section of the manual.
4710 File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References
4715 `@ref' is nearly the same as `@xref' except that it does not generate a
4716 `See' in the printed output, just the reference itself. This makes it
4717 useful as the last part of a sentence.
4721 For more information, see @ref{Hurricanes}.
4725 For more information, see *Note Hurricanes::.
4729 For more information, see Section 8.2 [Hurricanes], page 123.
4731 The `@ref' command sometimes leads writers to express themselves in a
4732 manner that is suitable for a printed manual but looks awkward in the
4733 Info format. Bear in mind that your audience will be using both the
4734 printed and the Info format.
4738 Sea surges are described in @ref{Hurricanes}.
4742 Sea surges are described in Section 6.7 [Hurricanes], page 72.
4744 in a printed document, and the following in Info:
4746 Sea surges are described in *Note Hurricanes::.
4748 *Caution:* You _must_ write a period or comma immediately after an
4749 `@ref' command with two or more arguments. Otherwise, Info will
4750 not find the end of the cross reference entry and its attempt to
4751 follow the cross reference will fail. As a general rule, you
4752 should write a period or comma after every `@ref' command. This
4753 looks best in both the printed and the Info output.
4756 File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References
4761 The parenthetical reference command, `@pxref', is nearly the same as
4762 `@xref', but you use it _only_ inside parentheses and you do _not_ type
4763 a comma or period after the command's closing brace. The command
4764 differs from `@xref' in two ways:
4766 1. TeX typesets the reference for the printed manual with a lower case
4767 `see' rather than an upper case `See'.
4769 2. The Info formatting commands automatically end the reference with a
4770 closing colon or period.
4772 Because one type of formatting automatically inserts closing
4773 punctuation and the other does not, you should use `@pxref' _only_
4774 inside parentheses as part of another sentence. Also, you yourself
4775 should not insert punctuation after the reference, as you do with
4778 `@pxref' is designed so that the output looks right and works right
4779 between parentheses both in printed output and in an Info file. In a
4780 printed manual, a closing comma or period should not follow a cross
4781 reference within parentheses; such punctuation is wrong. But in an
4782 Info file, suitable closing punctuation must follow the cross reference
4783 so Info can recognize its end. `@pxref' spares you the need to use
4784 complicated methods to put a terminator into one form of the output and
4787 With one argument, a parenthetical cross reference looks like this:
4789 ... storms cause flooding (@pxref{Hurricanes}) ...
4793 ... storms cause flooding (*Note Hurricanes::) ...
4797 ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
4800 With two arguments, a parenthetical cross reference has this template:
4802 ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
4806 ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
4810 ... (see Section NNN [NODE-NAME], page PPP) ...
4812 `@pxref' can be used with up to five arguments just like `@xref'
4813 (*note `@xref': xref.).
4815 *Please note:* Use `@pxref' only as a parenthetical reference. Do
4816 not try to use `@pxref' as a clause in a sentence. It will look
4817 bad in either the Info file, the printed output, or both.
4819 Also, parenthetical cross references look best at the ends of
4820 sentences. Although you may write them in the middle of a
4821 sentence, that location breaks up the flow of text.
4824 File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References
4829 `@inforef' is used for cross references to Info files for which there
4830 are no printed manuals. Even in a printed manual, `@inforef' generates
4831 a reference directing the user to look in an Info file.
4833 The command takes either two or three arguments, in the following
4838 2. The cross reference name (optional).
4840 3. The Info file name.
4842 Separate the arguments with commas, as with `@xref'. Also, you must
4843 terminate the reference with a comma or period after the `}', as you do
4848 @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
4852 @inforef{Expert, Advanced Info commands, info},
4853 for more information.
4857 *Note Advanced Info commands: (info)Expert,
4858 for more information.
4862 See Info file `info', node `Expert', for more information.
4866 @inforef{Expert, , info}, for more information.
4870 *Note (info)Expert::, for more information.
4874 See Info file `info', node `Expert', for more information.
4876 The converse of `@inforef' is `@cite', which is used to refer to
4877 printed works for which no Info form exists. *Note `@cite': cite.
4880 File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References
4882 `@uref{URL[, DISPLAYED-TEXT]}'
4883 ==============================
4885 `@uref' produces a reference to a uniform resource locator (URL). It
4886 takes one mandatory argument, the URL, and one optional argument, the
4887 text to display (the default is the URL itself). In HTML output,
4888 `@uref' produces a link you can follow. For example:
4890 The official GNU ftp site is
4891 @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
4894 The official GNU ftp site is
4895 `ftp://ftp.gnu.ai.mit.edu/pub/gnu'
4899 @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
4900 GNU ftp site} holds programs and texts.
4903 The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds
4907 The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
4908 site</A> holds programs and texts.
4910 To merely indicate a URL, use `@url' (*note `@url': url.).
4913 File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top
4915 Marking Words and Phrases
4916 *************************
4918 In Texinfo, you can mark words and phrases in a variety of ways. The
4919 Texinfo formatters use this information to determine how to highlight
4920 the text. You can specify, for example, whether a word or phrase is a
4921 defining occurrence, a metasyntactic variable, or a symbol used in a
4922 program. Also, you can emphasize text.
4926 * Indicating:: How to indicate definitions, files, etc.
4927 * Emphasis:: How to emphasize text.
4930 File: texinfo.info, Node: Indicating, Next: Emphasis, Prev: Marking Text, Up: Marking Text
4932 Indicating Definitions, Commands, etc.
4933 ======================================
4935 Texinfo has commands for indicating just what kind of object a piece of
4936 text refers to. For example, metasyntactic variables are marked by
4937 `@var', and code by `@code'. Since the pieces of text are labelled by
4938 commands that tell what kind of object they are, it is easy to change
4939 the way the Texinfo formatters prepare such text. (Texinfo is an
4940 _intentional_ formatting language rather than a _typesetting_
4941 formatting language.)
4943 For example, in a printed manual, code is usually illustrated in a
4944 typewriter font; `@code' tells TeX to typeset this text in this font.
4945 But it would be easy to change the way TeX highlights code to use
4946 another font, and this change would not effect how keystroke examples
4947 are highlighted. If straight typesetting commands were used in the body
4948 of the file and you wanted to make a change, you would need to check
4949 every single occurrence to make sure that you were changing code and
4950 not something else that should not be changed.
4954 * Useful Highlighting:: Highlighting provides useful information.
4955 * code:: How to indicate code.
4956 * kbd:: How to show keyboard input.
4957 * key:: How to specify keys.
4958 * samp:: How to show a literal sequence of characters.
4959 * var:: How to indicate a metasyntactic variable.
4960 * file:: How to indicate the name of a file.
4961 * dfn:: How to specify a definition.
4962 * cite:: How to refer to a book that is not in Info.
4963 * url:: How to indicate a world wide web reference.
4964 * email:: How to indicate an electronic mail address.
4967 File: texinfo.info, Node: Useful Highlighting, Next: code, Prev: Indicating, Up: Indicating
4969 Highlighting Commands are Useful
4970 --------------------------------
4972 The highlighting commands can be used to generate useful information
4973 from the file, such as lists of functions or file names. It is
4974 possible, for example, to write a program in Emacs Lisp (or a keyboard
4975 macro) to insert an index entry after every paragraph that contains
4976 words or phrases marked by a specified command. You could do this to
4977 construct an index of functions if you had not already made the entries.
4979 The commands serve a variety of purposes:
4981 `@code{SAMPLE-CODE}'
4982 Indicate text that is a literal example of a piece of a program.
4984 `@kbd{KEYBOARD-CHARACTERS}'
4985 Indicate keyboard input.
4988 Indicate the conventional name for a key on a keyboard.
4991 Indicate text that is a literal example of a sequence of
4994 `@var{METASYNTACTIC-VARIABLE}'
4995 Indicate a metasyntactic variable.
4997 `@url{UNIFORM-RESOURCE-LOCATOR}'
4998 Indicate a uniform resource locator for the World Wide Web.
5001 Indicate the name of a file.
5003 `@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
5004 Indicate an electronic mail address.
5007 Indicate the introductory or defining use of a term.
5010 Indicate the name of a book.
5014 File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating
5016 `@code'{SAMPLE-CODE}
5017 --------------------
5019 Use the `@code' command to indicate text that is a piece of a program
5020 and which consists of entire syntactic tokens. Enclose the text in
5023 Thus, you should use `@code' for an expression in a program, for the
5024 name of a variable or function used in a program, or for a keyword.
5025 Also, you should use `@code' for the name of a program, such as `diff',
5026 that is a name used in the machine. (You should write the name of a
5027 program in the ordinary text font if you regard it as a new English
5028 word, such as `Emacs' or `Bison'.)
5030 Use `@code' for environment variables such as `TEXINPUTS', and other
5033 Use `@code' for command names in command languages that resemble
5034 programming languages, such as Texinfo or the shell. For example,
5035 `@code' and `@samp' are produced by writing `@code{@@code}' and
5036 `@code{@@samp}' in the Texinfo source, respectively.
5038 Note, however, that you should not use `@code' for shell options such
5039 as `-c' when such options stand alone. (Use `@samp'.) Also, an entire
5040 shell command often looks better if written using `@samp' rather than
5041 `@code'. In this case, the rule is to choose the more pleasing format.
5043 It is incorrect to alter the case of a word inside an `@code' command
5044 when it appears at the beginning of a sentence. Most computer
5045 languages are case sensitive. In C, for example, `Printf' is different
5046 from the identifier `printf', and most likely is a misspelling of it.
5047 Even in languages which are not case sensitive, it is confusing to a
5048 human reader to see identifiers spelled in different ways. Pick one
5049 spelling and always use that. If you do not want to start a sentence
5050 with a command written all in lower case, you should rearrange the
5053 Do not use the `@code' command for a string of characters shorter
5054 than a syntactic token. If you are writing about `TEXINPU', which is
5055 just a part of the name for the `TEXINPUTS' environment variable, you
5058 In particular, you should not use the `@code' command when writing
5059 about the characters used in a token; do not, for example, use `@code'
5060 when you are explaining what letters or printable symbols can be used
5061 in the names of functions. (Use `@samp'.) Also, you should not use
5062 `@code' to mark text that is considered input to programs unless the
5063 input is written in a language that is like a programming language.
5064 For example, you should not use `@code' for the keystroke commands of
5065 GNU Emacs (use `@kbd' instead) although you may use `@code' for the
5066 names of the Emacs Lisp functions that the keystroke commands invoke.
5068 In the printed manual, `@code' causes TeX to typeset the argument in
5069 a typewriter face. In the Info file, it causes the Info formatting
5070 commands to use single quotation marks around the text.
5074 Use @code{diff} to compare two files.
5076 produces this in the printed manual:
5078 Use `diff' to compare two files.
5081 File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating
5083 `@kbd'{KEYBOARD-CHARACTERS}
5084 ---------------------------
5086 Use the `@kbd' command for characters of input to be typed by users.
5087 For example, to refer to the characters `M-a', write
5091 and to refer to the characters `M-x shell', write
5095 The `@kbd' command has the same effect as `@code' in Info, but by
5096 default produces a different font (slanted typewriter instead of normal
5097 typewriter) in the printed manual, so users can distinguish the
5098 characters they are supposed to type from those the computer outputs.
5100 Since the usage of `@kbd' varies from manual to manual, you can
5101 control the font switching with the `@kbdinputstyle' command. This
5102 command has no effect on Info output. Write this command at the
5103 beginning of a line with a single word as an argument, one of the
5106 Always use the same font for `@kbd' as `@code'.
5109 Use the distinguishing font for `@kbd' only in `@example' and
5110 similar environments.
5113 (the default) Always use the distinguishing font for `@kbd'.
5115 You can embed another @-command inside the braces of an `@kbd'
5116 command. Here, for example, is the way to describe a command that
5117 would be described more verbosely as "press an `r' and then press the
5122 This produces: `r <RET>'
5124 You also use the `@kbd' command if you are spelling out the letters
5125 you type; for example:
5127 To give the @code{logout} command,
5128 type the characters @kbd{l o g o u t @key{RET}}.
5132 To give the `logout' command, type the characters `l o g o u t
5135 (Also, this example shows that you can add spaces for clarity. If you
5136 really want to mention a space character as one of the characters of
5137 input, write `@key{SPC}' for it.)
5140 File: texinfo.info, Node: key, Next: samp, Prev: kbd, Up: Indicating
5145 Use the `@key' command for the conventional name for a key on a
5150 You can use the `@key' command within the argument of an `@kbd'
5151 command when the sequence of characters to be typed includes one or
5152 more keys that are described by name.
5154 For example, to produce `C-x <ESC>' you would type:
5158 Here is a list of the recommended names for keys:
5167 Linefeed (however, since most keyboards nowadays do not have
5168 a Linefeed key, it might be better to call this character
5192 There are subtleties to handling words like `meta' or `ctrl' that are
5193 names of modifier keys. When mentioning a character in which the
5194 modifier key is used, such as `Meta-a', use the `@kbd' command alone;
5195 do not use the `@key' command; but when you are referring to the
5196 modifier key in isolation, use the `@key' command. For example, write
5197 `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.
5200 File: texinfo.info, Node: samp, Next: var, Prev: key, Up: Indicating
5205 Use the `@samp' command to indicate text that is a literal example or
5206 `sample' of a sequence of characters in a file, string, pattern, etc.
5207 Enclose the text in braces. The argument appears within single
5208 quotation marks in both the Info file and the printed manual; in
5209 addition, it is printed in a fixed-width font.
5211 To match @samp{foo} at the end of the line,
5212 use the regexp @samp{foo$}.
5216 To match `foo' at the end of the line, use the regexp `foo$'.
5218 Any time you are referring to single characters, you should use
5219 `@samp' unless `@kbd' or `@key' is more appropriate. Use `@samp' for
5220 the names of command-line options (except in an `@table', where `@code'
5221 seems to read more easily). Also, you may use `@samp' for entire
5222 statements in C and for entire shell commands--in this case, `@samp'
5223 often looks better than `@code'. Basically, `@samp' is a catchall for
5224 whatever is not covered by `@code', `@kbd', or `@key'.
5226 Only include punctuation marks within braces if they are part of the
5227 string you are specifying. Write punctuation marks outside the braces
5228 if those punctuation marks are part of the English text that surrounds
5229 the string. In the following sentence, for example, the commas and
5230 period are outside of the braces:
5232 In English, the vowels are @samp{a}, @samp{e},
5233 @samp{i}, @samp{o}, @samp{u}, and sometimes
5238 In English, the vowels are `a', `e', `i', `o', `u', and sometimes
5242 File: texinfo.info, Node: var, Next: file, Prev: samp, Up: Indicating
5244 `@var'{METASYNTACTIC-VARIABLE}
5245 ------------------------------
5247 Use the `@var' command to indicate metasyntactic variables. A
5248 "metasyntactic variable" is something that stands for another piece of
5249 text. For example, you should use a metasyntactic variable in the
5250 documentation of a function to describe the arguments that are passed
5253 Do not use `@var' for the names of particular variables in
5254 programming languages. These are specific names from a program, so
5255 `@code' is correct for them. For example, the Emacs Lisp variable
5256 `texinfo-tex-command' is not a metasyntactic variable; it is properly
5257 formatted using `@code'.
5259 The effect of `@var' in the Info file is to change the case of the
5260 argument to all upper case; in the printed manual, to italicize it.
5264 To delete file @var{filename},
5265 type @code{rm @var{filename}}.
5269 To delete file FILENAME, type `rm FILENAME'.
5271 (Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
5273 Write a metasyntactic variable all in lower case without spaces, and
5274 use hyphens to make it more readable. Thus, the Texinfo source for the
5275 illustration of how to begin a Texinfo manual looks like this:
5278 @@setfilename @var{info-file-name}
5279 @@settitle @var{name-of-manual}
5284 @setfilename INFO-FILE-NAME
5285 @settitle NAME-OF-MANUAL
5287 In some documentation styles, metasyntactic variables are shown with
5288 angle brackets, for example:
5290 ..., type rm <filename>
5292 However, that is not the style that Texinfo uses. (You can, of course,
5293 modify the sources to TeX and the Info formatting commands to output
5294 the `<...>' format if you wish.)
5297 File: texinfo.info, Node: file, Next: dfn, Prev: var, Up: Indicating
5302 Use the `@file' command to indicate text that is the name of a file,
5303 buffer, or directory, or is the name of a node in Info. You can also
5304 use the command for file name suffixes. Do not use `@file' for symbols
5305 in a programming language; use `@code'.
5307 Currently, `@file' is equivalent to `@samp' in its effects. For
5310 The @file{.el} files are in
5311 the @file{/usr/local/emacs/lisp} directory.
5315 The `.el' files are in the `/usr/local/emacs/lisp' directory.
5318 File: texinfo.info, Node: dfn, Next: cite, Prev: file, Up: Indicating
5323 Use the `@dfn' command to identify the introductory or defining use of
5324 a technical term. Use the command only in passages whose purpose is to
5325 introduce a term which will be used again or which the reader ought to
5326 know. Mere passing mention of a term for the first time does not
5327 deserve `@dfn'. The command generates italics in the printed manual,
5328 and double quotation marks in the Info file. For example:
5330 Getting rid of a file is called @dfn{deleting} it.
5334 Getting rid of a file is called "deleting" it.
5336 As a general rule, a sentence containing the defining occurrence of a
5337 term should be a definition of the term. The sentence does not need to
5338 say explicitly that it is a definition, but it should contain the
5339 information of a definition--it should make the meaning clear.
5342 File: texinfo.info, Node: cite, Next: url, Prev: dfn, Up: Indicating
5347 Use the `@cite' command for the name of a book that lacks a companion
5348 Info file. The command produces italics in the printed manual, and
5349 quotation marks in the Info file.
5351 (If a book is written in Texinfo, it is better to use a cross
5352 reference command since a reader can easily follow such a reference in
5353 Info. *Note `@xref': xref.)
5356 File: texinfo.info, Node: url, Next: email, Prev: cite, Up: Indicating
5358 `@url'{UNIFORM-RESOURCE-LOCATOR}
5359 --------------------------------
5361 Use the `@url' to indicate a uniform resource locator on the World Wide
5362 Web. This is analogous to `@file', `@var', etc., and is purely for
5363 markup purposes. It does not produce a link you can follow in HTML
5364 output (the `@uref' command does, *note `@uref': uref.). It is useful
5365 for example URL's which do not actually exist. For example:
5367 For example, the url might be
5368 @url{http://host.domain.org/path}.
5371 File: texinfo.info, Node: email, Prev: url, Up: Indicating
5373 `@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
5374 -----------------------------------------
5376 Use the `@email' command to indicate an electronic mail address. It
5377 takes one mandatory argument, the address, and one optional argument,
5378 the text to display (the default is the address itself).
5380 In Info and TeX, the address is shown in angle brackets, preceded by
5381 the text to display if any. In HTML output, `@email' produces a
5382 `mailto' link that usually brings up a mail composition window. For
5385 Send bug reports to @email{bug-texinfo@@gnu.org}.
5386 Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
5389 Send bug reports to <bug-texinfo@gnu.org>.
5390 Send suggestions to the same place <bug-texinfo@gnu.org>.
5393 File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text
5398 Usually, Texinfo changes the font to mark words in the text according to
5399 what category the words belong to; an example is the `@code' command.
5400 Most often, this is the best way to mark words. However, sometimes you
5401 will want to emphasize text without indicating a category. Texinfo has
5402 two commands to do this. Also, Texinfo has several commands that
5403 specify the font in which TeX will typeset text. These commands have
5404 no affect on Info and only one of them, the `@r' command, has any
5409 * emph & strong:: How to emphasize text in Texinfo.
5410 * Smallcaps:: How to use the small caps font.
5411 * Fonts:: Various font commands for printed output.
5412 * Customized Highlighting:: How to define highlighting commands.
5415 File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, Up: Emphasis
5417 `@emph'{TEXT} and `@strong'{TEXT}
5418 ---------------------------------
5420 The `@emph' and `@strong' commands are for emphasis; `@strong' is
5421 stronger. In printed output, `@emph' produces _italics_ and `@strong'
5427 @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
5428 files in the directory.
5433 *Caution*: `rm * .[^.]*' removes *all*
5434 files in the directory.
5436 The `@strong' command is seldom used except to mark what is, in
5437 effect, a typographical element, such as the word `Caution' in the
5440 In the Info file, both `@emph' and `@strong' put asterisks around the
5443 *Caution:* Do not use `@emph' or `@strong' with the word `Note';
5444 Info will mistake the combination for a cross reference. Use a
5445 phrase such as *Please note* or *Caution* instead.
5448 File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis
5450 `@sc'{TEXT}: The Small Caps Font
5451 --------------------------------
5453 Use the `@sc' command to set text in the printed output in a small caps
5454 font and set text in the Info file in upper case letters.
5456 Write the text between braces in lower case, like this:
5458 The @sc{acm} and @sc{ieee} are technical societies.
5462 The ACM and IEEE are technical societies.
5464 TeX typesets the small caps font in a manner that prevents the
5465 letters from `jumping out at you on the page'. This makes small caps
5466 text easier to read than text in all upper case. The Info formatting
5467 commands set all small caps text in upper case.
5469 If the text between the braces of an `@sc' command is upper case, TeX
5470 typesets in full-size capitals. Use full-size capitals sparingly.
5472 You may also use the small caps font for a jargon word such as ATO (a
5473 NASA word meaning `abort to orbit').
5475 There are subtleties to using the small caps font with a jargon word
5476 such as CDR, a word used in Lisp programming. In this case, you should
5477 use the small caps font when the word refers to the second and
5478 subsequent elements of a list (the CDR of the list), but you should use
5479 `@code' when the word refers to the Lisp function of the same spelling.
5482 File: texinfo.info, Node: Fonts, Next: Customized Highlighting, Prev: Smallcaps, Up: Emphasis
5484 Fonts for Printing, Not Info
5485 ----------------------------
5487 Texinfo provides four font commands that specify font changes in the
5488 printed manual but have no effect in the Info file. `@i' requests
5489 italic font (in some versions of TeX, a slanted font is used), `@b'
5490 requests bold face, `@t' requests the fixed-width, typewriter-style
5491 font used by `@code', and `@r' requests a roman font, which is the
5492 usual font in which text is printed. All four commands apply to an
5493 argument that follows, surrounded by braces.
5495 Only the `@r' command has much use: in example programs, you can use
5496 the `@r' command to convert code comments from the fixed-width font to
5497 a roman font. This looks better in printed output.
5502 (+ 2 2) ; @r{Add two plus two.}
5507 (+ 2 2) ; Add two plus two.
5509 If possible, you should avoid using the other three font commands. If
5510 you need to use one, it probably indicates a gap in the Texinfo
5514 File: texinfo.info, Node: Customized Highlighting, Prev: Fonts, Up: Emphasis
5516 Customized Highlighting
5517 -----------------------
5519 You can use regular TeX commands inside of `@iftex' ... `@end iftex'
5520 to create your own customized highlighting commands for Texinfo. The
5521 easiest way to do this is to equate your customized commands with
5522 pre-existing commands, such as those for italics. Such new commands
5525 You can use the `@definfoenclose' command inside of `@ifinfo' ...
5526 `@end ifinfo' to define commands for Info with the same names as new
5527 commands for TeX. `@definfoenclose' creates new commands for Info that
5528 mark text by enclosing it in strings that precede and follow the text.
5529 (1) (*note Customized Highlighting-Footnote-1::)
5531 Here is how to create a new @-command called `@phoo' that causes TeX
5532 to typeset its argument in italics and causes Info to display the
5533 argument between `//' and `\\'.
5535 For TeX, write the following to equate the `@phoo' command with the
5536 existing `@i' italics command:
5542 This defines `@phoo' as a command that causes TeX to typeset the
5543 argument to `@phoo' in italics. `@global@let' tells TeX to equate the
5544 next argument with the argument that follows the equals sign.
5546 For Info, write the following to tell the Info formatters to enclose
5547 the argument between `//' and `\\':
5550 @definfoenclose phoo, //, \\
5553 Write the `@definfoenclose' command on a line and follow it with three
5554 arguments separated by commas (commas are used as separators in an
5555 `@node' line in the same way).
5557 * The first argument to `@definfoenclose' is the @-command name
5560 * the second argument is the Info start delimiter string; and,
5562 * the third argument is the Info end delimiter string.
5564 The latter two arguments enclose the highlighted text in the Info file.
5565 A delimiter string may contain spaces. Neither the start nor end
5566 delimiter is required. However, if you do not provide a start
5567 delimiter, you must follow the command name with two commas in a row;
5568 otherwise, the Info formatting commands will misinterpret the end
5569 delimiter string as a start delimiter string.
5571 After you have defined `@phoo' both for TeX and for Info, you can
5572 then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
5573 italics in printed output.
5575 Note that each definition applies to its own formatter: one for TeX,
5578 Here is another example:
5581 @definfoenclose headword, , :
5584 @global@let@headword=@b
5587 This defines `@headword' as an Info formatting command that inserts
5588 nothing before and a colon after the argument and as a TeX formatting
5589 command to typeset its argument in bold.
5592 File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting
5594 (1) Currently, `@definfoenclose' works only with
5595 `texinfo-format-buffer' and `texinfo-format-region', not with
5599 File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top
5601 Quotations and Examples
5602 ***********************
5604 Quotations and examples are blocks of text consisting of one or more
5605 whole paragraphs that are set off from the bulk of the text and treated
5606 differently. They are usually indented.
5608 In Texinfo, you always begin a quotation or example by writing an
5609 @-command at the beginning of a line by itself, and end it by writing
5610 an `@end' command that is also at the beginning of a line by itself.
5611 For instance, you begin an example by writing `@example' by itself at
5612 the beginning of a line and end the example by writing `@end example'
5613 on a line by itself, at the beginning of that line.
5617 * Block Enclosing Commands:: Use different constructs for
5619 * quotation:: How to write a quotation.
5620 * example:: How to write an example in a fixed-width font.
5621 * noindent:: How to prevent paragraph indentation.
5622 * Lisp Example:: How to illustrate Lisp code.
5623 * smallexample & smalllisp:: Forms for the `@smallbook' option.
5624 * display:: How to write an example in the current font.
5625 * format:: How to write an example that does not narrow
5627 * exdent:: How to undo the indentation of a line.
5628 * flushleft & flushright:: How to push text flushleft or flushright.
5629 * cartouche:: How to draw cartouches around examples.
5632 File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples
5634 The Block Enclosing Commands
5635 ============================
5637 Here are commands for quotations and examples:
5640 Indicate text that is quoted. The text is filled, indented, and
5641 printed in a roman font by default.
5644 Illustrate code, commands, and the like. The text is printed in a
5645 fixed-width font, and indented but not filled.
5648 Illustrate Lisp code. The text is printed in a fixed-width font,
5649 and indented but not filled.
5652 Illustrate code, commands, and the like. Similar to `@example',
5653 except that in TeX this command typesets text in a smaller font
5654 for the smaller `@smallbook' format than for the 8.5 by 11 inch
5658 Illustrate Lisp code. Similar to `@lisp', except that in TeX this
5659 command typesets text in a smaller font for the smaller
5660 `@smallbook' format than for the 8.5 by 11 inch format.
5663 Display illustrative text. The text is indented but not filled,
5664 and no font is specified (so, by default, the font is roman).
5667 Print illustrative text. The text is not indented and not filled
5668 and no font is specified (so, by default, the font is roman).
5670 The `@exdent' command is used within the above constructs to undo the
5671 indentation of a line.
5673 The `@flushleft' and `@flushright' commands are used to line up the
5674 left or right margins of unfilled text.
5676 The `@noindent' command may be used after one of the above constructs
5677 to prevent the following text from being indented as a new paragraph.
5679 You can use the `@cartouche' command within one of the above
5680 constructs to highlight the example or quotation by drawing a box with
5681 rounded corners around it. (The `@cartouche' command affects only the
5682 printed manual; it has no effect in the Info file; see *Note Drawing
5683 Cartouches Around Examples: cartouche.)
5686 File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples
5691 The text of a quotation is processed normally except that:
5693 * the margins are closer to the center of the page, so the whole of
5694 the quotation is indented;
5696 * the first lines of paragraphs are indented no more than other
5699 * in the printed output, interparagraph spacing is reduced.
5701 This is an example of text written between an `@quotation' command
5702 and an `@end quotation' command. An `@quotation' command is most
5703 often used to indicate text that is excerpted from another (real
5704 or hypothetical) printed work.
5706 Write an `@quotation' command as text on a line by itself. This line
5707 will disappear from the output. Mark the end of the quotation with a
5708 line beginning with and containing only `@end quotation'. The `@end
5709 quotation' line will likewise disappear from the output. Thus, the
5722 File: texinfo.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples
5727 The `@example' command is used to indicate an example that is not part
5728 of the running text, such as computer input or output.
5730 This is an example of text written between an
5732 and an `@end example' command.
5733 The text is indented but not filled.
5735 In the printed manual, the text is typeset in a
5736 fixed-width font, and extra spaces and blank lines are
5737 significant. In the Info file, an analogous result is
5738 obtained by indenting each line with five spaces.
5740 Write an `@example' command at the beginning of a line by itself.
5741 This line will disappear from the output. Mark the end of the example
5742 with an `@end example' command, also written at the beginning of a line
5743 by itself. The `@end example' will disappear from the output.
5755 Since the lines containing `@example' and `@end example' will
5756 disappear, you should put a blank line before the `@example' and
5757 another blank line after the `@end example'. (Remember that blank
5758 lines between the beginning `@example' and the ending `@end example'
5759 will appear in the output.)
5761 *Caution:* Do not use tabs in the lines of an example (or anywhere
5762 else in Texinfo, for that matter)! TeX treats tabs as single
5763 spaces, and that is not what they look like. This is a problem
5764 with TeX. (If necessary, in Emacs, you can use `M-x untabify' to
5765 convert tabs in a region to multiple spaces.)
5767 Examples are often, logically speaking, "in the middle" of a
5768 paragraph, and the text continues after an example should not be
5769 indented. The `@noindent' command prevents a piece of text from being
5770 indented as if it were a new paragraph. (*Note noindent::.)
5772 (The `@code' command is used for examples of code that are embedded
5773 within sentences, not set off from preceding and following text. *Note
5777 File: texinfo.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples
5782 An example or other inclusion can break a paragraph into segments.
5783 Ordinarily, the formatters indent text that follows an example as a new
5784 paragraph. However, you can prevent this by writing `@noindent' at the
5785 beginning of a line by itself preceding the continuation text.
5794 This line is not indented. As you can see, the
5795 beginning of the line is fully flush left with the line
5796 that follows after it. (This whole example is between
5797 @code{@@display} and @code{@@end display}.)
5804 This line is not indented. As you can see, the
5805 beginning of the line is fully flush left with the line
5806 that follows after it. (This whole example is between
5807 `@display' and `@end display'.)
5809 To adjust the number of blank lines properly in the Info file output,
5810 remember that the line containing `@noindent' does not generate a blank
5811 line, and neither does the `@end example' line.
5813 In the Texinfo source file for this manual, each line that says
5814 `produces' is preceded by a line containing `@noindent'.
5816 Do not put braces after an `@noindent' command; they are not
5817 necessary, since `@noindent' is a command used outside of paragraphs
5818 (*note Command Syntax::).
5821 File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples
5826 The `@lisp' command is used for Lisp code. It is synonymous with the
5829 This is an example of text written between an
5830 `@lisp' command and an `@end lisp' command.
5832 Use `@lisp' instead of `@example' to preserve information regarding
5833 the nature of the example. This is useful, for example, if you write a
5834 function that evaluates only and all the Lisp code in a Texinfo file.
5835 Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
5836 Example-Footnote-1::)
5838 Mark the end of `@lisp' with `@end lisp' on a line by itself.
5841 File: texinfo.info, Node: Lisp Example-Footnotes, Up: Lisp Example
5843 (1) It would be straightforward to extend Texinfo to work in a
5844 similar fashion for C, Fortran, or other languages.
5847 File: texinfo.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples
5849 `@smallexample' and `@smalllisp'
5850 ================================
5852 In addition to the regular `@example' and `@lisp' commands, Texinfo has
5853 two other "example-style" commands. These are the `@smallexample' and
5854 `@smalllisp' commands. Both these commands are designed for use with
5855 the `@smallbook' command that causes TeX to produce a printed manual in
5856 a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format.
5858 In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
5859 a smaller font for the smaller `@smallbook' format than for the 8.5 by
5860 11 inch format. Consequently, many examples containing long lines fit
5861 in a narrower, `@smallbook' page without needing to be shortened. Both
5862 commands typeset in the normal font size when you format for the 8.5 by
5863 11 inch size; indeed, in this situation, the `@smallexample' and
5864 `@smalllisp' commands are defined to be the `@example' and `@lisp'
5867 In Info, the `@smallexample' and `@smalllisp' commands are equivalent
5868 to the `@example' and `@lisp' commands, and work exactly the same.
5870 Mark the end of `@smallexample' or `@smalllisp' with `@end
5871 smallexample' or `@end smalllisp', respectively.
5873 This is an example of text written between `@smallexample' and
5874 `@end smallexample'. In Info and in an 8.5 by 11 inch manual,
5875 this text appears in its normal size; but in a 7 by 9.25 inch manual,
5876 this text appears in a smaller font.
5878 The `@smallexample' and `@smalllisp' commands make it easier to
5879 prepare smaller format manuals without forcing you to edit examples by
5880 hand to fit them onto narrower pages.
5882 As a general rule, a printed document looks better if you write all
5883 the examples in a chapter consistently in `@example' or in
5884 `@smallexample'. Only occasionally should you mix the two formats.
5886 *Note Printing "Small" Books: smallbook, for more information about
5887 the `@smallbook' command.
5890 File: texinfo.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples
5895 The `@display' command begins a kind of example. It is like the
5896 `@example' command except that, in a printed manual, `@display' does
5897 not select the fixed-width font. In fact, it does not specify the font
5898 at all, so that the text appears in the same font it would have
5899 appeared in without the `@display' command.
5901 This is an example of text written between an `@display' command
5902 and an `@end display' command. The `@display' command
5903 indents the text, but does not fill it.
5906 File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples
5911 The `@format' command is similar to `@example' except that, in the
5912 printed manual, `@format' does not select the fixed-width font and does
5913 not narrow the margins.
5915 This is an example of text written between an `@format' command
5916 and an `@end format' command. As you can see
5918 the `@format' command does not fill the text.
5921 File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples
5923 `@exdent': Undoing a Line's Indentation
5924 =======================================
5926 The `@exdent' command removes any indentation a line might have. The
5927 command is written at the beginning of a line and applies only to the
5928 text that follows the command that is on the same line. Do not use
5929 braces around the text. In a printed manual, the text on an `@exdent'
5930 line is printed in the roman font.
5932 `@exdent' is usually used within examples. Thus,
5935 This line follows an @@example command.
5936 @exdent This line is exdented.
5937 This line follows the exdented line.
5938 The @@end example comes on the next line.
5943 This line follows an @example command.
5944 This line is exdented.
5945 This line follows the exdented line.
5946 The @end example comes on the next line.
5948 In practice, the `@exdent' command is rarely used. Usually, you
5949 un-indent text by ending the example and returning the page to its
5953 File: texinfo.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples
5955 `@flushleft' and `@flushright'
5956 ==============================
5958 The `@flushleft' and `@flushright' commands line up the ends of lines
5959 on the left and right margins of a page, but do not fill the text. The
5960 commands are written on lines of their own, without braces. The
5961 `@flushleft' and `@flushright' commands are ended by `@end flushleft'
5962 and `@end flushright' commands on lines of their own.
5976 `@flushright' produces the type of indentation often used in the
5977 return address of letters. For example,
5980 Here is an example of text written
5981 flushright. The @code{@flushright} command
5982 right justifies every line but leaves the
5988 Here is an example of text written
5989 flushright. The `@flushright' command
5990 right justifies every line but leaves the
5994 File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples
5996 Drawing Cartouches Around Examples
5997 ==================================
5999 In a printed manual, the `@cartouche' command draws a box with rounded
6000 corners around its contents. You can use this command to further
6001 highlight an example or quotation. For instance, you could write a
6002 manual in which one type of example is surrounded by a cartouche for
6005 The `@cartouche' command affects only the printed manual; it has no
6006 effect in the Info file.
6013 /usr/local/share/emacs
6017 surrounds the two-line example with a box with rounded corners, in the
6021 File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top
6026 Texinfo has several ways of making lists and tables. Lists can be
6027 bulleted or numbered; two-column tables can highlight the items in the
6028 first column; multi-column tables are also supported.
6032 * Introducing Lists:: Texinfo formats lists for you.
6033 * itemize:: How to construct a simple list.
6034 * enumerate:: How to construct a numbered list.
6035 * Two-column Tables:: How to construct a two-column table.
6036 * Multi-column Tables:: How to construct generalized tables.
6039 File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables
6044 Texinfo automatically indents the text in lists or tables, and numbers
6045 an enumerated list. This last feature is useful if you modify the
6046 list, since you do not need to renumber it yourself.
6048 Numbered lists and tables begin with the appropriate @-command at the
6049 beginning of a line, and end with the corresponding `@end' command on a
6050 line by itself. The table and itemized-list commands also require that
6051 you write formatting information on the same line as the beginning
6054 Begin an enumerated list, for example, with an `@enumerate' command
6055 and end the list with an `@end enumerate' command. Begin an itemized
6056 list with an `@itemize' command, followed on the same line by a
6057 formatting command such as `@bullet', and end the list with an `@end
6060 Precede each element of a list with an `@item' or `@itemx' command.
6063 Here is an itemized list of the different kinds of table and lists:
6065 * Itemized lists with and without bullets.
6067 * Enumerated lists, using numbers or letters.
6069 * Two-column tables with highlighting.
6072 Here is an enumerated list with the same items:
6074 1. Itemized lists with and without bullets.
6076 2. Enumerated lists, using numbers or letters.
6078 3. Two-column tables with highlighting.
6081 And here is a two-column table with the same items and their @-commands:
6084 Itemized lists with and without bullets.
6087 Enumerated lists, using numbers or letters.
6092 Two-column tables with indexing.
6095 File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables
6097 Making an Itemized List
6098 =======================
6100 The `@itemize' command produces sequences of indented paragraphs, with
6101 a bullet or other mark inside the left margin at the beginning of each
6102 paragraph for which such a mark is desired.
6104 Begin an itemized list by writing `@itemize' at the beginning of a
6105 line. Follow the command, on the same line, with a character or a
6106 Texinfo command that generates a mark. Usually, you will write
6107 `@bullet' after `@itemize', but you can use `@minus', or any character
6108 or any special symbol that results in a single character in the Info
6109 file. (When you write `@bullet' or `@minus' after an `@itemize'
6110 command, you may omit the `{}'.)
6112 Write the text of the indented paragraphs themselves after the
6113 `@itemize', up to another line that says `@end itemize'.
6115 Before each paragraph for which a mark in the margin is desired, write
6116 a line that says just `@item'. Do not write any other text on this
6119 Usually, you should put a blank line before an `@item'. This puts a
6120 blank line in the Info file. (TeX inserts the proper interline
6121 whitespace in either case.) Except when the entries are very brief,
6122 these blank lines make the list look better.
6124 Here is an example of the use of `@itemize', followed by the output
6125 it produces. Note that `@bullet' produces a `*' in Info and a round
6139 * Some text for foo.
6141 * Some text for bar.
6143 Itemized lists may be embedded within other itemized lists. Here is a
6144 list marked with dashes embedded in a list marked with bullets:
6168 - Second inner item.
6170 * Second outer item.
6173 File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables
6175 Making a Numbered or Lettered List
6176 ==================================
6178 `@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
6179 that the labels on the items are successive integers or letters instead
6182 Write the `@enumerate' command at the beginning of a line. The
6183 command does not require an argument, but accepts either a number or a
6184 letter as an option. Without an argument, `@enumerate' starts the list
6185 with the number `1'. With a numeric argument, such as `3', the command
6186 starts the list with that number. With an upper or lower case letter,
6187 such as `a' or `A', the command starts the list with that letter.
6189 Write the text of the enumerated list in the same way you write an
6190 itemized list: put `@item' on a line of its own before the start of
6191 each paragraph that you want enumerated. Do not write any other text
6192 on the line beginning with `@item'.
6194 You should put a blank line between entries in the list. This
6195 generally makes it easier to read the Info file.
6197 Here is an example of `@enumerate' without an argument:
6209 1. Underlying causes.
6211 2. Proximate causes.
6214 Here is an example with an argument of `3':
6218 Predisposing causes.
6221 Precipitating causes.
6224 Perpetuating causes.
6229 3. Predisposing causes.
6231 4. Precipitating causes.
6233 5. Perpetuating causes.
6236 Here is a brief summary of the alternatives. The summary is
6237 constructed using `@enumerate' with an argument of `a'.
6241 Without an argument, produce a numbered list, starting with the
6244 b. `@enumerate POSITIVE-INTEGER'
6246 With a (positive) numeric argument, start a numbered list with that
6247 number. You can use this to continue a list that you interrupted
6250 c. `@enumerate UPPER-CASE-LETTER'
6252 With an upper case letter as argument, start a list in which each
6253 item is marked by a letter, beginning with that upper case letter.
6255 d. `@enumerate LOWER-CASE-LETTER'
6257 With a lower case letter as argument, start a list in which each
6258 item is marked by a letter, beginning with that lower case letter.
6260 You can also nest enumerated lists, as in an outline.
6263 File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables
6265 Making a Two-column Table
6266 =========================
6268 `@table' is similar to `@itemize' (*note `@itemize': itemize.), but
6269 allows you to specify a name or heading line for each item. The
6270 `@table' command is used to produce two-column tables, and is
6271 especially useful for glossaries, explanatory exhibits, and
6272 command-line option summaries.
6276 * table:: How to construct a two-column table.
6277 * ftable vtable:: Automatic indexing for two-column tables.
6278 * itemx:: How to put more entries in the first column.
6281 File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables
6283 Using the `@table' Command
6284 --------------------------
6286 Use the `@table' command to produce two-column tables.
6288 Write the `@table' command at the beginning of a line and follow it
6289 on the same line with an argument that is a Texinfo "indicating"
6290 command such as `@code', `@samp', `@var', or `@kbd' (*note
6291 Indicating::). Although these commands are usually followed by
6292 arguments in braces, in this case you use the command name without an
6293 argument because `@item' will supply the argument. This command will
6294 be applied to the text that goes into the first column of each item and
6295 determines how it will be highlighted. For example, `@code' will cause
6296 the text in the first column to be highlighted with an `@code' command.
6297 (We recommend `@code' for `@table''s of command-line options.)
6299 You may also choose to use the `@asis' command as an argument to
6300 `@table'. `@asis' is a command that does nothing; if you use this
6301 command after `@table', TeX and the Info formatting commands output the
6302 first column entries without added highlighting ("as is").
6304 (The `@table' command may work with other commands besides those
6305 listed here. However, you can only use commands that normally take
6306 arguments in braces.)
6308 Begin each table entry with an `@item' command at the beginning of a
6309 line. Write the first column text on the same line as the `@item'
6310 command. Write the second column text on the line following the
6311 `@item' line and on subsequent lines. (You do not need to type
6312 anything for an empty second column entry.) You may write as many
6313 lines of supporting text as you wish, even several paragraphs. But
6314 only text on the same line as the `@item' will be placed in the first
6317 Normally, you should put a blank line before an `@item' line. This
6318 puts a blank like in the Info file. Except when the entries are very
6319 brief, a blank line looks better.
6321 The following table, for example, highlights the text in the first
6322 column with an `@samp' command:
6326 This is the text for
6330 Text for @samp{bar}.
6336 This is the text for `foo'.
6341 If you want to list two or more named items with a single block of
6342 text, use the `@itemx' command. (*Note `@itemx': itemx.)
6345 File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables
6347 `@ftable' and `@vtable'
6348 -----------------------
6350 The `@ftable' and `@vtable' commands are the same as the `@table'
6351 command except that `@ftable' automatically enters each of the items in
6352 the first column of the table into the index of functions and `@vtable'
6353 automatically enters each of the items in the first column of the table
6354 into the index of variables. This simplifies the task of creating
6355 indices. Only the items on the same line as the `@item' commands are
6356 indexed, and they are indexed in exactly the form that they appear on
6357 that line. *Note Creating Indices: Indices, for more information about
6360 Begin a two-column table using `@ftable' or `@vtable' by writing the
6361 @-command at the beginning of a line, followed on the same line by an
6362 argument that is a Texinfo command such as `@code', exactly as you
6363 would for an `@table' command; and end the table with an `@end ftable'
6364 or `@end vtable' command on a line by itself.
6366 See the example for `@table' in the previous section.
6369 File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables
6374 Use the `@itemx' command inside a table when you have two or more first
6375 column entries for the same item, each of which should appear on a line
6376 of its own. Use `@itemx' for all but the first entry; `@itemx' should
6377 always follow an `@item' command. The `@itemx' command works exactly
6378 like `@item' except that it does not generate extra vertical space
6379 above the first column text.
6386 These two functions accept a character or a string as
6387 argument, and return the corresponding upper case (lower
6388 case) character or string.
6395 These two functions accept a character or a string as argument,
6396 and return the corresponding upper case (lower case) character or
6399 (Note also that this example illustrates multi-line supporting text in
6400 a two-column table.)
6403 File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables
6408 `@multitable' allows you to construct tables with any number of
6409 columns, with each column having any width you like.
6411 You define the column widths on the `@multitable' line itself, and
6412 write each row of the actual table following an `@item' command, with
6413 columns separated by an `@tab' command. Finally, `@end multitable'
6414 completes the table. Details in the sections below.
6418 * Multitable Column Widths:: Defining multitable column widths.
6419 * Multitable Rows:: Defining multitable rows, with examples.
6422 File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Prev: Multi-column Tables, Up: Multi-column Tables
6424 Multitable Column Widths
6425 ------------------------
6427 You can define the column widths for a multitable in two ways: as
6428 fractions of the line length; or with a prototype row. Mixing the two
6429 methods is not supported. In either case, the widths are defined
6430 entirely on the same line as the `@multitable' command.
6432 1. To specify column widths as fractions of the line length, write
6433 `@columnfractions' and the decimal numbers (presumably less than
6434 1) after the `@multitable' command, as in:
6436 @multitable @columnfractions .33 .33 .33
6438 The fractions need not add up exactly to 1.0, as these do not.
6439 This allows you to produce tables that do not need the full line
6442 2. To specify a prototype row, write the longest entry for each column
6443 enclosed in braces after the `@multitable' command. For example:
6445 @multitable {some text for column one} {for column two}
6447 The first column will then have the width of the typeset `some
6448 text for column one', and the second column the width of `for
6451 The prototype entries need not appear in the table itself.
6453 Although we used simple text in this example, the prototype
6454 entries can contain Texinfo commands; markup commands such as
6455 `@code' are particularly likely to be useful.
6459 File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables
6464 After the `@multitable' command defining the column widths (see the
6465 previous section), you begin each row in the body of a multitable with
6466 `@item', and separate the column entries with `@tab'. Line breaks are
6467 not special within the table body, and you may break input lines in
6468 your source file as necessary.
6470 Here is a complete example of a multi-column table (the text is from
6471 `The XEmacs Users' Manual', *note Splitting Windows: (xemacs)Split
6474 @multitable @columnfractions .15 .45 .4
6475 @item Key @tab Command @tab Description
6477 @tab @code{split-window-vertically}
6478 @tab Split the selected window into two windows,
6479 with one above the other.
6481 @tab @code{split-window-horizontally}
6482 @tab Split the selected window into two windows
6483 positioned side by side.
6486 @tab In the mode line or scroll bar of a window,
6492 Key Command Description
6493 C-x 2 `split-window-vertically' Split the selected window
6494 into two windows, with one
6496 C-x 3 `split-window-horizontally' Split the selected window
6497 into two windows positioned
6499 C-Mouse-2 In the mode line or scroll
6500 bar of a window, split that
6504 File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top
6509 Using Texinfo, you can generate indices without having to sort and
6510 collate entries manually. In an index, the entries are listed in
6511 alphabetical order, together with information on how to find the
6512 discussion of each entry. In a printed manual, this information
6513 consists of page numbers. In an Info file, this information is a menu
6514 entry leading to the first node referenced.
6516 Texinfo provides several predefined kinds of index: an index for
6517 functions, an index for variables, an index for concepts, and so on.
6518 You can combine indices or use them for other than their canonical
6519 purpose. If you wish, you can define your own indices.
6523 * Index Entries:: Choose different words for index entries.
6524 * Predefined Indices:: Use different indices for different kinds
6526 * Indexing Commands:: How to make an index entry.
6527 * Combining Indices:: How to combine indices.
6528 * New Indices:: How to define your own indices.
6531 File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices
6533 Making Index Entries
6534 ====================
6536 When you are making index entries, it is good practice to think of the
6537 different ways people may look for something. Different people _do
6538 not_ think of the same words when they look something up. A helpful
6539 index will have items indexed under all the different words that people
6540 may use. For example, one reader may think it obvious that the
6541 two-letter names for indices should be listed under "Indices,
6542 two-letter names", since the word "Index" is the general concept. But
6543 another reader may remember the specific concept of two-letter names
6544 and search for the entry listed as "Two letter names for indices". A
6545 good index will have both entries and will help both readers.
6547 Like typesetting, the construction of an index is a highly skilled,
6548 professional art, the subtleties of which are not appreciated until you
6549 need to do it yourself.
6551 *Note Printing Indices & Menus::, for information about printing an
6552 index at the end of a book or creating an index menu in an Info file.
6555 File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices
6560 Texinfo provides six predefined indices:
6562 * A "concept index" listing concepts that are discussed.
6564 * A "function index" listing functions (such as entry points of
6567 * A "variables index" listing variables (such as global variables of
6570 * A "keystroke index" listing keyboard commands.
6572 * A "program index" listing names of programs.
6574 * A "data type index" listing data types (such as structures defined
6577 Not every manual needs all of these, and most manuals use two or three
6578 of them. This manual has two indices: a concept index and an @-command
6579 index (that is actually the function index but is called a command
6580 index in the chapter heading). Two or more indices can be combined
6581 into one using the `@synindex' or `@syncodeindex' commands. *Note
6582 Combining Indices::.
6585 File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices
6587 Defining the Entries of an Index
6588 ================================
6590 The data to make an index come from many individual indexing commands
6591 scattered throughout the Texinfo source file. Each command says to add
6592 one entry to a particular index; after formatting, the index will give
6593 the current page number or node name as the reference.
6595 An index entry consists of an indexing command at the beginning of a
6596 line followed, on the rest of the line, by the entry.
6598 For example, this section begins with the following five entries for
6601 @cindex Defining indexing entries
6602 @cindex Index entries
6603 @cindex Entries for an index
6604 @cindex Specifying index entries
6605 @cindex Creating index entries
6607 Each predefined index has its own indexing command--`@cindex' for the
6608 concept index, `@findex' for the function index, and so on.
6610 Concept index entries consist of text. The best way to write an index
6611 is to choose entries that are terse yet clear. If you can do this, the
6612 index often looks better if the entries are not capitalized, but
6613 written just as they would appear in the middle of a sentence.
6614 (Capitalize proper names and acronyms that always call for upper case
6615 letters.) This is the case convention we use in most GNU manuals'
6618 If you don't see how to make an entry terse yet clear, make it longer
6619 and clear--not terse and confusing. If many of the entries are several
6620 words long, the index may look better if you use a different convention:
6621 to capitalize the first word of each entry. But do not capitalize a
6622 case-sensitive name such as a C or Lisp function name or a shell
6623 command; that would be a spelling error.
6625 Whichever case convention you use, please use it consistently!
6627 Entries in indices other than the concept index are symbol names in
6628 programming languages, or program names; these names are usually
6629 case-sensitive, so use upper and lower case as required for them.
6631 By default, entries for a concept index are printed in a small roman
6632 font and entries for the other indices are printed in a small `@code'
6633 font. You may change the way part of an entry is printed with the
6634 usual Texinfo commands, such as `@file' for file names and `@emph' for
6635 emphasis (*note Marking Text::).
6637 The six indexing commands for predefined indices are:
6640 Make an entry in the concept index for CONCEPT.
6643 Make an entry in the function index for FUNCTION.
6646 Make an entry in the variable index for VARIABLE.
6649 Make an entry in the key index for KEYSTROKE.
6652 Make an entry in the program index for PROGRAM.
6655 Make an entry in the data type index for DATA TYPE.
6657 *Caution:* Do not use a colon in an index entry. In Info, a colon
6658 separates the menu entry name from the node name. An extra colon
6659 confuses Info. *Note The Parts of a Menu: Menu Parts, for more
6660 information about the structure of a menu entry.
6662 If you write several identical index entries in different places in a
6663 Texinfo file, the index in the printed manual will list all the pages to
6664 which those entries refer. However, the index in the Info file will
6665 list *only* the node that references the *first* of those index
6666 entries. Therefore, it is best to write indices in which each entry
6667 refers to only one place in the Texinfo file. Fortunately, this
6668 constraint is a feature rather than a loss since it means that the index
6669 will be easy to use. Otherwise, you could create an index that lists
6670 several pages for one entry and your reader would not know to which page
6671 to turn. If you have two identical entries for one topic, change the
6672 topics slightly, or qualify them to indicate the difference.
6674 You are not actually required to use the predefined indices for their
6675 canonical purposes. For example, suppose you wish to index some C
6676 preprocessor macros. You could put them in the function index along
6677 with actual functions, just by writing `@findex' commands for them;
6678 then, when you print the "Function Index" as an unnumbered chapter, you
6679 could give it the title `Function and Macro Index' and all will be
6680 consistent for the reader. Or you could put the macros in with the
6681 data types by writing `@tindex' commands for them, and give that index
6682 a suitable title so the reader will understand. (*Note Printing
6686 File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices
6691 Sometimes you will want to combine two disparate indices such as
6692 functions and concepts, perhaps because you have few enough of one of
6693 them that a separate index for them would look silly.
6695 You could put functions into the concept index by writing `@cindex'
6696 commands for them instead of `@findex' commands, and produce a
6697 consistent manual by printing the concept index with the title
6698 `Function and Concept Index' and not printing the `Function Index' at
6699 all; but this is not a robust procedure. It works only if your
6700 document is never included as part of another document that is designed
6701 to have a separate function index; if your document were to be included
6702 with such a document, the functions from your document and those from
6703 the other would not end up together. Also, to make your function names
6704 appear in the right font in the concept index, you would need to
6705 enclose every one of them between the braces of `@code'.
6709 * syncodeindex:: How to merge two indices, using `@code'
6710 font for the merged-from index.
6711 * synindex:: How to merge two indices, using the
6712 default font of the merged-to index.
6715 File: texinfo.info, Node: syncodeindex, Next: synindex, Prev: Combining Indices, Up: Combining Indices
6720 When you want to combine functions and concepts into one index, you
6721 should index the functions with `@findex' and index the concepts with
6722 `@cindex', and use the `@syncodeindex' command to redirect the function
6723 index entries into the concept index.
6725 The `@syncodeindex' command takes two arguments; they are the name of
6726 the index to redirect, and the name of the index to redirect it to.
6727 The template looks like this:
6729 @syncodeindex FROM TO
6731 For this purpose, the indices are given two-letter names:
6751 Write an `@syncodeindex' command before or shortly after the
6752 end-of-header line at the beginning of a Texinfo file. For example, to
6753 merge a function index with a concept index, write the following:
6757 This will cause all entries designated for the function index to merge
6758 in with the concept index instead.
6760 To merge both a variables index and a function index into a concept
6761 index, write the following:
6766 The `@syncodeindex' command puts all the entries from the `from'
6767 index (the redirected index) into the `@code' font, overriding whatever
6768 default font is used by the index to which the entries are now
6769 directed. This way, if you direct function names from a function index
6770 into a concept index, all the function names are printed in the `@code'
6771 font as you would expect.
6774 File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices
6779 The `@synindex' command is nearly the same as the `@syncodeindex'
6780 command, except that it does not put the `from' index entries into the
6781 `@code' font; rather it puts them in the roman font. Thus, you use
6782 `@synindex' when you merge a concept index into a function index.
6784 *Note Printing Indices & Menus::, for information about printing an
6785 index at the end of a book or creating an index menu in an Info file.
6788 File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices
6790 Defining New Indices
6791 ====================
6793 In addition to the predefined indices, you may use the `@defindex' and
6794 `@defcodeindex' commands to define new indices. These commands create
6795 new indexing @-commands with which you mark index entries. The
6796 `@defindex 'command is used like this:
6800 The name of an index should be a two letter word, such as `au'. For
6805 This defines a new index, called the `au' index. At the same time,
6806 it creates a new indexing command, `@auindex', that you can use to make
6807 index entries. Use the new indexing command just as you would use a
6808 predefined indexing command.
6810 For example, here is a section heading followed by a concept index
6811 entry and two `au' index entries.
6813 @section Cognitive Semantics
6814 @cindex kinesthetic image schemas
6815 @auindex Johnson, Mark
6816 @auindex Lakoff, George
6818 (Evidently, `au' serves here as an abbreviation for "author".) Texinfo
6819 constructs the new indexing command by concatenating the name of the
6820 index with `index'; thus, defining an `au' index leads to the automatic
6821 creation of an `@auindex' command.
6823 Use the `@printindex' command to print the index, as you do with the
6824 predefined indices. For example:
6826 @node Author Index, Subject Index, , Top
6827 @unnumbered Author Index
6831 The `@defcodeindex' is like the `@defindex' command, except that, in
6832 the printed output, it prints entries in an `@code' font instead of a
6833 roman font. Thus, it parallels the `@findex' command rather than the
6836 You should define new indices within or right after the end-of-header
6837 line of a Texinfo file, before any `@synindex' or `@syncodeindex'
6838 commands (*note Header::).
6841 File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
6846 Texinfo provides several commands for inserting characters that have
6847 special meaning in Texinfo, such as braces, and for other graphic
6848 elements that do not correspond to simple characters you can type.
6852 * Braces Atsigns:: How to insert braces, `@'.
6853 * Inserting Space:: How to insert the right amount of space
6855 * Inserting Accents:: How to insert accents and special characters.
6856 * Dots Bullets:: How to insert dots and bullets.
6857 * TeX and copyright:: How to insert the TeX logo
6858 and the copyright symbol.
6859 * pounds:: How to insert the pounds currency symbol.
6860 * minus:: How to insert a minus sign.
6861 * math:: How to format a mathematical expression.
6862 * Glyphs:: How to indicate results of evaluation,
6863 expansion of macros, errors, etc.
6864 * Images:: How to include graphics.
6867 File: texinfo.info, Node: Braces Atsigns, Next: Inserting Space, Prev: Insertions, Up: Insertions
6869 Inserting @ and Braces
6870 ======================
6872 `@' and curly braces are special characters in Texinfo. To insert
6873 these characters so they appear in text, you must put an `@' in front
6874 of these characters to prevent Texinfo from misinterpreting them.
6876 Do not put braces after any of these commands; they are not necessary.
6880 * Inserting An Atsign:: How to insert `@'.
6881 * Inserting Braces:: How to insert `{' and `}'.
6884 File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns, Up: Braces Atsigns
6886 Inserting `@' with @@
6887 ---------------------
6889 `@@' stands for a single `@' in either printed or Info output.
6891 Do not put braces after an `@@' command.
6894 File: texinfo.info, Node: Inserting Braces, Prev: Inserting An Atsign, Up: Braces Atsigns
6896 Inserting `{' and `}'with @{ and @}
6897 -----------------------------------
6899 `@{' stands for a single `{' in either printed or Info output.
6901 `@}' stands for a single `}' in either printed or Info output.
6903 Do not put braces after either an `@{' or an `@}' command.
6906 File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Braces Atsigns, Up: Insertions
6911 The following sections describe commands that control spacing of various
6912 kinds within and after sentences.
6916 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
6917 * Ending a Sentence:: Sometimes it does.
6918 * Multiple Spaces:: Inserting multiple spaces.
6919 * dmn:: How to format a dimension.
6922 File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space
6924 Not Ending a Sentence
6925 ---------------------
6927 Depending on whether a period or exclamation point or question mark is
6928 inside or at the end of a sentence, less or more space is inserted after
6929 a period in a typeset manual. Since it is not always possible for
6930 Texinfo to determine when a period ends a sentence and when it is used
6931 in an abbreviation, special commands are needed in some circumstances.
6932 (Usually, Texinfo can guess how to handle periods, so you do not need to
6933 use the special commands; you just enter a period as you would if you
6934 were using a typewriter, which means you put two spaces after the
6935 period, question mark, or exclamation mark that ends a sentence.)
6937 Use the `@:' command after a period, question mark, exclamation mark,
6938 or colon that should not be followed by extra space. For example, use
6939 `@:' after periods that end abbreviations which are not at the ends of
6944 The s.o.p.@: has three parts ...
6945 The s.o.p. has three parts ...
6949 The s.o.p. has three parts ...
6950 The s.o.p. has three parts ...
6952 (Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
6955 `@:' has no effect on the Info output. Do not put braces after `@:'.
6958 File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space
6963 Use `@.' instead of a period, `@!' instead of an exclamation point, and
6964 `@?' instead of a question mark at the end of a sentence that ends with
6965 a single capital letter. Otherwise, TeX will think the letter is an
6966 abbreviation and will not insert the correct end-of-sentence spacing.
6969 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.
6970 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
6974 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
6975 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
6977 In the Info file output, `@.' is equivalent to a simple `.'; likewise
6980 The meanings of `@:' and `@.' in Texinfo are designed to work well
6981 with the Emacs sentence motion commands (*note Sentences:
6982 (xemacs)Sentences.). This made it necessary for them to be
6983 incompatible with some other formatting systems that use @-commands.
6985 Do not put braces after any of these commands.
6988 File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space
6993 Ordinarily, TeX collapses multiple whitespace characters (space, tab,
6994 and newline) into a single space. Info output, on the other hand,
6995 preserves whitespace as you type it, except for changing a newline into
6996 a space; this is why it is important to put two spaces at the end of
6997 sentences in Texinfo documents.
6999 Occasionally, you may want to actually insert several consecutive
7000 spaces, either for purposes of example (what your program does with
7001 multiple spaces as input), or merely for purposes of appearance in
7002 headings or lists. Texinfo supports three commands: `@SPACE', `@TAB',
7003 and `@NL', all of which insert a single space into the output. (Here,
7004 `@SPACE' represents an `@' character followed by a space, i.e., `@ ',
7005 and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
7006 when `@' is the last character on a line.)
7016 Other possible uses of `@SPACE' have been subsumed by `@multitable'
7017 (*note Multi-column Tables::).
7019 Do not follow any of these commands with braces.
7022 File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space
7024 `@dmn'{DIMENSION}: Format a Dimension
7025 -------------------------------------
7027 At times, you may want to write `12pt' or `8.5in' with little or no
7028 space between the number and the abbreviation for the dimension. You
7029 can use the `@dmn' command to do this. On seeing the command, TeX
7030 inserts just enough space for proper typesetting; the Info formatting
7031 commands insert no space at all, since the Info file does not require
7034 To use the `@dmn' command, write the number and then follow it
7035 immediately, with no intervening space, by `@dmn', and then by the
7036 dimension within braces. For example,
7038 A4 paper is 8.27@dmn{in} wide.
7042 A4 paper is 8.27in wide.
7044 Not everyone uses this style. Some people prefer `8.27 in.@:' or
7045 `8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
7046 however, the formatters may insert a line break between the number and
7047 the dimension, so use `@w' (*note w::). Also, if you write a period
7048 after an abbreviation within a sentence, you should write `@:' after
7049 the period to prevent TeX from inserting extra whitespace, as shown
7050 here. *Note Inserting Space::.
7053 File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
7058 Here is a table with the commands Texinfo provides for inserting
7059 floating accents. The commands with non-alphabetic names do not take
7060 braces around their argument (which is taken to be the next character).
7061 (Exception: `@,' _does_ take braces around its argument.) This is so
7062 as to make the source as convenient to type and read as possible, since
7063 accented characters are very common in some languages.
7066 @"o o" umlaut accent
7068 @,{c} c, cedilla accent
7069 @=o o= macron/overbar accent
7070 @^o o^ circumflex accent
7073 @dotaccent{o} o. overdot accent
7074 @H{o} o'' long Hungarian umlaut
7075 @ringaccent{o} o* ring accent
7076 @tieaccent{oo} oo[ tie-after accent
7077 @u{o} o( breve accent
7078 @ubaraccent{o} o_ underbar accent
7079 @udotaccent{o} .o underdot accent
7080 @v{o} o< hacek or check accent
7082 This table lists the Texinfo commands for inserting other characters
7083 commonly used in languages other than English.
7085 @exclamdown{} ! upside-down !
7086 @questiondown{} ? upside-down ?
7087 @aa{},@AA{} aa,AA A,a with circle
7088 @ae{},@AE{} ae,AE ae,AE ligatures
7089 @dotless{i} i dotless i
7090 @dotless{j} j dotless j
7091 @l{},@L{} /l,/L suppressed-L,l
7092 @o{},@O{} /o,/O O,o with slash
7093 @oe{},@OE{} oe,OE OE,oe ligatures
7094 @ss{} ss es-zet or sharp S
7097 File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
7099 Inserting Ellipsis, Dots, and Bullets
7100 =====================================
7102 An "ellipsis" (a line of dots) is not typeset as a string of periods,
7103 so a special command is used for ellipsis in Texinfo. The `@bullet'
7104 command is special, too. Each of these commands is followed by a pair
7105 of braces, `{}', without any whitespace between the name of the command
7106 and the braces. (You need to use braces with these commands because
7107 you can use them next to other text; without the braces, the formatters
7108 would be confused. *Note @-Command Syntax: Command Syntax, for further
7113 * dots:: How to insert dots ...
7114 * bullet:: How to insert a bullet.
7117 File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets
7122 Use the `@dots{}' command to generate an ellipsis, which is three dots
7123 in a row, appropriately spaced, like this: `...'. Do not simply write
7124 three periods in the input file; that would work for the Info file
7125 output, but would produce the wrong amount of space between the periods
7126 in the printed manual.
7128 Similarly, the `@enddots{}' command generates an end-of-sentence
7129 ellipsis (four dots) ....
7132 File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets
7137 Use the `@bullet{}' command to generate a large round dot, or the
7138 closest possible thing to one. In Info, an asterisk is used.
7142 When you use `@bullet' in `@itemize', you do not need to type the
7143 braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)
7146 File: texinfo.info, Node: TeX and copyright, Next: pounds, Prev: Dots Bullets, Up: Insertions
7148 Inserting TeX and the Copyright Symbol
7149 ======================================
7151 The logo `TeX' is typeset in a special fashion and it needs an
7152 @-command. The copyright symbol, `(C)', is also special. Each of
7153 these commands is followed by a pair of braces, `{}', without any
7154 whitespace between the name of the command and the braces.
7158 * tex:: How to insert the TeX logo.
7159 * copyright symbol:: How to use `@copyright'{}.
7162 File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright
7167 Use the `@TeX{}' command to generate `TeX'. In a printed manual, this
7168 is a special logo that is different from three ordinary letters. In
7169 Info, it just looks like `TeX'. The `@TeX{}' command is unique among
7170 Texinfo commands in that the `T' and the `X' are in upper case.
7173 File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright
7175 `@copyright'{} ((C))
7176 --------------------
7178 Use the `@copyright{}' command to generate `(C)'. In a printed manual,
7179 this is a `c' inside a circle, and in Info, this is `(C)'.
7182 File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions
7184 `@pounds{}' (#): Pounds Sterling
7185 ================================
7187 Use the `@pounds{}' command to generate `#'. In a printed manual, this
7188 is the symbol for the currency pounds sterling. In Info, it is a `#'.
7189 Other currency symbols are unfortunately not available.
7192 File: texinfo.info, Node: minus, Next: math, Prev: pounds, Up: Insertions
7194 `@minus'{} (-): Inserting a Minus Sign
7195 ======================================
7197 Use the `@minus{}' command to generate a minus sign. In a fixed-width
7198 font, this is a single hyphen, but in a proportional font, the symbol
7199 is the customary length for a minus sign--a little longer than a
7200 hyphen, shorter than an em-dash:
7202 `-' is a minus sign generated with `@minus{}',
7204 `-' is a hyphen generated with the character `-',
7206 `---' is an em-dash for text.
7208 In the fixed-width font used by Info, `@minus{}' is the same as a
7211 You should not use `@minus{}' inside `@code' or `@example' because
7212 the width distinction is not made in the fixed-width font they use.
7214 When you use `@minus' to specify the mark beginning each entry in an
7215 itemized list, you do not need to type the braces (*note `@itemize':
7219 File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
7221 `@math' - Inserting Mathematical Expressions
7222 ============================================
7224 You can write a short mathematical expression with the `@math' command.
7225 Write the mathematical expression between braces, like this:
7227 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
7229 This produces the following in Info:
7231 (a + b)(a + b) = a^2 + 2ab + b^2
7233 Thus, the `@math' command has no effect on the Info output.
7235 For complex mathematical expressions, you can also use TeX directly
7236 (*note Raw Formatter Commands::). When you use TeX directly, remember
7237 to write the mathematical expression between one or two `$'
7238 (dollar-signs) as appropriate.
7241 File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions
7246 In Texinfo, code is often illustrated in examples that are delimited by
7247 `@example' and `@end example', or by `@lisp' and `@end lisp'. In such
7248 examples, you can indicate the results of evaluation or an expansion
7249 using `=>' or `==>'. Likewise, there are commands to insert glyphs to
7250 indicate printed output, error messages, equivalence of expressions,
7251 and the location of point.
7253 The glyph-insertion commands do not need to be used within an
7254 example, but most often they are. Every glyph-insertion command is
7255 followed by a pair of left- and right-hand braces.
7260 * result:: How to show the result of expression.
7261 * expansion:: How to indicate an expansion.
7262 * Print Glyph:: How to indicate printed output.
7263 * Error Glyph:: How to indicate an error message.
7264 * Equivalence:: How to indicate equivalence.
7265 * Point Glyph:: How to indicate the location of point.
7268 File: texinfo.info, Node: Glyphs Summary, Next: result, Prev: Glyphs, Up: Glyphs
7273 Here are the different glyph commands:
7276 `@result{}' points to the result of an expression.
7279 `@expansion{}' shows the results of a macro expansion.
7282 `@print{}' indicates printed output.
7285 `@error{}' indicates that the following text is an error message.
7288 `@equiv{}' indicates the exact equivalence of two forms.
7291 `@point{}' shows the location of point.
7303 File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs
7305 `@result{}' (=>): Indicating Evaluation
7306 ---------------------------------------
7308 Use the `@result{}' command to indicate the result of evaluating an
7311 The `@result{}' command is displayed as `=>' in Info and as a double
7312 stemmed arrow in the printed output.
7314 Thus, the following,
7319 may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
7322 File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs
7324 `@expansion{}' (==>): Indicating an Expansion
7325 ---------------------------------------------
7327 When an expression is a macro call, it expands into a new expression.
7328 You can indicate the result of the expansion with the `@expansion{}'
7331 The `@expansion{}' command is displayed as `==>' in Info and as a
7332 long arrow with a flat base in the printed output.
7334 For example, the following
7338 @expansion{} (car (cdr (cdr '(a b c))))
7345 ==> (car (cdr (cdr '(a b c))))
7348 which may be read as:
7350 `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
7351 result of evaluating the expression is `c'.
7353 Often, as in this case, an example looks better if the `@expansion{}'
7354 and `@result{}' commands are indented five spaces.
7357 File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs
7359 `@print{}' (-|): Indicating Printed Output
7360 ------------------------------------------
7362 Sometimes an expression will print output during its execution. You
7363 can indicate the printed output with the `@print{}' command.
7365 The `@print{}' command is displayed as `-|' in Info and similarly, as
7366 a horizontal dash butting against a vertical bar, in the printed output.
7368 In the following example, the printed text is indicated with `-|',
7369 and the value of the expression follows on the last line.
7371 (progn (print 'foo) (print 'bar))
7376 In a Texinfo source file, this example is written as follows:
7379 (progn (print 'foo) (print 'bar))
7386 File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs
7388 `@error{}' (error-->): Indicating an Error Message
7389 --------------------------------------------------
7391 A piece of code may cause an error when you evaluate it. You can
7392 designate the error message with the `@error{}' command.
7394 The `@error{}' command is displayed as `error-->' in Info and as the
7395 word `error' in a box in the printed output.
7401 @error{} Wrong type argument: integer-or-marker-p, x
7407 error--> Wrong type argument: integer-or-marker-p, x
7409 This indicates that the following error message is printed when you
7410 evaluate the expression:
7412 Wrong type argument: integer-or-marker-p, x
7414 `error-->' itself is not part of the error message.
7417 File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs
7419 `@equiv{}' (==): Indicating Equivalence
7420 ---------------------------------------
7422 Sometimes two expressions produce identical results. You can indicate
7423 the exact equivalence of two forms with the `@equiv{}' command.
7425 The `@equiv{}' command is displayed as `==' in Info and as a three
7426 parallel horizontal lines in the printed output.
7431 (make-sparse-keymap) @equiv{} (list 'keymap)
7436 (make-sparse-keymap) == (list 'keymap)
7438 This indicates that evaluating `(make-sparse-keymap)' produces
7439 identical results to evaluating `(list 'keymap)'.
7442 File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
7444 `@point{}' (-!-): Indicating Point in a Buffer
7445 ----------------------------------------------
7447 Sometimes you need to show an example of text in an Emacs buffer. In
7448 such examples, the convention is to include the entire contents of the
7449 buffer in question between two lines of dashes containing the buffer
7452 You can use the `@point{}' command to show the location of point in
7453 the text in the buffer. (The symbol for point, of course, is not part
7454 of the text in the buffer; it indicates the place _between_ two
7455 characters where point is located.)
7457 The `@point{}' command is displayed as `-!-' in Info and as a small
7458 five pointed star in the printed output.
7460 The following example shows the contents of buffer `foo' before and
7461 after evaluating a Lisp command to insert the word `changed'.
7463 ---------- Buffer: foo ----------
7464 This is the -!-contents of foo.
7465 ---------- Buffer: foo ----------
7469 ---------- Buffer: foo ----------
7470 This is the changed -!-contents of foo.
7471 ---------- Buffer: foo ----------
7473 In a Texinfo source file, the example is written like this:
7476 ---------- Buffer: foo ----------
7477 This is the @point{}contents of foo.
7478 ---------- Buffer: foo ----------
7482 ---------- Buffer: foo ----------
7483 This is the changed @point{}contents of foo.
7484 ---------- Buffer: foo ----------
7488 File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions
7493 You can insert an image in an external file with the `@image' command:
7495 @image{FILENAME, [WIDTH], [HEIGHT]}
7497 The FILENAME argument is mandatory, and must not have an extension,
7498 because the different processors support different formats: TeX reads
7499 the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
7500 uses `FILENAME.txt' verbatim for Info output (more or less as if it was
7501 an `@example'). HTML output requires `FILENAME.jpg'.
7503 The optional WIDTH and HEIGHT arguments specify the size to scale the
7504 image to (they are ignored for Info output). If they are both
7505 specified, the image is presented in its natural size (given in the
7506 file); if only one is specified, the other is scaled proportionately;
7507 and if both are specified, both are respected, thus possibly distorting
7508 the original image by changing its aspect ratio.
7510 The WIDTH and HEIGHT may be specified using any valid TeX dimension,
7514 point (72.27pt = 1in)
7520 big point (72bp = 1in)
7526 centimeter (2.54cm = 1in)
7529 millimeter (10mm = 1cm)
7532 dido^t point (1157dd = 1238pt)
7538 scaled point (65536sp = 1pt)
7540 For example, the following will scale a file `ridt.eps' to one inch
7541 vertically, with the width scaled proportionately:
7545 For `@image' to work with TeX, the file `epsf.tex' must be installed
7546 somewhere that TeX can find it. This file is included in the Texinfo
7547 distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
7550 File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
7552 Making and Preventing Breaks
7553 ****************************
7555 Usually, a Texinfo file is processed both by TeX and by one of the Info
7556 formatting commands. Line, paragraph, or page breaks sometimes occur
7557 in the `wrong' place in one or other form of output. You must ensure
7558 that text looks right both in the printed manual and in the Info file.
7560 For example, in a printed manual, page breaks may occur awkwardly in
7561 the middle of an example; to prevent this, you can hold text together
7562 using a grouping command that keeps the text from being split across
7563 two pages. Conversely, you may want to force a page break where none
7564 would occur normally. Fortunately, problems like these do not often
7565 arise. When they do, use the break, break prevention, or pagination
7570 * Break Commands:: Cause and prevent splits.
7571 * Line Breaks:: How to force a single line to use two lines.
7572 * - and hyphenation:: How to tell TeX about hyphenation points.
7573 * w:: How to prevent unwanted line breaks.
7574 * sp:: How to insert blank lines.
7575 * page:: How to force the start of a new page.
7576 * group:: How to prevent unwanted page breaks.
7577 * need:: Another way to prevent unwanted page breaks.
7580 File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
7585 The break commands create or allow line and paragraph breaks:
7594 Insert a discretionary hyphen.
7596 `@hyphenation{HY-PHEN-A-TED WORDS}'
7597 Define hyphen points in HY-PHEN-A-TED WORDS.
7599 The line-break-prevention command holds text together all on one line:
7602 Prevent TEXT from being split and hyphenated across two lines.
7604 The pagination commands apply only to printed output, since Info
7605 files do not have pages.
7608 Start a new page in the printed manual.
7611 Hold text together that must appear on one printed page.
7614 Start a new printed page if not enough space on this one.
7617 File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
7619 `@*': Generate Line Breaks
7620 ==========================
7622 The `@*' command forces a line break in both the printed manual and in
7627 This line @* is broken @*in two places.
7635 (Note that the space after the first `@*' command is faithfully carried
7636 down to the next line.)
7638 The `@*' command is often used in a file's copyright page:
7640 This is edition 2.0 of the Texinfo documentation,@*
7643 In this case, the `@*' command keeps TeX from stretching the line
7644 across the whole page in an ugly manner.
7646 *Please note:* Do not write braces after an `@*' command; they are
7649 Do not write an `@refill' command at the end of a paragraph
7650 containing an `@*' command; it will cause the paragraph to be
7651 refilled after the line break occurs, negating the effect of the
7655 File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
7657 `@-' and `@hyphenation': Helping TeX hyphenate
7658 ==============================================
7660 Although TeX's hyphenation algorithm is generally pretty good, it does
7661 miss useful hyphenation points from time to time. (Or, far more
7662 rarely, insert an incorrect hyphenation.) So, for documents with an
7663 unusual vocabulary or when fine-tuning for a printed edition, you may
7664 wish to help TeX out. Texinfo supports two commands for this:
7667 Insert a discretionary hyphen, i.e., a place where TeX can (but
7668 does not have to) hyphenate. This is especially useful when you
7669 notice an overfull hbox is due to TeX missing a hyphenation (*note
7670 Overfull hboxes::). TeX will not insert any hyphenation points in
7671 a word containing `@-'.
7673 `@hyphenation{HY-PHEN-A-TED WORDS}'
7674 Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
7675 a `-' at each hyphenation point. For example:
7676 @hyphenation{man-u-script man-u-scripts}
7678 TeX only uses the specified hyphenation points when the words
7679 match exactly, so give all necessary variants.
7681 Info output is not hyphenated, so these commands have no effect there.
7684 File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
7686 `@w'{TEXT}: Prevent Line Breaks
7687 ===============================
7689 `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
7691 You can use the `@w' command to prevent TeX from automatically
7692 hyphenating a long name or phrase that happens to fall near the end of a
7695 You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
7699 You can copy GNU software from `ftp.gnu.ai.mit.edu'.
7701 *Caution:* Do not write an `@refill' command at the end of a
7702 paragraph containing an `@w' command; it will cause the paragraph
7703 to be refilled and may thereby negate the effect of the `@w'
7707 File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
7709 `@sp' N: Insert Blank Lines
7710 ===========================
7712 A line beginning with and containing only `@sp N' generates N blank
7713 lines of space in both the printed manual and the Info file. `@sp'
7714 also forces a paragraph break. For example,
7718 generates two blank lines.
7720 The `@sp' command is most often used in the title page.
7723 File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
7725 `@page': Start a New Page
7726 =========================
7728 A line containing only `@page' starts a new page in a printed manual.
7729 The command has no effect on Info files since they are not paginated.
7730 An `@page' command is often used in the `@titlepage' section of a
7731 Texinfo file to start the copyright page.
7734 File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks
7736 `@group': Prevent Page Breaks
7737 =============================
7739 The `@group' command (on a line by itself) is used inside an `@example'
7740 or similar construct to begin an unsplittable vertical group, which
7741 will appear entirely on one page in the printed output. The group is
7742 terminated by a line containing only `@end group'. These two lines
7743 produce no output of their own, and in the Info file output they have
7746 Although `@group' would make sense conceptually in a wide variety of
7747 contexts, its current implementation works reliably only within
7748 `@example' and variants, and within `@display', `@format', `@flushleft'
7749 and `@flushright'. *Note Quotations and Examples::. (What all these
7750 commands have in common is that each line of input produces a line of
7751 output.) In other contexts, `@group' can cause anomalous vertical
7754 This formatting requirement means that you should write:
7762 with the `@group' and `@end group' commands inside the `@example' and
7763 `@end example' commands.
7765 The `@group' command is most often used to hold an example together
7766 on one page. In this Texinfo manual, more than 100 examples contain
7767 text that is enclosed between `@group' and `@end group'.
7769 If you forget to end a group, you may get strange and unfathomable
7770 error messages when you run TeX. This is because TeX keeps trying to
7771 put the rest of the Texinfo file onto the one page and does not start
7772 to generate error messages until it has processed considerable text.
7773 It is a good rule of thumb to look for a missing `@end group' if you
7774 get incomprehensible error messages in TeX.
7777 File: texinfo.info, Node: need, Prev: group, Up: Breaks
7779 `@need MILS': Prevent Page Breaks
7780 =================================
7782 A line containing only `@need N' starts a new page in a printed manual
7783 if fewer than N mils (thousandths of an inch) remain on the current
7784 page. Do not use braces around the argument N. The `@need' command
7785 has no effect on Info files since they are not paginated.
7787 This paragraph is preceded by an `@need' command that tells TeX to
7788 start a new page if fewer than 800 mils (eight-tenths inch) remain on
7789 the page. It looks like this:
7792 This paragraph is preceded by ...
7794 The `@need' command is useful for preventing orphans (single lines at
7795 the bottoms of printed pages).
7798 File: texinfo.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top
7803 The `@deffn' command and the other "definition commands" enable you to
7804 describe functions, variables, macros, commands, user options, special
7805 forms and other such artifacts in a uniform format.
7807 In the Info file, a definition causes the entity
7808 category--`Function', `Variable', or whatever--to appear at the
7809 beginning of the first line of the definition, followed by the entity's
7810 name and arguments. In the printed manual, the command causes TeX to
7811 print the entity's name and its arguments on the left margin and print
7812 the category next to the right margin. In both output formats, the
7813 body of the definition is indented. Also, the name of the entity is
7814 entered into the appropriate index: `@deffn' enters the name into the
7815 index of functions, `@defvr' enters it into the index of variables, and
7818 A manual need not and should not contain more than one definition for
7819 a given name. An appendix containing a summary should use `@table'
7820 rather than the definition commands.
7824 * Def Cmd Template:: How to structure a description using a
7826 * Optional Arguments:: How to handle optional and repeated arguments.
7827 * deffnx:: How to group two or more `first' lines.
7828 * Def Cmds in Detail:: All the definition commands.
7829 * Def Cmd Conventions:: Conventions for writing definitions.
7830 * Sample Function Definition::
7833 File: texinfo.info, Node: Def Cmd Template, Next: Optional Arguments, Prev: Definition Commands, Up: Definition Commands
7835 The Template for a Definition
7836 =============================
7838 The `@deffn' command is used for definitions of entities that resemble
7839 functions. To write a definition using the `@deffn' command, write the
7840 `@deffn' command at the beginning of a line and follow it on the same
7841 line by the category of the entity, the name of the entity itself, and
7842 its arguments (if any). Then write the body of the definition on
7843 succeeding lines. (You may embed examples in the body.) Finally, end
7844 the definition with an `@end deffn' command written on a line of its
7845 own. (The other definition commands follow the same format.)
7847 The template for a definition looks like this:
7849 @deffn CATEGORY NAME ARGUMENTS...
7855 @deffn Command forward-word count
7856 This command moves point forward @var{count} words
7857 (or backward if @var{count} is negative). ...
7862 - Command: forward-word count
7863 This function moves point forward COUNT words (or backward if
7864 COUNT is negative). ...
7866 Capitalize the category name like a title. If the name of the
7867 category contains spaces, as in the phrase `Interactive Command', write
7868 braces around it. For example:
7870 @deffn {Interactive Command} isearch-forward
7874 Otherwise, the second word will be mistaken for the name of the entity.
7876 Some of the definition commands are more general than others. The
7877 `@deffn' command, for example, is the general definition command for
7878 functions and the like--for entities that may take arguments. When you
7879 use this command, you specify the category to which the entity belongs.
7880 The `@deffn' command possesses three predefined, specialized
7881 variations, `@defun', `@defmac', and `@defspec', that specify the
7882 category for you: "Function", "Macro", and "Special Form" respectively.
7883 (In Lisp, a special form is an entity much like a function.) The
7884 `@defvr' command also is accompanied by several predefined, specialized
7885 variations for describing particular kinds of variables.
7887 The template for a specialized definition, such as `@defun', is
7888 similar to the template for a generalized definition, except that you
7889 do not need to specify the category:
7891 @defun NAME ARGUMENTS...
7897 @defun buffer-end flag
7898 This function returns @code{(point-min)} if @var{flag}
7899 is less than 1, @code{(point-max)} otherwise.
7905 - Function: buffer-end flag
7906 This function returns `(point-min)' if FLAG is less than 1,
7907 `(point-max)' otherwise. ...
7909 *Note Sample Function Definition: Sample Function Definition, for a
7910 more detailed example of a function definition, including the use of
7911 `@example' inside the definition.
7913 The other specialized commands work like `@defun'.