1 This is Info file ../info/texinfo.info, produced by Makeinfo version
2 1.68 from the input file texinfo.texi.
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
520 include 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-Footnotes::) 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 GNU Emacs Manual' is a good example of
608 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
652 documentation 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-Footnotes::)
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
737 manual. To do this, you need TeX, a powerful, sophisticated typesetting
738 program written by Donald Knuth.(1) (*note Printed Books-Footnotes::)
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-Footnotes::) 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
872 a 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
925 either the Info file or the printed manual by using the `@comment'
926 command (which may be abbreviated to `@c'). Such comments are for the
927 person who reads the Texinfo file. All the text on a line that follows
928 either `@comment' or `@c' is a comment; the rest of the line does not
929 appear in either the Info file or the printed manual. (Often, you can
930 write the `@comment' or `@c' in the middle of a line, and only the text
931 that follows after the `@comment' or `@c' command does not appear; but
932 some commands, such as `@settitle' and `@setfilename', work on a whole
933 line. You cannot use `@comment' or `@c' in a line beginning with such
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
1010 and 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.
projects / chise / xemacs-chise.git.1 / blob