1 This is ../info/texinfo.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Update info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
9 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both online information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
19 This edition is for Texinfo version 4.0, 28 September 1999.
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, Up: (dir)
41 Texinfo is a documentation system that uses a single source file to
42 produce both online 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 4.0 of the Texinfo manual, updated 28 September 1999.
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 * Conditionals:: How to specify text for either TeX or Info.
73 * Internationalization::
74 * Defining New Texinfo Commands::
75 * Hardcopy:: How to convert a Texinfo file to a file
76 for printing and how to print that file.
77 * Creating and Installing Info Files::
78 * Command List:: All the Texinfo @-commands.
79 * Tips:: Hints on how to write a Texinfo document.
80 * Sample Texinfo File:: A sample Texinfo file to look at.
81 * Sample Permissions:: Tell readers they have the right to copy
83 * Include Files:: How to incorporate other Texinfo files.
84 * Headings:: How to write page headings and footings.
85 * Catching Mistakes:: How to find formatting mistakes.
86 * Refilling Paragraphs:: All about paragraph refilling.
87 * Command Syntax:: A description of @-Command syntax.
88 * Obtaining TeX:: How to Obtain TeX.
89 * Command and Variable Index:: A menu containing commands and variables.
90 * Concept Index:: A menu covering many topics.
93 --- The Detailed Node Listing ---
97 * Reporting Bugs:: Submitting effective bug reports.
98 * Using Texinfo:: Create printed or online output.
99 * Info Files:: What is an Info file?
100 * Printed Books:: Characteristics of a printed book or manual.
101 * Formatting Commands:: @-commands are used for formatting.
102 * Conventions:: General rules for writing a Texinfo file.
103 * Comments:: Writing comments and ignored text in general.
104 * Minimum:: What a Texinfo file must have.
105 * Six Parts:: Usually, a Texinfo file has six parts.
106 * Short Sample:: A short sample Texinfo file.
107 * Acknowledgements and History:: Contributors and genesis.
111 * Texinfo Mode Overview:: How Texinfo mode can help you.
112 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
113 purpose editing features.
114 * Inserting:: How to insert frequently used @-commands.
115 * Showing the Structure:: How to show the structure of a file.
116 * Updating Nodes and Menus:: How to update or create new nodes and menus.
117 * Info Formatting:: How to format for Info.
118 * Printing:: How to format and print part or all of a file.
119 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
121 Updating Nodes and Menus
123 * Updating Commands:: Five major updating commands.
124 * Updating Requirements:: How to structure a Texinfo file for
125 using the updating command.
126 * Other Updating Commands:: How to indent descriptions, insert
127 missing nodes lines, and update
130 Beginning a Texinfo File
132 * Four Parts:: Four parts begin a Texinfo file.
133 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
134 * Header:: The very beginning of a Texinfo file.
135 * Info Summary and Permissions:: Summary and copying permissions for Info.
136 * Titlepage & Copyright Page:: Creating the title and copyright pages.
137 * The Top Node:: Creating the `Top' node and master menu.
138 * Software Copying Permissions:: Ensure that you and others continue to
139 have the right to use and share software.
141 The Texinfo File Header
143 * First Line:: The first line of a Texinfo file.
144 * Start of Header:: Formatting a region requires this.
145 * setfilename:: Tell Info the name of the Info file.
146 * settitle:: Create a title for the printed work.
147 * setchapternewpage:: Start chapters on right-hand pages.
148 * paragraphindent:: Specify paragraph indentation.
149 * exampleindent:: Specify environment indentation.
150 * End of Header:: Formatting a region requires this.
152 The Title and Copyright Pages
154 * titlepage:: Create a title for the printed document.
155 * titlefont center sp:: The `@titlefont', `@center',
157 * title subtitle author:: The `@title', `@subtitle',
158 and `@author' commands.
159 * Copyright & Permissions:: How to write the copyright notice and
160 include copying permissions.
161 * end titlepage:: Turn on page headings after the title and
163 * headings on off:: An option for turning headings on and off
164 and double or single sided printing.
166 The `Top' Node and Master Menu
168 * Title of Top Node:: Sketch what the file is about.
169 * Master Menu Parts:: A master menu has three or more parts.
171 Ending a Texinfo File
173 * Printing Indices & Menus:: How to print an index in hardcopy and
174 generate index menus in Info.
175 * Contents:: How to create a table of contents.
176 * File End:: How to mark the end of a file.
180 * Tree Structuring:: A manual is like an upside down tree ...
181 * Structuring Command Types:: How to divide a manual into parts.
182 * makeinfo top:: The `@top' command, part of the `Top' node.
184 * unnumbered & appendix::
185 * majorheading & chapheading::
187 * unnumberedsec appendixsec heading::
189 * unnumberedsubsec appendixsubsec subheading::
190 * subsubsection:: Commands for the lowest level sections.
191 * Raise/lower sections:: How to change commands' hierarchical level.
195 * Two Paths:: Different commands to structure
196 Info output and printed output.
197 * Node Menu Illustration:: A diagram, and sample nodes and menus.
198 * node:: Creating nodes, in detail.
199 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
200 * anchor:: Defining arbitrary cross-reference targets.
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:: Indicating program code.
250 * kbd:: Showing keyboard input.
251 * key:: Specifying keys.
252 * samp:: Showing a literal sequence of characters.
253 * var:: Indicating metasyntactic variables.
254 * env:: Indicating environment variables.
255 * file:: Indicating file names.
256 * command:: Indicating command names.
257 * option:: Indicating option names.
258 * dfn:: Specifying definitions.
259 * cite:: Referring to books not in the Info system.
260 * acronym:: Indicating acronyms.
261 * url:: Indicating a World Wide Web reference.
262 * email:: Indicating an electronic mail address.
266 * emph & strong:: How to emphasize text in Texinfo.
267 * Smallcaps:: How to use the small caps font.
268 * Fonts:: Various font commands for printed output.
270 Quotations and Examples
272 * Block Enclosing Commands:: Use different constructs for
274 * quotation:: How to write a quotation.
275 * example:: How to write an example in a fixed-width font.
276 * noindent:: How to prevent paragraph indentation.
277 * lisp:: How to illustrate Lisp code.
278 * small:: Forms for `@smallbook'.
279 * display:: How to write an example in the current font.
280 * format:: How to write an example that does not narrow
282 * exdent:: How to undo the indentation of a line.
283 * flushleft & flushright:: How to push text flushleft or flushright.
284 * cartouche:: How to draw cartouches around examples.
288 * Introducing Lists:: Texinfo formats lists for you.
289 * itemize:: How to construct a simple list.
290 * enumerate:: How to construct a numbered list.
291 * Two-column Tables:: How to construct a two-column table.
292 * Multi-column Tables:: How to construct generalized tables.
294 Making a Two-column Table
296 * table:: How to construct a two-column table.
297 * ftable vtable:: Automatic indexing for two-column tables.
298 * itemx:: How to put more entries in the first column.
302 * Multitable Column Widths:: Defining multitable column widths.
303 * Multitable Rows:: Defining multitable rows, with examples.
307 * Index Entries:: Choose different words for index entries.
308 * Predefined Indices:: Use different indices for different kinds
310 * Indexing Commands:: How to make an index entry.
311 * Combining Indices:: How to combine indices.
312 * New Indices:: How to define your own indices.
316 * syncodeindex:: How to merge two indices, using `@code'
317 font for the merged-from index.
318 * synindex:: How to merge two indices, using the
319 default font of the merged-to index.
323 * Braces Atsigns:: How to insert braces, `@'.
324 * Inserting Space:: How to insert the right amount of space
326 * Inserting Accents:: How to insert accents and special characters.
327 * Dots Bullets:: How to insert dots and bullets.
328 * TeX and copyright:: How to insert the TeX logo
329 and the copyright symbol.
330 * pounds:: How to insert the pounds currency symbol.
331 * minus:: How to insert a minus sign.
332 * math:: How to format a mathematical expression.
333 * Glyphs:: How to indicate results of evaluation,
334 expansion of macros, errors, etc.
335 * Footnotes:: How to include footnotes.
336 * Images:: How to include graphics.
338 Inserting @ and Braces
340 * Inserting An Atsign:: How to insert `@'.
341 * Inserting Braces:: How to insert `{' and `}'.
345 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
346 * Ending a Sentence:: Sometimes it does.
347 * Multiple Spaces:: Inserting multiple spaces.
348 * dmn:: How to format a dimension.
350 Inserting Ellipsis, Dots, and Bullets
352 * dots:: How to insert dots ...
353 * bullet:: How to insert a bullet.
355 Inserting TeX and the Copyright Symbol
357 * tex:: How to insert the TeX logo.
358 * copyright symbol:: How to use `@copyright'{}.
363 * result:: How to show the result of expression.
364 * expansion:: How to indicate an expansion.
365 * Print Glyph:: How to indicate printed output.
366 * Error Glyph:: How to indicate an error message.
367 * Equivalence:: How to indicate equivalence.
368 * Point Glyph:: How to indicate the location of point.
381 * Footnote Commands:: How to write a footnote in Texinfo.
382 * Footnote Styles:: Controlling how footnotes appear in Info.
384 Making and Preventing Breaks
386 * Break Commands:: Cause and prevent splits.
387 * Line Breaks:: How to force a single line to use two lines.
388 * - and hyphenation:: How to tell TeX about hyphenation points.
389 * w:: How to prevent unwanted line breaks.
390 * sp:: How to insert blank lines.
391 * page:: How to force the start of a new page.
392 * group:: How to prevent unwanted page breaks.
393 * need:: Another way to prevent unwanted page breaks.
397 * Def Cmd Template:: How to structure a description using a
399 * Optional Arguments:: How to handle optional and repeated arguments.
400 * deffnx:: How to group two or more `first' lines.
401 * Def Cmds in Detail:: All the definition commands.
402 * Def Cmd Conventions:: Conventions for writing definitions.
403 * Sample Function Definition::
405 The Definition Commands
407 * Functions Commands:: Commands for functions and similar entities.
408 * Variables Commands:: Commands for variables and similar entities.
409 * Typed Functions:: Commands for functions in typed languages.
410 * Typed Variables:: Commands for variables in typed languages.
411 * Abstract Objects:: Commands for object-oriented programming.
412 * Data Types:: The definition command for data types.
414 Conditionally Visible Text
416 * Conditional Commands:: Specifying text for HTML, Info, or TeX.
417 * Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
418 * Raw Formatter Commands:: Using raw TeX or HTML commands.
419 * set clear value:: Designating which text to format (for
420 all output formats); and how to set a
421 flag to a string that you can insert.
423 `@set', `@clear', and `@value'
425 * ifset ifclear:: Format a region if a flag is set.
426 * set value:: Expand a flag variable to a string.
427 * value Example:: An easy way to update edition information.
431 * documentlanguage:: Declaring the current language.
432 * documentencoding:: Declaring the input encoding.
434 Defining New Texinfo Commands
436 * Defining Macros:: Defining and undefining new commands.
437 * Invoking Macros:: Using a macro, once you've defined it.
438 * Macro Details:: Beyond basic macro usage.
439 * alias:: Command aliases.
440 * definfoenclose:: Customized highlighting.
442 Formatting and Printing Hardcopy
444 * Use TeX:: Use TeX to format for hardcopy.
445 * Format with tex/texindex:: How to format with explicit shell commands.
446 * Format with texi2dvi:: A simpler way to format.
447 * Print with lpr:: How to print.
448 * Within Emacs:: How to format and print from an Emacs shell.
449 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
450 * Compile-Command:: How to print using Emacs's compile command.
451 * Requirements Summary:: TeX formatting requirements summary.
452 * Preparing for TeX:: What to do before you use TeX.
453 * Overfull hboxes:: What are and what to do with overfull hboxes.
454 * smallbook:: How to print small format books and manuals.
455 * A4 Paper:: How to print on European A4 paper.
456 * pagesizes:: How to print with customized page sizes.
457 * Cropmarks and Magnification:: How to print marks to indicate the size
458 of pages and how to print scaled up output.
459 * PDF Output:: Portable Document Format output.
461 Creating and Installing Info Files
463 * Creating an Info File::
464 * Install an Info File::
466 Creating an Info File
468 * makeinfo advantages:: `makeinfo' provides better error checking.
469 * Invoking makeinfo:: How to run `makeinfo' from a shell.
470 * makeinfo options:: Specify fill-column and other options.
471 * Pointer Validation:: How to check that pointers point somewhere.
472 * makeinfo in Emacs:: How to run `makeinfo' from Emacs.
473 * texinfo-format commands:: Two Info formatting commands written
474 in Emacs Lisp are an alternative
476 * Batch Formatting:: How to format for Info in Emacs Batch mode.
477 * Tag and Split Files:: How tagged and split files help Info
479 * makeinfo html:: Generating HTML output.
481 Installing an Info File
483 * Directory File:: The top level menu for all Info files.
484 * New Info File:: Listing a new info file.
485 * Other Info Directories:: How to specify Info files that are
486 located in other directories.
487 * Installing Dir Entries:: How to specify what menu entry to add
488 to the Info directory.
489 * Invoking install-info:: `install-info' options.
493 * Inserting Permissions:: How to put permissions in your document.
494 * ifinfo Permissions:: Sample `ifinfo' copying permissions.
495 * Titlepage Permissions:: Sample Titlepage copying permissions.
499 * Using Include Files:: How to use the `@include' command.
500 * texinfo-multiple-files-update:: How to create and update nodes and
501 menus when using included files.
502 * Include File Requirements:: What `texinfo-multiple-files-update' expects.
503 * Sample Include File:: A sample outer file with included files
504 within it; and a sample included file.
505 * Include Files Evolution:: How use of the `@include' command
506 has changed over time.
510 * Headings Introduced:: Conventions for using page headings.
511 * Heading Format:: Standard page heading formats.
512 * Heading Choice:: How to specify the type of page heading.
513 * Custom Headings:: How to create your own headings and footings.
517 * makeinfo Preferred:: `makeinfo' finds errors.
518 * Debugging with Info:: How to catch errors with Info formatting.
519 * Debugging with TeX:: How to catch errors with TeX formatting.
520 * Using texinfo-show-structure:: How to use `texinfo-show-structure'.
521 * Using occur:: How to list all lines containing a pattern.
522 * Running Info-Validate:: How to find badly referenced nodes.
524 Finding Badly Referenced Nodes
526 * Using Info-validate:: How to run `Info-validate'.
527 * Unsplit:: How to create an unsplit file.
528 * Tagifying:: How to tagify a file.
529 * Splitting:: How to split a file manually.
531 Documentation is like sex: when it is good, it is very, very good;
532 and when it is bad, it is better than nothing. --Dick Brandon
535 File: texinfo.info, Node: Copying, Next: Overview, Prev: Top, Up: Top
537 Texinfo Copying Conditions
538 **************************
540 The programs currently being distributed that relate to Texinfo
541 include portions of GNU Emacs, plus other separate programs (including
542 `makeinfo', `info', `texindex', and `texinfo.tex'). These programs are
543 "free"; this means that everyone is free to use them and free to
544 redistribute them on a free basis. The Texinfo-related programs are
545 not in the public domain; they are copyrighted and there are
546 restrictions on their distribution, but these restrictions are designed
547 to permit everything that a good cooperating citizen would want to do.
548 What is not allowed is to try to prevent others from further sharing
549 any version of these programs that they might get from you.
551 Specifically, we want to make sure that you have the right to give
552 away copies of the programs that relate to Texinfo, that you receive
553 source code or else can get it if you want it, that you can change these
554 programs or use pieces of them in new free programs, and that you know
555 you can do these things.
557 To make sure that everyone has such rights, we have to forbid you to
558 deprive anyone else of these rights. For example, if you distribute
559 copies of the Texinfo related programs, you must give the recipients all
560 the rights that you have. You must make sure that they, too, receive or
561 can get the source code. And you must tell them their rights.
563 Also, for our own protection, we must make certain that everyone finds
564 out that there is no warranty for the programs that relate to Texinfo.
565 If these programs are modified by someone else and passed on, we want
566 their recipients to know that what they have is not what we distributed,
567 so that any problems introduced by others will not reflect on our
570 The precise conditions of the licenses for the programs currently
571 being distributed that relate to Texinfo are found in the General Public
572 Licenses that accompany them.
575 File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: Top
580 "Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system
581 that uses a single source file to produce both online information and
582 printed output. This means that instead of writing two different
583 documents, one for the online information and the other for a printed
584 work, you need write only one document. Therefore, when the work is
585 revised, you need revise only that one document.
589 * Reporting Bugs:: Submitting effective bug reports.
590 * Using Texinfo:: Create printed or online output.
591 * Info Files:: What is an Info file?
592 * Printed Books:: Characteristics of a printed book or manual.
593 * Formatting Commands:: @-commands are used for formatting.
594 * Conventions:: General rules for writing a Texinfo file.
595 * Comments:: Writing comments and ignored text in general.
596 * Minimum:: What a Texinfo file must have.
597 * Six Parts:: Usually, a Texinfo file has six parts.
598 * Short Sample:: A short sample Texinfo file.
599 * Acknowledgements and History:: Contributors and genesis.
602 File: texinfo.info, Node: Overview-Footnotes, Up: Overview
604 (1) The first syllable of "Texinfo" is pronounced like "speck", not
605 "hex". This odd pronunciation is derived from, but is not the same as,
606 the pronunciation of TeX. In the word TeX, the `X' is actually the
607 Greek letter "chi" rather than the English letter "ex". Pronounce TeX
608 as if the `X' were the last sound in the name `Bach'; but pronounce
609 Texinfo as if the `x' were a `k'. Spell "Texinfo" with a capital "T"
610 and the other letters in lower case.
613 File: texinfo.info, Node: Reporting Bugs, Next: Using Texinfo, Up: Overview
618 We welcome bug reports or suggestions for the Texinfo system, both
619 programs and documentation. Please email them to
620 <bug-texinfo@gnu.org>. You can get the latest version of Texinfo from
621 `ftp://ftp.gnu.org/gnu/texinfo/' and its mirrors worldwide.
623 For bug reports, please include enough information for the maintainers
624 to reproduce the problem. Generally speaking, that means:
626 * the version number of Texinfo and the program(s) or manual(s)
629 * hardware, operating system, and compiler versions.
631 * any unusual options you gave to `configure'.
633 * the contents of any input files necessary to reproduce the bug.
635 * a description of the problem and samples of any erroneous output.
637 * anything else that you think would be helpful.
639 When in doubt whether something is needed or not, include it. It's
640 better to include too much than to leave out something important.
642 Patches are most welcome; if possible, please make them with
643 `diff -c' (*note Overview: (diffutils)Top.) and include `ChangeLog'
644 entries (*note Change Log: (emacs)Change Log.).
646 When sending email, please do not encode or split the messages in any
647 way if possible; it's much easier to deal with one plain text message,
648 however large, than many small ones. GNU shar
649 (ftp://ftp.gnu.org/gnu/sharutils/) is a convenient way of packaging
650 multiple and/or binary files for email.
653 File: texinfo.info, Node: Using Texinfo, Next: Info Files, Prev: Reporting Bugs, Up: Overview
658 Using Texinfo, you can create a printed document with the normal
659 features of a book, including chapters, sections, cross references, and
660 indices. From the same Texinfo source file, you can create a
661 menu-driven, online Info file with nodes, menus, cross references, and
662 indices. You can also create from that same source file an HTML output
663 file suitable for use with a web browser. `The GNU Emacs Manual' is a
664 good example of a Texinfo file, as is this manual.
666 To make a printed document, you process a Texinfo source file with the
667 TeX typesetting program (but the Texinfo language is very different
668 from TeX's usual language, plain TeX). This creates a DVI file that
669 you can typeset and print as a book or report (*note Hardcopy::).
671 To output an Info file, process your Texinfo source with the
672 `makeinfo' utility or Emacs's `texinfo-format-buffer' command. You can
673 install the result in your Info tree (*note Install an Info File::).
675 To output an HTML file, process your Texinfo source with `makeinfo'
676 using the `--html' option. You can (for example) install the result on
679 If you are a programmer and would like to contribute to the GNU
680 project by implementing additional output formats for Texinfo, that
681 would be excellent. But please do not write a separate translator
682 texi2foo for your favorite format foo! That is the hard way to do the
683 job, and makes extra work in subsequent maintenance, since the Texinfo
684 language is continually being enhanced and updated. Instead, the best
685 approach is modify `makeinfo' to generate the new format, as it does
686 now for Info and HTML.
688 TeX works with virtually all printers; Info works with virtually all
689 computer terminals; the HTML output works with virtually all web
690 browsers. Thus Texinfo can be used by almost any computer user.
692 A Texinfo source file is a plain ASCII file containing text and
693 "@-commands" (words preceded by an `@') that tell the typesetting and
694 formatting programs what to do. You may edit a Texinfo file with any
695 text editor; but it is especially convenient to use GNU Emacs since
696 that editor has a special mode, called Texinfo mode, that provides
697 various Texinfo-related features. (*Note Texinfo Mode::.)
699 Before writing a Texinfo source file, you should learn about nodes,
700 menus, cross references, and the rest, for example by reading this
703 You can use Texinfo to create both online help and printed manuals;
704 moreover, Texinfo is freely redistributable. For these reasons, Texinfo
705 is the official documentation format of the GNU project. More
706 information is available at the GNU documentation web page
707 (http://www.gnu.org/doc/).
709 From time to time, proposals are made to generate traditional Unix man
710 pages from Texinfo source. This is not likely to ever be supported,
711 because man pages have a very strict conventional format. Merely
712 enhancing `makeinfo' to output troff format would be insufficient.
713 Generating a good man page therefore requires a completely different
714 source than the typical Texinfo applications of generating a good user
715 manual or a good reference manual. This makes generating man pages
716 incompatible with the Texinfo design goal of not having to document the
717 same information in different ways for different output formats. You
718 might as well just write the man page directly.
720 If you wish to support man pages, the program `help2man' may be
721 useful; it generates a traditional man page from the `--help' output of
722 a program. In fact, this is currently used to generate man pages for
723 the Texinfo programs themselves. It is free software written by
724 Brendan O'Dea, available from
725 `http://www.ozemail.com.au/~bod/help2man.tar.gz'.
728 File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Using Texinfo, Up: Overview
733 An Info file is a Texinfo file formatted so that the Info
734 documentation reading program can operate on it. (`makeinfo' and
735 `texinfo-format-buffer' are two commands that convert a Texinfo file
738 Info files are divided into pieces called "nodes", each of which
739 contains the discussion of one topic. Each node has a name, and
740 contains both text for the user to read and pointers to other nodes,
741 which are identified by their names. The Info program displays one node
742 at a time, and provides commands with which the user can move to other
745 *note info: (info)Top, for more information about using Info.
747 Each node of an Info file may have any number of child nodes that
748 describe subtopics of the node's topic. The names of child nodes are
749 listed in a "menu" within the parent node; this allows you to use
750 certain Info commands to move to one of the child nodes. Generally, an
751 Info file is organized like a book. If a node is at the logical level
752 of a chapter, its child nodes are at the level of sections; likewise,
753 the child nodes of sections are at the level of subsections.
755 All the children of any one parent are linked together in a
756 bidirectional chain of `Next' and `Previous' pointers. The `Next'
757 pointer provides a link to the next section, and the `Previous' pointer
758 provides a link to the previous section. This means that all the nodes
759 that are at the level of sections within a chapter are linked together.
760 Normally the order in this chain is the same as the order of the
761 children in the parent's menu. Each child node records the parent node
762 name as its `Up' pointer. The last child has no `Next' pointer, and the
763 first child has the parent both as its `Previous' and as its `Up'
764 pointer.(1) (*note Info Files-Footnote-1::)
766 The book-like structuring of an Info file into nodes that correspond
767 to chapters, sections, and the like is a matter of convention, not a
768 requirement. The `Up', `Previous', and `Next' pointers of a node can
769 point to any other nodes, and a menu can contain any other nodes.
770 Thus, the node structure can be any directed graph. But it is usually
771 more comprehensible to follow a structure that corresponds to the
772 structure of chapters and sections in a printed book or report.
774 In addition to menus and to `Next', `Previous', and `Up' pointers,
775 Info provides pointers of another kind, called references, that can be
776 sprinkled throughout the text. This is usually the best way to
777 represent links that do not fit a hierarchical structure.
779 Usually, you will design a document so that its nodes match the
780 structure of chapters and sections in the printed output. But
781 occasionally there are times when this is not right for the material
782 being discussed. Therefore, Texinfo uses separate commands to specify
783 the node structure for the Info file and the section structure for the
786 Generally, you enter an Info file through a node that by convention is
787 named `Top'. This node normally contains just a brief summary of the
788 file's purpose, and a large menu through which the rest of the file is
789 reached. From this node, you can either traverse the file
790 systematically by going from node to node, or you can go to a specific
791 node listed in the main menu, or you can search the index menus and then
792 go directly to the node that has the information you want.
793 Alternatively, with the standalone Info program, you can specify
794 specific menu items on the command line (*note Top: (info)Top.).
796 If you want to read through an Info file in sequence, as if it were a
797 printed manual, you can hit <SPC> repeatedly, or you get the whole file
798 with the advanced Info command `g *'. (*note Advanced Info commands:
801 The `dir' file in the `info' directory serves as the departure point
802 for the whole Info system. From it, you can reach the `Top' nodes of
803 each of the documents in a complete Info system.
805 If you wish to refer to an Info file in a URI, you can use the
806 (unofficial) syntax exemplified in the following. This works with
807 Emacs/W3, for example:
808 info:///usr/info/emacs#Dissociated%20Press
809 info:emacs#Dissociated%20Press
810 info://localhost/usr/info/emacs#Dissociated%20Press
812 The `info' program itself does not follow URI's of any kind.
815 File: texinfo.info, Node: Info Files-Footnotes, Up: Info Files
817 (1) In some documents, the first child has no `Previous' pointer.
818 Occasionally, the last child has the node name of the next following
819 higher level node as its `Next' pointer.
822 File: texinfo.info, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview
827 A Texinfo file can be formatted and typeset as a printed book or
828 manual. To do this, you need TeX, a powerful, sophisticated typesetting
829 program written by Donald Knuth.(1) (*note Printed Books-Footnote-1::)
831 A Texinfo-based book is similar to any other typeset, printed work: it
832 can have a title page, copyright page, table of contents, and preface,
833 as well as chapters, numbered or unnumbered sections and subsections,
834 page headers, cross references, footnotes, and indices.
836 You can use Texinfo to write a book without ever having the intention
837 of converting it into online information. You can use Texinfo for
838 writing a printed novel, and even to write a printed memo, although
839 this latter application is not recommended since electronic mail is so
842 TeX is a general purpose typesetting program. Texinfo provides a
843 file `texinfo.tex' that contains information (definitions or "macros")
844 that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells
845 TeX how to convert the Texinfo @-commands to TeX commands, which TeX
846 can then process to create the typeset document.) `texinfo.tex'
847 contains the specifications for printing a document. You can get the
848 latest version of `texinfo.tex' from
849 `ftp://ftp.gnu.org/gnu/texinfo.tex'.
851 Most often, documents are printed on 8.5 inch by 11 inch pages (216mm
852 by 280mm; this is the default size), but you can also print for 7 inch
853 by 9.25 inch pages (178mm by 235mm; the `@smallbook' size) or on
854 European A4 size paper (`@afourpaper'). (*Note Printing "Small" Books:
855 smallbook. Also, see *Note Printing on A4 Paper: A4 Paper.)
857 By changing the parameters in `texinfo.tex', you can change the size
858 of the printed document. In addition, you can change the style in
859 which the printed document is formatted; for example, you can change the
860 sizes and fonts used, the amount of indentation for each paragraph, the
861 degree to which words are hyphenated, and the like. By changing the
862 specifications, you can make a book look dignified, old and serious, or
863 light-hearted, young and cheery.
865 TeX is freely distributable. It is written in a superset of Pascal
866 called WEB and can be compiled either in Pascal or (by using a
867 conversion program that comes with the TeX distribution) in C. (*Note
868 TeX Mode: (emacs)TeX Mode, for information about TeX.)
870 TeX is very powerful and has a great many features. Because a
871 Texinfo file must be able to present information both on a
872 character-only terminal in Info form and in a typeset book, the
873 formatting commands that Texinfo supports are necessarily limited.
875 To get a copy of TeX, see *Note How to Obtain TeX: Obtaining TeX.
878 File: texinfo.info, Node: Printed Books-Footnotes, Up: Printed Books
880 (1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz)
881 program if you do not have TeX; since Texinfo is designed for use with
882 TeX, `texi2roff' is not described here. `texi2roff' is not part of the
883 standard GNU distribution and is not maintained or up-to-date with all
884 the Texinfo features described in this manual.
887 File: texinfo.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview
892 In a Texinfo file, the commands that tell TeX how to typeset the
893 printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
894 create an Info file are preceded by `@'; they are called "@-commands".
895 For example, `@node' is the command to indicate a node and `@chapter'
896 is the command to indicate the start of a chapter.
898 *Please note:* All the @-commands, with the exception of the
899 `@TeX{}' command, must be written entirely in lower case.
901 The Texinfo @-commands are a strictly limited set of constructs. The
902 strict limits make it possible for Texinfo files to be understood both
903 by TeX and by the code that converts them into Info files. You can
904 display Info files on any terminal that displays alphabetic and numeric
905 characters. Similarly, you can print the output generated by TeX on a
906 wide variety of printers.
908 Depending on what they do or what arguments(1) (*note Formatting
909 Commands-Footnote-1::) they take, you need to write @-commands on lines
910 of their own or as part of sentences:
912 * Write a command such as `@noindent' at the beginning of a line as
913 the only text on the line. (`@noindent' prevents the beginning of
914 the next line from being indented as the beginning of a paragraph.)
916 * Write a command such as `@chapter' at the beginning of a line
917 followed by the command's arguments, in this case the chapter
918 title, on the rest of the line. (`@chapter' creates chapter
921 * Write a command such as `@dots{}' wherever you wish but usually
922 within a sentence. (`@dots{}' creates dots ...)
924 * Write a command such as `@code{SAMPLE-CODE}' wherever you wish
925 (but usually within a sentence) with its argument, SAMPLE-CODE in
926 this example, between the braces. (`@code' marks text as being
929 * Write a command such as `@example' on a line of its own; write the
930 body-text on following lines; and write the matching `@end'
931 command, `@end example' in this case, at the on a line of its own
932 after the body-text. (`@example' ... `@end example' indents and
933 typesets body-text as an example.) It's usually ok to indent
934 environment commands like this, but in complicated and
935 hard-to-define circumstances the extra spaces cause extra space to
936 appear in the output, so beware.
938 As a general rule, a command requires braces if it mingles among other
939 text; but it does not need braces if it starts a line of its own. The
940 non-alphabetic commands, such as `@:', are exceptions to the rule; they
943 As you gain experience with Texinfo, you will rapidly learn how to
944 write the different commands: the different ways to write commands make
945 it easier to write and read Texinfo files than if all commands followed
946 exactly the same syntax. (For details about @-command syntax, see
947 *Note @-Command Syntax: Command Syntax.)
950 File: texinfo.info, Node: Formatting Commands-Footnotes, Up: Formatting Commands
952 (1) The word "argument" comes from the way it is used in mathematics
953 and does not refer to a dispute between two people; it refers to the
954 information presented to the command. According to the `Oxford English
955 Dictionary', the word derives from the Latin for "to make clear,
956 prove"; thus it came to mean `the evidence offered as proof', which is
957 to say, `the information offered', which led to its mathematical
958 meaning. In its other thread of derivation, the word came to mean `to
959 assert in a manner against which others may make counter assertions',
960 which led to the meaning of `argument' as a dispute.
963 File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview
965 General Syntactic Conventions
966 =============================
968 This section describes the general conventions used in all Texinfo
971 * All printable ASCII characters except `@', `{' and `}' can appear
972 in a Texinfo file and stand for themselves. `@' is the escape
973 character which introduces commands. `{' and `}' should be used
974 only to surround arguments to certain commands. To put one of
975 these special characters into the document, put an `@' character
976 in front of it, like this: `@@', `@{', and `@}'.
978 * It is customary in TeX to use doubled single-quote characters to
979 begin and end quotations: ` ` and ' ' (but without a space between
980 the two single-quote characters). This convention should be
981 followed in Texinfo files. TeX converts doubled single-quote
982 characters to left- and right-hand doubled quotation marks and
983 Info converts doubled single-quote characters to ASCII
984 double-quotes: ` ` and ' ' to " .
986 * Use three hyphens in a row, `---', for a dash--like this. In TeX,
987 a single or double hyphen produces a printed dash that is shorter
988 than the usual typeset dash. Info reduces three hyphens to two for
989 display on the screen.
991 * To prevent a paragraph from being indented in the printed manual,
992 put the command `@noindent' on a line by itself before the
995 * If you mark off a region of the Texinfo file with the `@iftex' and
996 `@end iftex' commands, that region will appear only in the printed
997 copy; in that region, you can use certain commands borrowed from
998 plain TeX that you cannot use in Info. Likewise, if you mark off
999 a region with the `@ifinfo' and `@end ifinfo' commands, that
1000 region will appear only in the Info file; in that region, you can
1001 use Info commands that you cannot use in TeX. Similarly for
1002 `@ifhtml ... @end ifhtml', `@ifnothtml ... @end ifnothtml',
1003 `@ifnotinfo ... @end ifnotinfo', `@ifnottex ... @end ifnottex'.
1004 *Note Conditionals::.
1006 *Caution:* Do not use tabs in a Texinfo file! TeX uses
1007 variable-width fonts, which means that it cannot predefine a tab
1008 to work in all circumstances. Consequently, TeX treats tabs like
1009 single spaces, and that is not what they look like. Furthermore,
1010 `makeinfo' does nothing special with tabs, and thus a tab character
1011 in your input file may appear differently in the output.
1013 To avoid this problem, Texinfo mode causes GNU Emacs to insert
1014 multiple spaces when you press the <TAB> key.
1016 Also, you can run `untabify' in Emacs to convert tabs in a region
1020 File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview
1025 You can write comments in a Texinfo file that will not appear in
1026 either the Info file or the printed manual by using the `@comment'
1027 command (which may be abbreviated to `@c'). Such comments are for the
1028 person who revises the Texinfo file. All the text on a line that
1029 follows either `@comment' or `@c' is a comment; the rest of the line
1030 does not appear in either the Info file or the printed manual. (Often,
1031 you can write the `@comment' or `@c' in the middle of a line, and only
1032 the text that follows after the `@comment' or `@c' command does not
1033 appear; but some commands, such as `@settitle' and `@setfilename', work
1034 on a whole line. You cannot use `@comment' or `@c' in a line beginning
1035 with such a command.)
1037 You can write long stretches of text that will not appear in either
1038 the Info file or the printed manual by using the `@ignore' and `@end
1039 ignore' commands. Write each of these commands on a line of its own,
1040 starting each command at the beginning of the line. Text between these
1041 two commands does not appear in the processed output. You can use
1042 `@ignore' and `@end ignore' for writing comments. Often, `@ignore' and
1043 `@end ignore' is used to enclose a part of the copying permissions that
1044 applies to the Texinfo source file of a document, but not to the Info
1045 or printed version of the document.
projects / chise / xemacs-chise.git.1 / blob