![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to texinfo.texinfo CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man|
Return to texinfo.texinfo CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2: @comment %**start of header (This is for running Texinfo on a region.)
3: @setfilename ../info/texinfo
4: @settitle Texinfo 1.1
5: @comment %**end of header (This is for running Texinfo on a region.)
6:
7: @iftex
8: @finalout
9: @end iftex
10:
11: @ifinfo
12: This file documents Texinfo, a documentation system that uses a single
13: source file to produce both on-line help and a printed manual.
14:
15: This is edition 1.1 of the Texinfo documentation, and is for the Texinfo
16: that is distributed as part of Version 18 of GNU Emacs.
17:
18: Copyright (C) 1988 Free Software Foundation, Inc.
19:
20: Permission is granted to make and distribute verbatim copies of
21: this manual provided the copyright notice and this permission notice
22: are preserved on all copies.
23:
24: @ignore
25: Permission is granted to process this file through TeX and print the
26: results, provided the printed document carries copying permission
27: notice identical to this one except for the removal of this paragraph
28: (this paragraph not being relevant to the printed manual).
29:
30: @end ignore
31: Permission is granted to copy and distribute modified versions of this
32: manual under the conditions for verbatim copying, provided that the entire
33: resulting derived work is distributed under the terms of a permission
34: notice identical to this one.
35:
36: Permission is granted to copy and distribute translations of this manual
37: into another language, under the above conditions for modified versions,
38: except that this permission notice may be stated in a translation approved
39: by the Foundation.
40: @end ifinfo
41:
42: @setchapternewpage odd
43: @titlepage
44: @sp 11
45: @center @titlefont{Texinfo}
46: @sp 2
47: @center The GNU Documentation Format
48: @sp 2
49: @center by Richard M. Stallman and Robert J. Chassell
50: @sp 2
51: @center Edition 1.1
52: @sp 2
53: @center May 1988
54:
55: @comment Include the Distribution inside the titlepage environment so
56: @c that headings are turned off.
57:
58: @page
59: @vskip 0pt plus 1filll
60: Copyright @copyright{} 1988 Free Software Foundation, Inc.
61:
62: @sp 2
63: This is version 1.1 of the Texinfo documentation, and is for @*
64: the Texinfo that is distributed as part of Version 18 of GNU Emacs.
65: @sp 2
66:
67: Published by the Free Software Foundation @*
68: 675 Massachusetts Avenue, @*
69: Cambridge, MA 02139 USA @*
70: Printed copies are available for $10 each.
71:
72: Permission is granted to make and distribute verbatim copies of
73: this manual provided the copyright notice and this permission notice
74: are preserved on all copies.
75:
76: Permission is granted to copy and distribute modified versions of this
77: manual under the conditions for verbatim copying, provided that the entire
78: resulting derived work is distributed under the terms of a permission
79: notice identical to this one.
80:
81: Permission is granted to copy and distribute translations of this manual
82: into another language, under the above conditions for modified versions,
83: except that this permission notice may be stated in a translation approved
84: by the Foundation.
85:
86: @end titlepage
87:
88:
89: @node Top, License, (dir), (dir)
90:
91: @menu
92: * License:: Licensing information.
93: * Overview:: What is Texinfo?
94: * Texinfo Mode:: Special features in GNU Emacs.
95: * Beginning a File:: What to put at the beginning of a Texinfo file.
96: * Ending a File:: What to put at the end of a Texinfo file.
97: * Structuring:: How to make nodes and chapters.
98: * Quotations and Examples:: How to insert quotations and examples.
99: * Lists and Tables:: How to make lists and tables.
100: * Cross References:: How to make cross references.
101: * Formatting Paragraphs:: How to format paragraphs.
102: * Marking Text:: How to mark code, definitions, variables etc.
103: * Conditionals:: Putting text in only Info or the printed work.
104: * Printing Hardcopy:: How to print a hardcopy of the manual.
105: * Creating an Info File:: How to create an on-line Info file.
106: * Catching Mistakes:: How to find problems.
107:
108: Indices, nodes containing large menus
109:
110: * Command Index:: An item for each @@-command.
111: * Concept Index:: An item for each concept.
112:
113: A detailed node listing
114:
115: Overview
116: * Info File:: Characteristics of the Info file.
117: * Printed Manual:: Characteristics of the printed manual.
118: * Conventions:: General syntactic conventions.
119: * Short Sample:: A short sample Texinfo file.
120:
121: Using Texinfo Mode
122: * Info on a Region:: Formatting a region for Info.
123: * Showing the Structure:: Showing the structure of a file.
124: * Inserting:: Inserting frequently used commands.
125:
126: Beginning a Texinfo File.
127: * First Line:: The first line of a Texinfo file.
128: * Start-of-Header:: Identifying the start of the header.
129: * Setfilename:: Specifying the name of the Info file.
130: * Settitle:: Specifying the title used by the headings.
131: * Setchapternewpage:: Starting chapters on odd numbered pages.
132: * Titlepage:: The title and copyright page.
133: * Center:: Centering a line.
134: * Copyright & Printed Permissions:: Ensuring free distributability.
135: * Top Node:: The master menu.
136: * License and Distribution:: Your are free to copy and distribute this.
137:
138: Ending a Texinfo File
139: * Contents:: Generating tables of contents.
140: * Indices:: Generating indices.
141: * Index Entries:: Defining the entries of an index.
142: * Combining Indices:: Putting two or more indices together.
143: * Printing Indices & Menus:: Printing an index and generating menus.
144:
145: Node and Chapter Structuring
146: * Chapter:: Creating a chapter.
147: * Unnumbered and Appendix:: Chapter-like parts.
148: * Section:: Creating sections
149: * Subsection:: Creating subsections.
150: * Subsubsection:: Creating subsubsections.
151:
152: * Node:: Creating nodes.
153: * Menu:: Creating menus.
154:
155:
156: Making quotations and examples
157: * Quotation:: Inserting long quotations.
158: * Example:: Inserting examples of code and the like.
159: * Display:: Inserting displayed text.
160:
161: Making lists and two column tables
162: * Itemize:: Creating itemized lists.
163: * Enumerate:: Creating enumerated lists.
164: * Table:: Creating two column tables.
165: * Itemx:: Putting an extra item in the
166: first column of a table.
167:
168: Making Cross References
169: * Xref:: Making a regular cross reference.
170: * Pxref:: Making a parenthetical cross reference.
171: * Inforef:: Making a cross reference to an Info file.
172:
173:
174: Formatting Paragraphs
175: * Refilling & Noindent:: Refilling paragraphs
176: and preventing indentation
177: * Refill:: Using the @code{@@refill} command.
178: * Noindent:: Using the @code{@@noindent} command.
179:
180:
181: Breaks, Blank Lines and Groups
182: * Line Breaks:: Inserting line breaks in @TeX{}.
183: * Sp:: Inserting blank lines.
184: * Br:: Inserting paragraph breaks.
185: * W:: Preventing line breaks.
186: * Page:: Starting new pages.
187: * Group:: Holding text together on one page.
188: * Need:: Keeping text together.
189:
190: Marking Text Within a Paragraph
191: * Code:: A literal example of a piece of a program.
192: * Samp:: A literal example of a sequence of characters.
193: * File:: The name of a file.
194: * Kbd:: The names of keys or else characters you type.
195: * Key:: The conventional name for a key on a keyboard.
196: * Ctrl:: Indicates the ASCII control character.
197: * Var:: A variable.
198: * Dfn:: The introductory or defining use of a term.
199: * Cite:: The name of a book.
200:
201: Inserting Braces, @samp{@@} and Periods
202: * Braces Atsigns Periods:: Inserting braces, @samp{@@} and periods.
203: * Dots Bullets Tex:: Inserting dots, bullets and the @TeX{} logo
204: * Emphasis:: Emphasizing text.
205:
206: Emphasizing Text
207: * Emph and Strong:: Emphasizing text.
208: * Fonts:: Selecting italic, bold or typewriter fonts.
209:
210: Creating an Info File
211: * Installing an Info File:: Putting the Info file in the
212: @file{info} directory.
213:
214: Catching Mistakes
215: * Debugging with Info:: Catching errors with info formatting.
216: * Using the Emacs Lisp Debugger:: Using the Emacs Lisp Debugger
217: * Debugging with Tex:: Catching errors with @TeX{} formatting.
218: * Using texinfo-show-structure:: Using @code{texinfo-show-structure}
219: to catch mistakes.
220: * Using Occur:: Using @code{occur} to catch mistakes.
221: * Running Info-Validate:: Checking for unreferenced nodes.
222:
223: Finding badly referenced nodes
224: * Info-Validating a Large File:: Running @code{Info-validate}
225: on a large file.
226: * Splitting:: Splitting a file manually.
227:
228: Appendices
229: * Command Syntax:: Details about the syntax.
230: * Include Files:: Making one printed file out of
231: several Info files.
232: * TeX Input:: Where @TeX{} finds its @samp{\input} file.
233: * Sample Permissions:: You may copy GNU Software.
234: * Ifinfo Permissions:: What to put in the `ifinfo' section.
235: * Titlepage Permissions:: What to put in the `@@titlepage' section.
236: @end menu
237:
238: @node License, Overview, Top, Top
239: @comment node-name, next, previous, up
240: @unnumbered Licensing Information
241:
242: The programs currently being distributed that relate to Texinfo
243: include two portions of GNU Emacs, plus two other separate programs
244: (@code{texindex} and @code{texinfo.tex}). These programs are
245: @dfn{free}; this means that everyone is free to use them and free to
246: redistribute them on a free basis. The Texinfo related programs are not
247: in the public domain; they are copyrighted and there are restrictions on
248: their distribution, but these restrictions are designed to permit
249: everything that a good cooperating citizen would want to do. What is
250: not allowed is to try to prevent others from further sharing any version
251: of these programs that they might get from you.
252:
253: Specifically, we want to make sure that you have the right to give
254: away copies of the programs that relate to Texinfo, that you receive
255: source code or else can get it if you want it, that you can change these
256: programs or use pieces of them in new free programs, and that you know
257: you can do these things.
258:
259: To make sure that everyone has such rights, we have to forbid you to
260: deprive anyone else of these rights. For example, if you distribute
261: copies of the Texinfo related programs, you must give the recipients all
262: the rights that you have. You must make sure that they, too, receive or
263: can get the source code. And you must tell them their rights.
264:
265: Also, for our own protection, we must make certain that everyone finds
266: out that there is no warranty for the programs that relate to Texinfo.
267: If these programs are modified by someone else and passed on, we want
268: their recipients to know that what they have is not what we distributed,
269: so that any problems introduced by others will not reflect on our
270: reputation.
271:
272: The precise conditions of the licenses for the programs currently
273: being distributed that relate to Texinfo are found in the General Public
274: Licenses that accompany them. The programs that are part of GNU Emacs
275: are covered by the GNU Emacs copying terms (@pxref{License, , , emacs,
276: The GNU Emacs Manual}), and other programs are covered by licenses that
277: are contained in their source files.
278:
279: @node Overview, Texinfo Mode, License, Top
280: @comment node-name, next, previous, up
281: @chapter Overview of Texinfo
282: @cindex Overview of Texinfo
283: @cindex Texinfo overview
284:
285: Texinfo is a documentation system that uses a single source file for both
286: on-line help and a printed manual. This means that instead of writing two
287: different documents, one for the on-line help and the other for the printed
288: manual, only one document needs to be written. When the system is revised,
289: only one file has to be revised.@refill
290:
291: Using Texinfo, you can create a document with the normal features of a book
292: such as chapters, sections, cross references and indices. The chapters and
293: sections of the printed manual can be made to correspond to the nodes of
294: the on-line help. The cross references and indices can be used in both the
295: on-line help and in the printed document. Indices are generated
296: semi-automatically. The @cite{GNU Emacs Manual} is a good example of a
297: Texinfo file.@refill
298:
299: To make the printed manual, the Texinfo source file is processed by the
300: @TeX{} typesetting program; the resulting DVI file can be typeset and
301: printed as a book. To make the on-line help, the Texinfo source file is by
302: processed the @kbd{M-x texinfo-format-buffer} command; the resulting Info
303: file is installed in the @file{info} directory.@refill
304:
305: Since the Texinfo source file is used for a dual task---to create both the
306: on-line help and the printed manual---it must be written in a special
307: format that uses @@-commands (words preceded by an @samp{@@}) to indicate
308: chapters, sections, nodes, examples, index entries and the like.@refill
309:
310: Before writing a Texinfo source file, you should be familiar with the
311: on-line Info documentation reading program. (@inforef{Info, info, info},
312: for more information.) If you are writing a document that will be both
313: on-line and printed, you will need both Info and @TeX{}.
314:
315: To make an Info file, you use the @kbd{M-x texinfo-format-buffer} command
316: in GNU Emacs.@refill
317:
318: To make a printed manual, you need to use @TeX{}, a powerful,
319: sophisticated typesetting program written by Donald Knuth. @TeX{} is
320: freely distributable. It is written in a dialect of Pascal called WEB and
321: can be compiled either in Pascal or (by using a conversion program that
322: comes with the @TeX{} distribution) in C. (For information about getting
323: @TeX{}, @pxref{TeX Mode, , , emacs, The GNU Emacs Manual})
324:
325: When @TeX{} processes a Texinfo source file, @TeX{} makes use of a macro
326: definitions file called @file{texinfo.tex} that comes with the GNU Emacs
327: distribution in the @file{emacs/man} sources directory. (The first line of
328: every Texinfo file has a command that says @code{\input texinfo}; this
329: tells @TeX{} to use the @file{texinfo.tex} file.)@refill
330:
331: If the @file{texinfo.tex} file has not already been copied to the directory
332: which contains the other @TeX{} macro definition files when Emacs was
333: installed, you will probably want to copy it to that directory. Usually,
334: this is the @file{/usr/lib/tex/macros} directory. For more information,
335: @pxref{TeX Input, , @TeX{} Input Initialization}
336:
337: Documentation for GNU utilities and libraries should be written in Texinfo
338: format.
339:
340: @menu
341: * Info File:: Characteristics of the Info file.
342: * Printed Manual:: Characteristics of the Printed Manual.
343: * Conventions:: General Syntactic Conventions.
344: * Short Sample:: A short sample Texinfo file.
345: @end menu
346:
347: @node Info File, Printed Manual, , Overview
348: @comment node-name, next, previous, up
349: @section Characteristics of the Info file
350: @cindex Characteristics of the Info file
351: @cindex Info file characteristics
352:
353: A Texinfo file can be transformed into a printed manual and an on-line Info
354: file.
355:
356: An on-line Info file is a file formatted so that the Info documentation
357: reading program can operate on it. Info files are divided into pieces
358: called @dfn{nodes}, each of which contains the discussion of one topic.
359: Each node has a name, and contains both text for the user to read and
360: pointers to other nodes, which are identified by their names. The Info
361: program displays one node at a time, and provides commands with which the
362: user can move to the other nodes to which the current node points.
363:
364: @ifinfo
365: @inforef{Info, info, info}, for more information about using Info.
366: @end ifinfo
367:
368: Normally, most of the nodes are arranged in a tree which branches down.
369: Each node may have any number of child nodes that describe subtopics of the
370: node's topic. The names of these child nodes, if any, are listed in a
371: @dfn{menu} within the parent node; this allows certain Info commands to
372: be used to move to one of the child nodes. Each child node records the
373: parent node name, as its `Up' pointer. Thus, if a node were at the logical
374: level of a `chapter', its child nodes would be `sections'; likewise,
375: the child nodes of a section would be subsections.
376:
377: The root of the tree is the top node of the file, through which users
378: enter the file from the Info directory. By convention, this node is always
379: called @samp{Top}. This node normally contains just a brief summary of the
380: file's purpose, and a large menu through which the rest of the file is
381: reached.
382:
383: Generally you enter the Info file from the top; then you can either traverse
384: the file systematically by going from node to node or you can search large
385: menus that correspond to indices and go directly to the node that has the
386: information you want.
387:
388: If you want to read through an Info file in sequence, as if it were a
389: printed manual, you can get the whole file with the advanced Info command
390: @kbd{g *}. (@inforef{Expert, info, info}.)@refill
391:
392: All the children of any one parent are linked together in a bidirectional
393: chain of `Next' and `Previous' pointers. This means that all the nodes
394: that are logically parallel to sections within a chapter are all linked
395: together. Normally the order in this chain is the same as the order of the
396: children in the parent's menu. The last child has no `Next' pointer, and
397: the first child normally has the parent as its `Previous' pointer (as well
398: as its `Up' pointer, of course).
399:
400: Structuring the nodes in a tree is a matter of convention, not a
401: requirement. In fact, the `Up', `Previous' and `Next' pointers of a node
402: can point to any other nodes, and the menu can contain any other nodes.
403: The structure of nodes can be any directed graph. But it is usually more
404: comprehensible to make it a tree. Info provides another kind of pointer
405: between nodes, called a reference, that can be sprinkled through the text
406: of a node. This is usually the best way to represent links that do not fit
407: the tree structure.
408:
409: Most often the nodes fall into a strict tree structure that corresponds to
410: the structure of chapters and sections in the printed
411: manual. But there are times when this is not right for the material being
412: discussed. Therefore, Texinfo uses separate commands to specify the node
413: structure of the Info file and the section structure of the printed manual.
414: Also, Texinfo requires that you specify menus explicitly, rather than
415: generate them automatically based on an assumed tree structure.
416:
417: @node Printed Manual, Conventions, Info File, Top
418: @comment node-name, next, previous, up
419: @section Characteristics of the Printed Manual
420: @cindex Printed manual characteristics
421: @cindex Characteristics, printed manual
422:
423: A Texinfo file can be formatted and typeset as a printed manual. The
424: printed manual will be the same as any other book; it will have a title
425: page, copyright page, table of contents, and preface as you would expect,
426: as well as chapters, numbered or unnumbered sections and subsections, not
427: to mention page headers, cross references and indices.
428:
429: Texinfo can be used for writing a book without ever having the intention of
430: converting it into on-line help. Texinfo can be used for writing a novel;
431: and it can even be used to write a memo, although this application is not
432: recommended since electronic mail is so much easier.
433:
434: Texinfo uses the formatting language called @TeX{} for typesetting. A file
435: called @file{texinfo.tex} contains information (definitions or
436: @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. (The
437: macros tell @TeX{} how to convert the Texinfo @@-commands to @TeX{}
438: commands which @TeX{} can then process to create the typeset document.)
439: @file{texinfo.tex} contains the specifications for printing a document,
440: either with 7 inch by 9.25 inch pages or with 8.5 inch by 11 inch pages.
441: (This is 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
442: parameters in @file{texinfo.tex} you can easily change the size of the
443: printed document. In addition, you can readily change the style in which
444: the printed document is formatted; for example, you can change the sizes and
445: fonts used, the amount of indentation for each paragraph, the degree to
446: which words are hyphenated, and the like. By changing the specifications,
447: you can make a book look dignified, old and serious, or light-hearted,
448: young and cheery.@refill
449:
450: @TeX{} is very powerful and has a great many features. Because a Texinfo
451: file must be able to present information both on a character-only terminal
452: in Info form and in a typeset book, the commands that Texinfo supports are
453: necessarily limited.
454:
455:
456: @node Conventions, Short Sample, Printed Manual, Overview
457: @comment node-name, next, previous, up
458: @section General Syntactic Conventions
459: @cindex General syntactic conventions
460: @cindex Syntactic conventions
461: @cindex Conventions, syntactic
462:
463:
464: Texinfo files contain a strictly limited set of constructs. The strict
465: limits make it possible for Texinfo files to be understood both by @TeX{}
466: and by the code which converts them into Info files.
467:
468: All ASCII printing characters except @samp{@@}, @samp{@{} and @samp{@}} can
469: appear in body text in a Texinfo file and stand for themselves. @samp{@@}
470: is the escape character which introduces commands. @samp{@{} and @samp{@}}
471: should be used only to surround arguments to certain commands. @samp{@{}
472: and @samp{@}} appearing anywhere else will be treated by @TeX{} as a
473: grouping but treated by the code that produces an Info file as themselves;
474: this inconsistency is undesirable, so don't let it occur. To put one of
475: these special characters into the document, put an @samp{@@} character in
476: front of it. For example, you would insert @samp{@@@@}, @samp{@@@{}, and
477: @samp{@@@}}.@refill
478:
479: It is customary in @TeX{} to use doubled single-quote characters to begin
480: and end quotations, @samp{``} like these @samp{''}. This convention should
481: be followed in Texinfo files. Also, three hyphens in a row, @samp{---},
482: are used for a dash---like this. In @TeX{}, a single or even a double
483: hyphen produces a dash that is shorter than you want.@refill
484:
485: @comment Remove for version 19
486:
487: @TeX{} ignores the line-breaks in the input text, except for blank lines,
488: which separate paragraphs. Info generally preserves the line breaks that
489: are present in the input file. Therefore, break the lines in the Texinfo
490: file the way you want them to appear in the output Info file, and let
491: @TeX{} take care of itself.
492:
493: Since Info does not normally refill paragraphs when it processes them, a
494: line with @@-commands in it will sometimes look bad after Info has run on
495: it. To cause Info to refill the paragraph after finishing with the other
496: processing, you need to put the command @code{@@refill} at the end of the
497: paragraph. (@xref{Refilling & Noindent, , Refilling paragraphs and
498: Preventing indentation}.)@refill
499:
500: To prevent a paragraph from being indented in the printed manual, put the
501: command @code{@@noindent} on a line by itself before the start of the text
502: that should not be indented.
503:
504: If you mark off a region of the Texinfo file with the @code{@@iftex} and
505: @code{@@end iftex} commands so that the region will appear only in the
506: printed copy, you can use @TeX{} commands that cannot be used in the Info
507: file.
508:
509: In order to be made into a printed manual, a Texinfo file @strong{must}
510: begin with lines that looks like
511:
512: @example
513: \input texinfo @@c -*-texinfo-*-
514: @@setfilename @var{info-file-name}
515: @@settitle @var{Name of Manual}
516: @end example
517:
518: @noindent
519: The @samp{\input texinfo} line tells @TeX{} to use the @file{texinfo.tex}
520: file. This line is usually followed by a start-of-header line (not shown
521: here) and then by the @samp{@@setfilename @var{info-file-name}} and
522: @samp{@@settitle @var{Name of Manual}} lines. These two lines are needed
523: to provide a name for the Info file and to specify the name used on the
524: left-hand page headers of the printed manual.@refill
525:
526: The two lines that contain the @code{@@setfilename} and @code{@@settitle}
527: commands usually are sandwiched between the start-of-header line and the
528: end-of-header line. (@xref{Start-of-Header}, for more information.) The
529: start-of-header and end-of-header lines are needed if you are going to run
530: @TeX{} or Info on just part of a file.@refill
531:
532: @node Short Sample, , Conventions, Overview
533: @comment node-name, next, previous, up
534: @section A Short Sample Texinfo File
535: @cindex Sample texinfo file
536:
537: A Texinfo file looks like the following, which is a complete but very short
538: Texinfo file. The @code{@@comment} command introduces comments that will
539: not appear in either the Info file or the printed manual; they are for the
540: person who reads the Texinfo file.
541:
542: The first part of the file, from @samp{\input texinfo} through to
543: @samp{@@end titlepage}, looks more intimidating than it is. Most of the
544: material is standard boilerplate; when you write a manual, you just put in
545: the name of your own manual in this section.@refill
546:
547: All the commands that tell @TeX{} how to typeset the printed manual and
548: tell @code{texinfo-format-buffer} how to create an Info file are preceded
549: by @samp{@@}; thus, @code{@@node} indicates a node and @code{@@chapter}
550: indicates the start of a chapter.
551:
552: @example
553: \input texinfo @@c -*-texinfo-*-
554: @@setfilename name-of-texinfo-file
555: @@settitle Name of Manual
556: @@setchapternewpage odd
557:
558: @@ifinfo
559: @@comment The following line inserts the copyright notice
560: @@comment into the Info file.
561: Copyright @@copyright@{@} 1988 Free Software Foundation, Inc.
562: @@end ifinfo
563:
564: @@comment The titlepage section does not appear in the Info file.
565: @@titlepage
566: @@sp 10
567: @@comment The title is printed in a large font.
568: @@center @@titlefont@{Sample Title@}
569:
570: @@comment The following two commands start the copyright page
571: @@comment for the printed manual. This will not appear in the Info file.
572: @@page
573: @@vskip 0pt plus 1filll
574: Copyright @@copyright@{@} year copyright-owner
575: @@end titlepage
576:
577: @@comment The Top node contains the master menu for the Info file.
578: @@comment This appears only in the Info file, not the printed manual.
579:
580: @@node Top, First Chapter, (dir), (dir)
581: @@comment node-name, next, previous, up
582:
583: @@menu
584: * First Chapter:: The first chapter is the
585: only chapter in this sample.
586: @@end menu
587:
588: @@node First Chapter, , Top, Top
589: @@comment node-name, next, previous, up
590: @@chapter First Chapter
591: @@cindex Reference to First Chapter
592:
593: This is the contents of the first chapter.
594:
595: Here is a numbered list.
596:
597: @@enumerate
598: @@item
599: This is the first item.
600:
601: @@item
602: This is the second item.
603: @@end enumerate
604:
605: The @@kbd@{M-x texinfo-format-buffer@} command transforms a Texinfo file
606: like this into an Info file; and @@TeX@{@} typesets it for a printed
607: manual.
608:
609: @@node Concept Index, , Previous Node, Top
610: @@comment node-name, next, previous, up
611: @@unnumbered Concept Index
612:
613: @@printindex cp
614:
615: @@contents
616: @@bye
617: @end example
618:
619: Here is what the contents of the first chapter of the sample look like:
620:
621: @quotation
622:
623: This is the contents of the first chapter.
624:
625: Here is a numbered list.
626:
627: @enumerate
628: @item
629: This is the first item.
630:
631: @item
632: This is the second item.
633: @end enumerate
634:
635: The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file like
636: this into an Info file; and @TeX{} typesets it for a printed manual.
637: @end quotation
638:
639: @node Texinfo Mode, Beginning a File, Overview, Top
640: @comment node-name, next, previous, up
641: @chapter Using Texinfo Mode
642: @cindex Texinfo mode
643: @cindex Mode, using Texinfo
644: @cindex GNU Emacs
645: @cindex Emacs
646:
647: In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
648: This means that Emacs has commands and features especially designed for
649: working with Texinfo files. Like all other Emacs features, you can
650: customize or enhance these as you wish. In particular, the keybindings are
651: very easy to change. The keybindings described here are the default or
652: standard ones.
653:
654: The major features of Texinfo mode are:
655:
656: @itemize @bullet
657: @item
658: Paragraph filling control.
659:
660: @item
661: A command to show the structure of the file.
662:
663: @item
664: Pre-defined keystroke commands to insert commonly used strings of text.
665:
666: @item
667: Formatting a part of a file for Info, rather than the whole file.
668: @end itemize
669:
670: In general, in Texinfo mode, the GNU Emacs editing commands are like those
671: in text-mode. The major difference is that the paragraph separation
672: variable and syntax table are set up so expression commands skip Texinfo
673: bracket groups. This means, for example, that the @kbd{M-q}
674: (@code{fill-paragraph}) command will refill a paragraph but not the
675: @@-command on a line adjacent to it.@refill
676:
677: By convention, the Texinfo file name shall end with the extension
678: @file{.texinfo} so that Emacs knows to use Texinfo mode for editing it.
679:
680: @menu
681: * Info on a Region:: Formatting part of a file for Info.
682: * Showing the Structure:: Showing the structure of a file.
683: * Inserting:: Inserting frequently used commands.
684: @end menu
685:
686: @node Info on a Region, Showing the Structure, Texinfo Mode, Texinfo Mode
687: @comment node-name, next, previous, up
688: @section Formatting a Region for Info
689: @cindex Running Info on a region
690: @cindex Info, formatting on a region
691: @findex texinfo-format-region
692:
693: To see what part of a Texinfo file will look like after it has been
694: transformed into an Info file, use the command @kbd{C-c C-f}
695: (@code{texinfo-format-region}). This command formats the current region of
696: the Texinfo file for Info and writes it to a temporary buffer called
697: @samp{*Info Region*}.@refill
698:
699: For @code{texinfo-format-region} to work, the file @strong{must} include a
700: line that has @code{@@setfilename} in its header.@refill
701:
702: The command is:
703:
704: @table @kbd
705: @item C-c C-f
706: texinfo-format-region
707: @end table
708:
709: @node Showing the Structure, Inserting, Info on a Region, Texinfo Mode
710: @comment node-name, next, previous, up
711: @section Showing the Structure of a File
712: @cindex Showing the structure of a file
713: @cindex Structure of a file, showing it
714: @cindex File structure, showing it
715: @cindex Texinfo file structure, showing it
716:
717: You can show the structure of a Texinfo file by using the @kbd{C-c C-s}
718: command (@code{texinfo-show-structure}). This command shows the structure
719: of a Texinfo file by listing the lines with the @@-commands for
720: @code{@@node}, @code{@@chapter}, @code{@@section} and the like. These
721: lines are displayed in another window called the @samp{*Occur*} window. In
722: that window, you can position the cursor over one of the lines and use the
723: @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to the
724: corresponding spot in the Texinfo file.@refill
725:
726: The two commands are:
727:
728: @table @kbd
729: @item C-c C-s
730: texinfo-show-structure
731:
732: @item C-c C-c
733: occur-mode-goto-occurrence
734: @end table
735:
736: Often, when you are working on a manual, you will be interested only in the
737: structure of the current chapter. In this case, you can mark off the
738: region of the buffer that you are interested in with the @kbd{C-x n}
739: (@code{narrow-to-region}) command and @code{texinfo-show-structure} will
740: work on only that region. (To see the whole buffer again, use @kbd{C-x w}
741: (@code{widen}).)@refill
742:
743: @node Inserting, , Showing the Structure, Texinfo Mode
744: @comment node-name, next, previous, up
745: @section Inserting Frequently Used Commands
746: @cindex Inserting frequently used commands
747: @cindex Frequently used commands, inserting them
748: @cindex Commands, inserting them
749:
750: Texinfo mode provides commands that insert various frequently used
751: @@-commands into the buffer. You can use these commands to save
752: keystrokes. And you can insert balanced curly braces with the @kbd{M-@{}
753: command, (@code{texinfo-insert-braces}) and later use the @kbd{M-@}}
754: command (@code{up-list}) to move forward past the closing brace.@refill
755:
756: The special commands are invoked by typing @kbd{C-c} twice and then the
757: first letter of the @@-command.
758:
759: @table @kbd
760: @item C-c C-c c
761: texinfo-insert-@@code
762:
763: @item C-c C-c d
764: texinfo-insert-@@dfn
765:
766: @item C-c C-c e
767: texinfo-insert-@@end
768:
769: @item C-c C-c i
770: texinfo-insert-@@item
771:
772: @item C-c C-c n
773: texinfo-insert-@@node
774:
775: @item C-c C-c s
776: texinfo-insert-@@samp
777:
778: @item C-c C-c v
779: texinfo-insert-@@var
780:
781: @item M-@{
782: texinfo-insert-braces
783:
784: @item M-@}
785: up-list
786: @end table
787:
788: This list was generated by analyzing the frequency with which commands were
789: used in the @cite{GNU Emacs Manual} and the @cite{GDB Manual}. If you wish
790: to add your own insert commands, you can bind a keyboard macro to a key, use
791: abbreviations or extend the code in @file{texinfo.el}.
792:
793: @node Beginning a File, Ending a File, Texinfo Mode, Top
794: @comment node-name, next, previous, up
795: @chapter Beginning a Texinfo File
796: @cindex Beginning a Texinfo file
797: @cindex Texinfo file beginning
798: @cindex File beginning
799:
800: Various pieces of information have to be provided to Texinfo at the
801: beginning of a Texinfo file, such as the name of the file, the title
802: of the document and the like. Generally, the beginning of a Texinfo file
803: has four parts:
804:
805: @enumerate
806: @item
807: The header, marked by start-of-header and end-of-header lines, that
808: includes the commands for naming the Texinfo file and telling @TeX{} what
809: definitions' file to use when processing the file.
810:
811: @item
812: A section, marked by the @code{@@ifinfo} and @code{@@end ifinfo} commands,
813: that contains a short statement of what the file is about, the copyright
814: notice and copying permissions. This section appears only in the Info file.
815:
816: @item
817: A section, marked by the @code{@@titlepage} and @code{@@end titlepage}
818: commands, that contains the title page, the copyright page and copying
819: permissions. This section appears only in the printed manual.
820:
821: @item
822: The @samp{Top} node that contains an extensive menu for the whole Info
823: file. The contents of this node only appear in the Info file.
824: @end enumerate
825:
826: If the Texinfo file has a section containing licensing information and a
827: warranty disclaimer, that section usually follows the @samp{Top} node. The
828: licensing section will be followed by a preface or else by the first
829: chapter of the manual.
830:
831: Since the copyright notice and the copying permissions are in sections that
832: appear only in the Info file or only in the printed manual, this
833: information has to be repeated twice.
834:
835: The following sample shows what is needed.
836:
837: @example
838: \input texinfo @@c -*-texinfo-*-
839: @@comment %**start of header (This is for running Texinfo on a region.)
840: @@setfilename name-of-texinfo-file
841: @@settitle Name of Manual
842: @@setchapternewpage odd
843: @@comment %**end of header (This is for running Texinfo on a region.)
844:
845: @@ifinfo
846: This file documents @dots{}
847:
848: Copyright @@copyright@{@} year copyright-owner
849:
850: Permission is granted to @dots{}
851: @@end ifinfo
852:
853: @@titlepage
854: @@sp 10
855: @@center @@titlefont@{Name of Manual When Printed@}
856: @@sp 2
857: @@center Subtitle, If Any
858: @@sp 2
859: @@center Author
860:
861: @@comment The following two commands start the copyright page.
862: @@page
863: @@vskip 0pt plus 1filll
864: Copyright @@copyright@{@} year copyright-owner
865:
866: Published by @dots{}
867:
868: Permission is granted to @dots{}
869: @@end titlepage
870:
871:
872: @@node Top, Overview, (dir), (dir)
873:
874: @@menu
875: * First Chapter:: The first chapter is usually an overview.
876: * Second Chapter:: @dots{}
877: <many more menu items here>
878: @@end menu
879:
880: @@node First Chapter, Second Chapter, top, top
881: @@comment node-name, next, previous, up
882: @@chapter First Chapter
883: @@cindex Reference to First Chapter
884: @end example
885:
886: @menu
887: * Header:: Necessary first lines.
888: * Permissions for Info:: Copyright notice and copying permissions.
889: * Titlepage & Copyright Page:: Printed title and copyright pages.
890: * Top Node:: The top node and master menu.
891: * License and Distribution:: The importance of the license.
892: @end menu
893:
894: @node Header, Permissions for Info , Beginning a File, Beginning a File
895: @comment node-name, next, previous, up
896: @section The Texinfo File Header
897: @cindex Header for Texinfo files
898: @cindex Texinfo file header
899:
900: Texinfo files start with at least three lines that provide Info and @TeX{}
901: with necessary information. If you want to run @TeX{} on just a part of
902: the Texinfo File, you also have to mark these heading lines with
903: start-of-header and end-of-header lines.@refill
904:
905: @menu
906: * First Line:: The first line of a Texinfo file.
907: * Start-of-Header:: Identifying the start of the header.
908: * Setfilename:: Specifying the name of the Info file.
909: * Settitle:: Specifying the title used by the headings.
910: * Setchapternewpage:: Starting chapters on odd numbered pages.
911: * End-of-Header:: Identifying the end of the header.
912: @end menu
913:
914: @node First Line, Start-of-Header, Header, Header
915: @comment node-name, next, previous, up
916: @subsection The First Line of a Texinfo File
917: @cindex First line of a Texinfo file
918: @cindex Beginning line of a Texinfo file
919:
920:
921: Every Texinfo file that is to be the top-level input to @TeX{} must begin
922: with a line that looks like this:
923:
924: @example
925: \input texinfo @@c -*-texinfo-*-
926: @end example
927:
928: @noindent
929: The line serves two functions:
930:
931: @enumerate
932: @item
933: When the file is processed by @TeX{}, it loads the macros needed for
934: processing a Texinfo file. These are in a file called @file{texinfo.tex}
935: which is usually located in the @file{/usr/lib/tex/macros} directory.@refill
936:
937: @item
938: When the file is edited in GNU Emacs, it causes Texinfo mode to be used.@refill
939: @end enumerate
940:
941: The @samp{\input texinfo} line should be followed by the start-of-header
942: line. This makes it possible for the command for running @TeX{} on a part
943: of the Texinfo file (@code{texinfo-hardcopy-region}) to operate. The
944: reason for this is that the @code{texinfo-hardcopy-region} command will
945: look on the line preceding the start-of-header line for the @samp{\input
946: texinfo} line.
947:
948: @node Start-of-Header, Setfilename, First Line, Header
949: @comment node-name, next, previous, up
950: @subsection @samp{start-of-header}
951: @cindex start-of-header
952: @findex start-of-header
953:
954: The start-of-header line should immediately follow the first line of the
955: Texinfo file.
956:
957: @ifinfo
958: The @code{texinfo-hardcopy-region} command will look at the
959: line preceding the start-of-header line to find the @samp{\input
960: texinfo} line.
961: @end ifinfo
962:
963: Usually, the start-of-header line looks like this:
964:
965: @example
966: @@comment %**start of header (This is for running Texinfo on a region.)
967: @end example
968:
969: The reason for the odd string of characters (@samp{%**}) is so that the
970: @code{texinfo-hardcopy-region} command does not accidently find something
971: that it shouldn't when it is looking for the header.
972:
973: In the default configuration, the phrase @samp{(This is for running Texinfo
974: on a region.)} is not needed and is just included to make it easier for
975: someone reading the Texinfo file.
976:
977: The start-of-header line and the end-of-header line are Texinfo mode
978: variables that you can change.
979:
980: @node Setfilename, Settitle, Start-of-Header, Header
981: @comment node-name, next, previous, up
982: @subsection @@setfilename
983: @cindex Setfilename command
984: @cindex Info file requirement for @@setfilename
985: @findex setfilename
986:
987: In order to be made into an Info file, a Texinfo file must contain a line
988: that looks like this:
989: @example
990: @@setfilename @var{info-file-name}
991: @end example
992:
993: @noindent
994: This line specifies the name of the Info file to be generated. In fact, there
995: can be other things in the file before this line, but they are ignored in
996: the generation of an Info file. The @code{@@setfilename} line is ignored
997: when a printed manual is generated.
998:
999: @node Settitle, Setchapternewpage, Setfilename, Header
1000: @comment node-name, next, previous, up
1001: @subsection @@settitle
1002: @findex settitle
1003:
1004: In order to be made into a printed manual file, a Texinfo file must contain
1005: a line that specifies the title of the manual. Texinfo uses this
1006: information during printing to put the title on every other page as a
1007: heading; Texinfo puts the current chapter title on the other pages.
1008: Texinfo can find the name of the chapter title from the information
1009: provided by the @code{@@chapter} command, but you must tell it the manual
1010: title with @code{@@settitle}:
1011:
1012: @example
1013: @@settitle @var{Title}
1014: @end example
1015:
1016: @noindent
1017: This command, on a line by itself, causes @var{title} to be used for the
1018: headings. Usually, you will use the same words for the title on the title
1019: page and for the title specified by this command for the headings, but the
1020: two could be different. For example, the title on the title page may be
1021: longer than the title specified by the @code{settitle} command.
1022:
1023: The @code{@@settitle} command should precede everything that generates
1024: actual output.
1025:
1026: @node Setchapternewpage, End-of-Header, Settitle, Header
1027: @comment node-name, next, previous, up
1028: @subsection @@setchapternewpage
1029: @cindex Starting chapters
1030: @cindex Pages, starting odd
1031: @findex setchapternewpage
1032:
1033: Conventionally, chapters start on the page on the right hand side of a
1034: book; and the right hand page has an odd number. To make sure that Texinfo
1035: does this, you can use the command @code{@@setchapternewpage}. For
1036: example, to cause each chapter to start on a fresh odd-numbered page:
1037:
1038: @example
1039: @@setchapternewpage odd
1040: @end example
1041:
1042: Page numbering is turned on by the @code{@@end titlepage} command, so the
1043: @code{@@setchapternewpage} should come before it. Although it can occur
1044: anywhere in the beginning of the file, it is most convenient to put it in
1045: this location.
1046:
1047:
1048: @node End-of-Header, , Setchapternewpage, Header
1049: @comment node-name, next, previous, up
1050: @subsection @samp{end-of-header}
1051: @cindex end-of-header
1052:
1053: The end-of-header line should follow the line containing the
1054: @code{@@setchapternewpage} command.
1055:
1056: Usually, the end-of-header line looks like this:
1057:
1058: @example
1059: @@comment %**end of header (This is for running Texinfo on a region.)
1060: @end example
1061:
1062: @ifinfo
1063: In the default configuration, the phrase @samp{(This is for running Texinfo
1064: on a region.)} is not needed and is just included to make it easier for
1065: someone reading the Texinfo file.
1066:
1067: The reason for the odd string of characters (`%**') is so that the
1068: @code{texinfo-hardcopy-region} command does not accidently find something
1069: that it shouldn't when it is looking for the header.
1070:
1071: The start-of-header line and the end-of-header line are Texinfo mode
1072: variables that you can change.
1073: @end ifinfo
1074:
1075: @iftex
1076: Also, @pxref{Start-of-Header}
1077: @end iftex
1078:
1079: @node Permissions for Info, Titlepage & Copyright Page, Header, Beginning a File
1080: @comment node-name, next, previous, up
1081: @section Copying Permissions for Info
1082:
1083: Since the title page and the copyright page appear only in the printed copy
1084: of the manual, the same information has to inserted in a section that
1085: appears only in the Info file. This section usually contains a brief
1086: description of the contents of the Info file, a copyright notice and
1087: copying permissions.
1088:
1089: The copyright notice should read:
1090:
1091: @example
1092: Copyright @var{year} @var{copyright-owner}
1093: @end example
1094:
1095: @noindent
1096: and be put on a line by itself.
1097:
1098: Standard text for the copyright permissions is contained in the appendix.
1099: @xref{Ifinfo Permissions}, for the complete text.
1100:
1101: @node Titlepage & Copyright Page, Top Node, Permissions for Info, Beginning a File
1102: @comment node-name, next, previous, up
1103: @section The Title and Copyright Pages
1104: @cindex Titlepage
1105: @cindex Copyright page
1106:
1107: The title and copyright pages appear in the printed manual, but not in the
1108: Info file. Because of this, it is possible to use a couple of slightly
1109: obscure @TeX{} typesetting commands that could not be used in an Info file.
1110: In addition, this part of the beginning of a Texinfo file contains the text
1111: of the copying permissions that will appear in the printed manual.
1112:
1113: @menu
1114: * Titlepage:: Creating a title page for the printed manual.
1115: * Center:: Centering a line.
1116: * Copyright & Printed Permissions:: Inserting the copyright notice
1117: and printed permissions.
1118: @end menu
1119:
1120: @node Titlepage, Center , Setchapternewpage, Titlepage & Copyright Page
1121: @comment node-name, next, previous, up
1122: @subsection @@titlepage
1123: @cindex Titlepage
1124: @findex titlepage
1125:
1126: Start the material for the title page and following copyright page with
1127: @code{@@titlepage} on a line by itself and end it with @code{@@end
1128: titlepage} on a line by itself. The title page and copyright page material
1129: appears only in the printed manual, not in the Info file.
1130:
1131: Also, the @code{@@end titlepage} command starts a new page and turns on
1132: page numbering (generation of headings). Therefore, all the material that
1133: you want to appear on unnumbered pages should be put between the
1134: @code{@@titlepage} and @code{@@end titlepage} commands. By using the
1135: @code{@@page} command you can force a page break within the region
1136: delineated by the @code{@@titlepage} and @code{@@end titlepage} commands
1137: and create more than one unnumbered page. This is how the copyright page
1138: is produced.@refill
1139:
1140: @findex titlefont
1141: To select a large font suitable for the title itself, you can use the
1142: command @code{@@titlefont}. For example:
1143:
1144: @example
1145: @@center @@titlefont@{Texinfo@}
1146: @end example
1147:
1148: Also, you can use @code{@@sp} commands to adjust vertical spacing.
1149: For example:
1150:
1151: @example
1152: @@sp 2
1153: @end example
1154:
1155: @noindent
1156: In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch manual.
1157:
1158: @node Center, Titlepage, Copyright & Printed Permissions, Titlepage & Copyright Page
1159: @comment node-name, next, previous, up
1160: @subsection @@center
1161: @cindex Centering a line
1162: @findex center
1163:
1164: A line containing @code{@@center @var{text}} produces a line of output
1165: containing @var{text}, centered between the margins.@refill
1166:
1167:
1168:
1169: @node Copyright & Printed Permissions, Center, , Titlepage & Copyright Page
1170: @comment node-name, next, previous, up
1171: @subsection The Copyright Page and Printed Permissions
1172: @cindex Copyright
1173: @cindex Printed permissions
1174: @cindex Permissions, printed
1175:
1176: By international treaty, the copyright notice for a book should either be
1177: on the title page or on the back of the title page. Other locations in a
1178: book are not official and do not provide copyright protection. The
1179: copyright notice should include the year followed by the name of the person
1180: or organization who has the copyright.
1181:
1182: When the copyright notice is on the back of the title page, the page is not
1183: numbered. Therefore, in Texinfo, the information on the copyright page
1184: should be within the region delineated by the @code{@@titlepage} and
1185: @code{@@end titlepage} commands.@refill
1186:
1187: @findex vskip
1188: @findex filll
1189: To cause a page break, the @code{@@page} command is used. In the sample,
1190: the @code{@@page} command is followed by the somewhat mysterious line that
1191: reads: @samp{@@vskip 0pt plus 1filll}. This is a line that uses @TeX{}
1192: commands to push the copyright notice and the other text on the copyright
1193: page towards the bottom of the page. The @code{@@vskip} command means to
1194: skip lines and put in white space. The @samp{0pt plus 1filll} means to put
1195: in zero points of mandatory white space, and as much optional white space
1196: as needed. Note the use of three @samp{l}s in the word @samp{filll}; this
1197: is the correct use in @TeX{}.@refill
1198:
1199: @findex copyright
1200: The @code{@@copyright@{@}} command generates a @samp{c} inside a circle.
1201: The copyright notice itself has the following legally defined sequence:
1202:
1203: @example
1204: Copyright @copyright{} @var{year} @var{copyright-owner}
1205: @end example
1206:
1207: It is customary to put information on how to get a manual after the
1208: copyright notice (the address of the Free Software Foundation, for example)
1209: and the permissions.
1210:
1211: Note that the permissions have to be repeated here as well as in the
1212: `ifinfo' section that immediately follows the header since this section
1213: appears only in the printed manual and the `ifinfo' section appears only in
1214: the Info file.
1215:
1216: Standard text for the permissions appears in the appendix.
1217: @xref{Sample Permissions}.
1218:
1219: @node Top Node, License and Distribution, Titlepage & Copyright Page, Beginning a File
1220: @comment node-name, next, previous, up
1221: @section The Top Node and Master Menu
1222: @cindex Top node
1223: @cindex Master menu
1224:
1225: The @samp{Top} node contains an extensive, master menu for the whole Info
1226: file. The contents of this node appear only in the Info file. Nothing in
1227: this node should appear in the printed file. Since a node line by itself
1228: and a menu by itself are not printed, the contents of this node do not have
1229: to be within a region delineated by @code{@@ifinfo} and @code{@@end ifinfo}
1230: commands. However, any text within the node should be marked off in that
1231: manner. You may want to put a short summary before the master menu inside
1232: a region delineated by @code{@@ifinfo} and @code{@@end ifinfo} commands.
1233: Usually, the `Previous' and `Up' nodes refer to the top level directory of
1234: the whole Info system, with pointers to @samp{(dir)}.@refill
1235:
1236: Generally, the top menu is divided into parts.
1237:
1238: @itemize @bullet
1239:
1240: @item
1241: The first part contains the major nodes in the Texinfo file: the nodes for
1242: the chapters, chapter-like sections and the major appendices.
1243:
1244: @item
1245: The second part contains entries for the indices. In an Info file, it is
1246: very useful to have indices here at the beginning of the file in the top
1247: node rather than at the end, as in a printed book.
1248:
1249: @item
1250: The third and subsequent parts contain a listing of the other, lower level
1251: nodes, often ordered by chapter. This way, an inquirer can go directly to
1252: a particular node if he or she is searching for specific information.
1253: (These nodes are not required; use them if you think they are a
1254: convenience.)
1255: @end itemize
1256:
1257: Each section in the menu can be introduced a descriptive line. So long as
1258: the line does not begin with an asterisk, it will not be treated as a menu
1259: item. (@xref{Menu, , Making Menus}, for more information.)
1260:
1261: For example, the Top node of this manual looks like this (but with many
1262: more entries):
1263:
1264: @example
1265: @@node Top, Overview, (dir), (dir)
1266:
1267: @@menu
1268: * Overview:: What is Texinfo?
1269: * Texinfo Mode:: Special features in GNU Emacs.
1270: @dots{}
1271:
1272: Indices, nodes containing large menus
1273:
1274: * Command Index:: An item for each @@-command.
1275: * Concept Index:: An item for each concept.
1276:
1277: A detailed node listing
1278:
1279: Overview
1280: * Info File:: Characteristics of the Info file.
1281: * Printed Manual:: Characteristics of the printed manual.
1282:
1283: Using Texinfo Mode
1284: * Info on a Region:: Formatting a region for Info.
1285: * Showing the Structure:: Showing the structure of a file.
1286: @dots{}
1287: @dots{}
1288: @end example
1289:
1290:
1291: @node License and Distribution, , Top Node, Beginning a File
1292: @comment node-name, next, previous, up
1293: @section Licensing and Distribution Information
1294: @cindex Distribution
1295: @cindex License agreement
1296:
1297: If the Texinfo file has a section containing the ``General Public License''
1298: and the distribution information and a warranty disclaimer, this section
1299: usually follows the @samp{Top} node. The licensing and distribution
1300: information and the disclaimer are followed by a preface or else by the
1301: first chapter of the manual.
1302:
1303: The licensing agreement is very important to Project GNU documentation and
1304: software. Without it, you may find that you can no longer get the software
1305: or its documentation. This sounds paradoxical, but the state of the world
1306: is such that documentation and software that does not have a
1307: ``restrictive'' license to make them freely distributable may be lost to
1308: the public. This has happened.@refill
1309:
1310: For a good example of the text that could be used for the Distribution,
1311: General Public License and NO WARRANTY sections of your document, see the
1312: latest version of the @cite{GNU Emacs Manual}.
1313:
1314: @cindex Preface
1315: Although a preface is not a required part of a Texinfo file, it is very
1316: helpful. Ideally, it should state clearly and concisely what the file is
1317: about and who would be interested in reading it. In general, the preface
1318: would follow the licensing and distribution information, although sometimes
1319: people put it earlier in the document. Usually, a preface is put in an
1320: @code{@@unnumbered} section. (@xref{Unnumbered and Appendix}.)
1321:
1322: @node Ending a File, Structuring, Beginning a File, Top
1323: @comment node-name, next, previous, up
1324: @chapter Ending a Texinfo File
1325: @cindex Ending a Texinfo file
1326: @cindex Texinfo file ending
1327: @cindex File ending
1328: @findex bye
1329:
1330: The end of a Texinfo file should include the indices, the commands to
1331: generate detailed and summary tables of contents and the @@-command
1332: that tells @TeX{} that it has reached the end of the file.
1333:
1334: For example, a Texinfo file might be ended as follows:
1335:
1336: @example
1337: @@node Concept Index, , Previous Node, Top
1338: @@comment node-name, next, previous, up
1339: @@unnumbered Concept Index
1340:
1341: @@printindex cp
1342:
1343: @@contents
1344: @@bye
1345: @end example
1346:
1347: The @code{@@bye} command should be on a line by itself and every Texinfo
1348: file must end with such a line. This command terminates @TeX{} processing
1349: and forces out unfinished pages.@refill
1350:
1351: @menu
1352: * Contents:: Generating a table of contents
1353: * Indices:: Generating, sorting and printing indices
1354: @end menu
1355:
1356: @node Contents, Indices , , Ending a File
1357: @comment node-name, next, previous, up
1358: @section Generating a Table of Contents
1359: @cindex Table of contents
1360: @cindex Contents, Table of
1361:
1362: The commands @code{@@chapter}, @code{@@section}, etc., supply the
1363: information to make up a table of contents, but they do not cause an actual
1364: table to be generated. To do this, you must use the commands
1365: @code{@@contents} and @code{@@summarycontents}.@refill
1366:
1367: @table @code
1368:
1369: @item @@contents
1370: The table of contents command outputs (into a printed manual) a complete
1371: table of contents, based on the @code{@@chapter}, @code{@@unnumbered} and
1372: other sectioning commands. This command should be used on a line by
1373: itself.@refill
1374:
1375: @item @@summarycontents
1376: The summary contents command generates a summary table of contents that
1377: lists only the chapters (and appendices and unnumbered chapters); sections,
1378: subsections and subsubsections are omitted. This command should be used on
1379: a line by itself. Only large manuals need a summary table of
1380: contents.@refill
1381: @end table
1382:
1383: You can use either one of these commands, or both. Each command
1384: automatically generates a chapter-like heading at the top of the page.
1385: Tables of contents should be generated at the very end of the manual, just
1386: before the @code{@@bye} command; the tables of contents commands should
1387: follow any indices that are output, so that the indices will appear in the
1388: contents.@refill
1389:
1390: @group
1391: @example
1392: @var{indices}@dots{}
1393: @@summarycontents
1394: @@contents
1395: @@bye
1396: @end example
1397: @end group
1398:
1399: The commands @code{@@contents} and @code{@@summarycontents} are ignored when an
1400: Info file is being generated.
1401:
1402: @node Indices, , Contents, Ending a File
1403: @comment node-name, next, previous, up
1404: @section Creating Indices
1405: @cindex Indices
1406: @cindex Creating indices
1407:
1408: Using Texinfo, you can generate printed indices and Info file menus without
1409: having to sort and collate entries manually. Texinfo will do this for you
1410: automatically. Each index covers a certain kind of entry (functions, or
1411: variables, or concepts, etc.)@: and lists all of those entries in
1412: alphabetical order, together with information on how to find the discussion
1413: of each entry. In a printed manual, this information consists of page
1414: numbers. In an Info file, it consists of a menu item leading to the first
1415: node referenced.
1416:
1417: When you are making index entries, it is good practice to think of the
1418: different categories under which people may look for something. Different
1419: people @emph{do not} think of the same words when they look something up.
1420: They think of different words. A helpful index will have items indexed
1421: under all the different words that people may use. For example, someone might
1422: think it obvious that the two letter names for indices should be listed
1423: under ``Indices, two letter names'', since the word ``Index'' is the
1424: general concept. But another reader may remember the specific concept of
1425: two letter names and search for the entry listed as ``Two letter names for
1426: indices''. A good index will have both entries and will help both kinds of
1427: user.
1428:
1429: Like typesetting, the construction of an index is a highly skilled,
1430: professional art, the subtleties of which are not appreciated until you
1431: have to do it yourself.
1432:
1433: Normally, six indices are provided for:
1434:
1435: @itemize @bullet
1436: @item
1437: A @dfn{program index} listing names of programs and leading to the places
1438: where those programs are documented.@refill
1439:
1440: @item
1441: A @dfn{function index} listing functions (such as, entry points of
1442: libraries).@refill
1443:
1444: @item
1445: A @dfn{variables index} listing variables (such as, external variables of
1446: libraries).@refill
1447:
1448: @item
1449: A @dfn{data type index} listing data types (such as, structures defined in
1450: header files).@refill
1451:
1452: @item
1453: A @dfn{keystroke index} listing keyboard commands.@refill
1454:
1455: @item
1456: A @dfn{concept index} listing concepts that are discussed.@refill
1457: @end itemize
1458:
1459: @noindent
1460: Not every manual needs all of these. This manual has two indices: a
1461: concept index and an @@-command index (that uses the function index but is
1462: called a command index in the chapter heading). Two or more indices can be
1463: combined into one using the @code{@@synindex} command. @xref{Combining
1464: Indices}.
1465:
1466: @menu
1467: * Index Entries:: Defining the entries of an index
1468: * Combining Indices::
1469: * Printing Indices & Menus::
1470: @end menu
1471:
1472: @node Index Entries, Combining Indices, , Indices
1473: @comment node-name, next, previous, up
1474: @subsection Defining the Entries of an Index
1475: @cindex Defining the entries of an index
1476: @cindex Index entries
1477: @cindex Entries for an index
1478:
1479: The data to make an index comes from many individual commands scattered
1480: throughout the Texinfo source file. Each command says to add one entry to
1481: a particular index; after processing, it will give the current page number
1482: or node name as the reference.
1483:
1484: @table @code
1485: @item @@cindex @var{concept}
1486: Make an entry in the concept index for @var{concept}, referring to the
1487: current page or node.@refill
1488: @item @@findex @var{function}
1489: Make an entry in the function index for @var{function}, referring to the
1490: current page or node.@refill
1491: @item @@vindex @var{variable}
1492: Make an entry in the variable index for @var{variable}, referring to the
1493: current page or node.@refill
1494: @item @@pindex @var{program}
1495: Make an entry in the program index for @var{program}, referring to the
1496: current page or node.@refill
1497: @item @@kindex @var{key}
1498: Make an entry in the key index for @var{key}, referring to the
1499: current page or node.@refill
1500: @item @@tindex @var{data type}
1501: Make an entry in the data type index for @var{data type}, referring to the
1502: current page or node.@refill
1503: @end table
1504:
1505: If the same name is indexed on several pages, all the pages are listed in
1506: the printed manual's index. However, @strong{only} the @strong{first} node
1507: referenced will appear in the index of an Info file. This means that it is
1508: best to write indices in which each entry will refer to only one place in the
1509: Texinfo file. Fortunately, this constraint is a feature rather than loss
1510: since it means that the index will be easy to use. Otherwise, it can be
1511: easy to create an index which has many pages listed for an entry and you
1512: don't know which one you need.@refill
1513:
1514: You are not actually required to use indices for their canonical
1515: purposes. For example, you might wish to index some C preprocessor macros.
1516: You could put them in the function index along with actual functions, just
1517: by writing @code{@@findex} commands for them; then, when you print the
1518: ``function index'', you could give it the title `Function and Macro Index'
1519: and all will be consistent for the reader. Or you could put the macros in
1520: with the data types by writing @code{@@tindex} commands for them, and give
1521: that index a suitable title so the reader will understand.@refill
1522:
1523: @node Combining Indices, Printing Indices & Menus, Index Entries, Indices
1524: @comment node-name, next, previous, up
1525: @subsection Combining Indices
1526: @cindex Combining Indices
1527: @cindex Indices, combining them
1528:
1529: Sometimes you will want to combine two disparate indices such as functions
1530: and variables, perhaps because you have few enough of one of them that
1531: a separate index for them would look silly.
1532:
1533: You could put variables into the function index by writing @code{@@findex}
1534: commands for them instead of @code{@@vindex} commands, and produce a
1535: consistent manual by printing the function index with the title `Function
1536: and Variable Index' and not printing the `Variable Index' at all; but this
1537: is not a robust procedure. It works only as long as your document is never
1538: included in part of or together with another document that is designed to
1539: have a separate variable index; if you did that, the variables from your
1540: document and those from the other would not end up together.
1541:
1542: What you should do instead when you want functions and variables in one
1543: index is to index the variables with @code{@@vindex} as they should be, but
1544: use the @code{@@synindex} command to redirect these @code{@@vindex}
1545: commands to the function index. @code{@@synindex} takes two arguments: the
1546: name of an index to redirect, and the name of an index to redirect it to.
1547: For this purpose, the indices are given two-letter names:
1548: @cindex Two letter names for indices
1549: @cindex Indices, two letter names
1550: @cindex Names for indices
1551:
1552: @table @samp
1553: @item cp
1554: the concept index
1555: @item vr
1556: the variable index
1557: @item fn
1558: the function index
1559: @item ky
1560: the key index
1561: @item pg
1562: the program index
1563: @item tp
1564: the data type index
1565: @end table
1566:
1567: Thus, @code{@@synindex vr fn} at the front of a Texinfo file
1568: will cause all entries designated for the variable index to go to
1569: the function index instead.
1570:
1571: @node Printing Indices & Menus, , Combining Indices, Indices
1572: @comment node-name, next, previous, up
1573: @subsection Printing an Index and Generating Menus
1574: @cindex Printing an index
1575: @cindex Indices, printing
1576: @cindex Generating menus with indices
1577: @cindex Menus generated with indices
1578:
1579: To print an index means to include it as part of a manual or Info file.
1580: This does not happen automatically just because you use @code{@@cindex} or
1581: other index-entry generating commands in the Texinfo file; those just cause
1582: the raw data for the index to be accumulated. To print an index, you must
1583: include the @code{@@printindex} command at the place in the document where
1584: you want the index to appear. Also, for the case of the printed manual,
1585: you must run a program called @code{texindex} to sort the raw data to
1586: produce a sorted index file, which is what will actually be used to print
1587: the index.@refill
1588:
1589: The Texinfo command that is used to print indices is @code{@@printindex}.
1590: It takes the two-letter index name (@pxref{Combining Indices}) as an
1591: argument without braces, and reads the corresponding sorted index file and
1592: formats it appropriately into an index.@refill
1593:
1594: @ifinfo
1595: The two-letter index names are:
1596:
1597: @table @samp
1598: @item cp
1599: the concept index.
1600: @item vr
1601: the variable index.
1602: @item fn
1603: the function index.
1604: @item ky
1605: the key index.
1606: @item pg
1607: the program index.
1608: @item tp
1609: the data type index.
1610: @end table
1611: @end ifinfo
1612:
1613: @code{@@printindex} does not generate a chapter heading for the index.
1614: Consequently, you should precede the command with a suitable section or
1615: chapter command (usually @code{@@unnumbered}) to supply the chapter heading
1616: and put the index into the table of contents. And before that, you will
1617: probably put a @code{@@node} command. For example,@refill
1618:
1619: @example
1620: @@node Variables Index, Concept Index, Function Index, Top
1621: @@comment node-name, next, previous, up
1622: @@unnumbered Variable Index
1623:
1624: @@printindex vr
1625:
1626: @@node Concept Index, , Variables Index, Top
1627: @@comment node-name, next, previous, up
1628: @@unnumbered Concept Index
1629:
1630: @@printindex cp
1631:
1632: @@summarycontents
1633: @@contents
1634: @@bye
1635: @end example
1636:
1637: In @TeX{}, @code{@@printindex} needs a sorted index file to work from.
1638: @TeX{} does not know how to do sorting; this is one of the main
1639: deficiencies of @TeX{}. You must invoke the program @code{texindex} to do
1640: so, giving it the names of the raw index files to be sorted as arguments.
1641: You do not have to run @code{texindex} on all of them; only the ones you
1642: are going to print. (@xref{Printing Hardcopy}, for more information.)
1643:
1644: @node Structuring, Quotations and Examples, Ending a File, Top
1645: @comment node-name, next, previous, up
1646: @chapter Node and Chapter Structuring
1647: @cindex Node and chapter structuring
1648: @cindex Chapter structuring
1649: @cindex Node structuring
1650: @cindex Structuring of nodes and chapters
1651: @findex node
1652:
1653: The chapter structuring commands divide a document into a hierarchy of
1654: chapters, sections, subsections and subsubsections. These commands
1655: generate large headings.
1656:
1657: In a printed manual, the table of contents is based on the information
1658: specified by the chapter structuring commands.
1659:
1660: Although the chapter structuring commands used for creating a printed
1661: document are entirely different from the node commands for structuring an
1662: Info file, you are likely to use the two kinds of command together since
1663: the single Texinfo file is usually designed to be read both as an Info file
1664: and as a printed manual. The only time you are likely to use the chapter
1665: structuring commands without using the node structuring commands is if you
1666: are writing a document that will never be put into Info format, for
1667: example, a novel, a letter, an article or a memorandum.
1668:
1669: It is unlikely that you will ever write a Texinfo file that is only
1670: intended as an on-line Info file and not as a printable document. However,
1671: Texinfo is flexible enough so that you can do this if you wish.
1672:
1673: Although a Texinfo file can be structured in a variety of ways, it is
1674: usually structured like a book with chapters, sections, subsections and the
1675: like. This structure can also be visualized as a tree (or rather as an
1676: upside down tree) with the root at the top and each level corresponding to
1677: chapters or sections or whatnot. In Info format, you reach the nodes on
1678: each level by using the the `Next' and `Previous' pointers in the node
1679: line. For example, you go from one chapter to the next or previous chapter
1680: by using the the pointers to the next and previous chapters. In Info, you
1681: go the level above by using an `Up' pointer and you go to the level below
1682: through a `Menu'. In the printed manual, cross references are indicated by
1683: page and section numbers; in the on-line file, cross references are
1684: specified by inline menu items.
1685:
1686: @group
1687: Here is a diagram that shows a Texinfo file with three chapters;
1688: each chapter has two sections.
1689:
1690: @example
1691: top
1692: |
1693: |
1694: ---------------------------------------------
1695: | | |
1696: | | |
1697: Chapter 1 Chapter 2 Chapter 3
1698: | | |
1699: | | |
1700: ---------- ---------- ----------
1701: | | | | | |
1702: Sect. 1.1 Sect. 1.2 Sect. 2.1 Sect. 2.2 Sect. 3.1 Sect. 3.2
1703:
1704: @end example
1705: @end group
1706:
1707: In this structure, the node for Chapter 2 looks like this:
1708:
1709: @example
1710: @@node Chapter 2, Chapter 3, Chapter 1, top
1711: @@comment node-name, next, previous, up
1712: @end example
1713:
1714: To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 that
1715: says:
1716:
1717: @example
1718: @@menu
1719: * Sect. 2.1:: Description of this section.
1720: * Sect. 2.2::
1721: @@end menu
1722: @end example
1723:
1724: @noindent
1725: This menu is located inside Chapter 2, after the beginning of the chapter,
1726: just before Section 2.1.
1727:
1728: Note that a menu entry has three parts: the menu item name, the name of the
1729: node and, optionally, a description of the item (in that order). If the
1730: menu item name and the name of the node are the same, you can put two
1731: colons after the item name, as is shown in the example. (If the second part
1732: is different from the first, the first part is terminated by a colon and
1733: the second part terminated by a tab, newline, comma or period.)
1734: (@xref{Menu}.)
1735:
1736: The node for Sect. 2.1 will look like this:
1737:
1738: @example
1739: @@node Sect. 2.1, Sect. 2.2, , Chapter 2
1740: @@comment node-name, next, previous, up
1741: @end example
1742:
1743: This node does not have a `Previous' node.
1744:
1745:
1746: Usually, an @code{@@node} command and a chapter structuring command are
1747: used in sequence, along with indexing commands. For example, the node for
1748: the chapter on ending a file looks like this:
1749:
1750: @group
1751: @example
1752: @@node Ending a File, Structuring, Beginning a File, Top
1753: @@comment node-name, next, previous, up
1754: @@chapter Ending a Texinfo File
1755: @@cindex Ending a Texinfo file
1756: @@cindex Texinfo file ending
1757: @@cindex File ending
1758: @end example
1759: @end group
1760:
1761: The chapter structuring commands fall into four groups that have the
1762: characteristics of chapters, sections, subsections and subsubsections.
1763: The groups are:
1764:
1765: @group
1766: @table @code
1767: @item @@chapter
1768: @itemx @@unnumbered
1769: @itemx @@appendix
1770: For chapters and chapter-like parts of a document.
1771:
1772: @item @@section
1773: @itemx @@unnumberedsec
1774: @itemx @@appendixsec
1775: For sections and section-like parts of a document.
1776:
1777: @item @@subsection
1778: @itemx @@unnumberedsubsec
1779: @itemx @@appendixsubsec
1780: For subsections and subsection-like parts of a document.
1781:
1782: @item @@subsubsection
1783: @itemx @@unnumberedsubsubsec
1784: @itemx @@appendixsubsubsec
1785: For subsubsections and subsubsection-like parts of a document.
1786: @end table
1787: @end group
1788:
1789: In the sections that follow, the chapter structuring commands are described
1790: first and then the @code{@@node} and @code{@@menu} commands.
1791:
1792: @menu
1793: * Chapter::
1794: * Unnumbered and Appendix::
1795: * Section::
1796: * Subsection::
1797: * Subsubsection::
1798: * Node::
1799: * Menu::
1800: @end menu
1801:
1802: @node Chapter, Unnumbered and Appendix, , Structuring
1803: @comment node-name, next, previous, up
1804: @section @@chapter
1805: @findex chapter
1806:
1807: @code{@@chapter} identifies a chapter in the document. It is followed by a
1808: single argument which is the rest of the line, as in
1809:
1810: @example
1811: @@chapter Node and Chapter Structuring
1812: @end example
1813:
1814: In @TeX{}, it creates a chapter in the document, specifying the chapter
1815: title.
1816:
1817: In the Info file, @code{@@chapter} causes its argument to appear on a line
1818: by itself, with a line of asterisks inserted underneath. Thus, the above
1819: example produces the following output:@refill
1820:
1821: @example
1822: Node and Chapter Structuring
1823: ****************************
1824: @end example
1825:
1826: @node Unnumbered and Appendix, Section, Chapter, Structuring
1827: @comment node-name, next, previous, up
1828: @section @@unnumbered, @@appendix
1829: @findex unnumbered
1830: @findex appendix
1831:
1832: These commands are equivalent to @code{@@chapter} for Info file output.
1833: (@xref{Chapter}.) In a printed manual, they generate chapters that are
1834: numbered differently in the table of contents. @code{@@unnumbered}
1835: chapters appear without chapter numbers of any kind, and @code{@@appendix}
1836: chapters are given a letter instead of a number.
1837:
1838: @node Section, Subsection, Unnumbered and Appendix, Structuring
1839: @comment node-name, next, previous, up
1840: @section @@section
1841: @findex section
1842:
1843: @code{@@section} is like @code{@@chapter} except that in @TeX{} it makes a
1844: section rather than a chapter. (@xref{Chapter}.) Sections go within
1845: chapters. In the Info file, @code{@@chapter} and @code{@@section} differ
1846: only in that @code{@@section} underlines with @samp{=}. For example,@refill
1847:
1848: @example
1849: This is a section
1850: =================
1851: @end example
1852:
1853: @section @@unnumberedsec, @@appendixsec
1854: @findex unnumberedsec
1855: @findex appendixsec
1856:
1857: Use these constructs for sections within chapters made by
1858: @code{@@unnumbered} or @code{@@appendix}. (@xref{Section}.)@refill
1859:
1860: @node Subsection, Subsubsection, Section, Structuring
1861: @comment node-name, next, previous, up
1862: @section @@subsection
1863: @findex subsection
1864:
1865: Subsections are to sections as sections are to chapters. (@xref{Section}.)
1866: They are underlined with @samp{-}. For example,@refill
1867:
1868: @example
1869: This is a subsection
1870: --------------------
1871: @end example
1872:
1873: @section @@unnumberedsubsec, @@appendixsubsec
1874: @findex unnumberedsubsec
1875: @findex appendixsubsec
1876:
1877: Use these constructs for subsections within sections within chapters made
1878: by @code{@@unnumberedsec} or @code{@@appendixsec}. (@xref{Subsection}.)@refill
1879:
1880: @node Subsubsection, Node, Subsection, Structuring
1881: @comment node-name, next, previous, up
1882: @section @@subsubsection, @@unnumberedsubsubsec, @@appendixsubsubsec
1883: @findex unnumberedsubsubsec
1884: @findex appendixsubsubsec
1885: @findex subsubsection
1886:
1887: Subsubsections are to subsections as subsections are to sections.
1888: (@xref{Subsection}.) They are underlined with periods. The equivalent
1889: commands for @code{@@unnumberedsubsec} and @code{@@appendixsubsec} are
1890: @code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec}. For
1891: example,@refill
1892:
1893: @example
1894: This is a subsubsection
1895: .......................
1896: @end example
1897:
1898:
1899: @node Node, Menu, Subsubsection, Structuring
1900: @comment node-name, next, previous, up
1901: @section @@node
1902:
1903: @code{@@node} defines the beginning of a new node in the Info output file
1904: (@inforef{Top, info, info}.). It is followed by four arguments, separated
1905: by commas, that make up the rest of the line. Since it is often hard to
1906: remember the order in which are arguments are listed, @code{texinfo-mode}
1907: provides the @kbd{C-c C-c n} command (@code{texinfo-insert-@@node}) which
1908: automatically inserts a comment line listing the arguments. For
1909: example,@refill
1910:
1911: @example
1912: @@node Texinfo Mode, Beginning a File, Overview, Top
1913: @@comment node-name, next, previous, up
1914: @end example
1915:
1916: @noindent
1917: defines a node named @samp{Texinfo Mode}, whose `Next' pointer is to node
1918: @samp{Beginning a File}, whose `Previous' pointer is to node
1919: @samp{Overview}, and whose `Up' pointer is to node @samp{Top}. What this
1920: means is that Texinfo changes @w{@code{@@node @var{args}}} into the special
1921: text string necessary to separate Info nodes and to identify the node that
1922: is starting and say what nodes it points to.@refill
1923:
1924: The pointer names should be the names of nodes defined elsewhere. For this
1925: example, nodes named @samp{Beginning a File}, @samp{Overview} and
1926: @samp{Top} should be defined elsewhere in the file with other @code{@@node}
1927: commands. It does not matter whether they are before or after the node
1928: that refers to them.@refill
1929:
1930: Normally, a node's `Up' pointer should point at the node whose menu
1931: mentions that node. The node's `Next' pointer should point at the node
1932: that follows that node and its `Previous' pointer should point at the node
1933: that precedes it in that menu.@refill
1934:
1935: In @TeX{}, @code{@@node} is nearly ignored. It generates no text. Its
1936: only function is to identify the name to use for cross-references to the
1937: chapter or section which follows the @code{@@node} command and which which
1938: makes up the body of the node. (Cross references are made with
1939: @code{@@xref}. @xref{Cross References}.)@refill
1940:
1941: @code{@@node} should be followed immediately by a chapter-structuring
1942: command such as @code{@@chapter}, @code{@@section}, @code{@@subsection} or
1943: @code{@@subsubsection}.@refill
1944:
1945: The easiest way to write a node is to use the Texinfo mode keyboard command
1946: @kbd{C-c C-c n} to insert @samp{@@node} and a comment line listing the
1947: names of each of the pointers in their proper order. This way you won't
1948: lose track of which arguments are for which pointers. The template is
1949: especially useful if you are not familiar with Texinfo. It is important to
1950: pick a suitable node name. Generally, these begin with an uppercase letter
1951: as if the node name were a heading for a chapter or section. Do not use
1952: any of the Texinfo @@-commands in the name; these commands confuse Info.
1953: The node name should be informative. Unfortunately, long names will not
1954: fit onto the line, which can be awkward. Sometimes it is better to use
1955: long but informative names rather than short ones.
1956:
1957: Some people insert the names of the `Next', `Previous' and `Up' pointers at
1958: the same time they insert the node's own name. This is because it is
1959: easier to keep track of the node structure as you create a document than it
1960: is to sort it out after you have dozens of nodes. Others wait to insert
1961: the `Next', `Previous' and `Up' pointers until they have a nearly final
1962: version of the document. This is because they expect to change the
1963: organization of the document while they write it and insert or delete
1964: sections and move them around. The command @code{texinfo-show-structure}
1965: can be used to find the `Next', `Previous' and `Up' pointers of a node.
1966: (See @xref{Using texinfo-show-structure}.)
1967:
1968: However you do it, it is best to name the node whenever you write the
1969: section so you can easily make cross references to the section. A large
1970: number of cross references are an especially important feature of a good
1971: Info file.
1972:
1973: After you have inserted the node-line, you should immediately write an
1974: @@-command for the chapter or section and insert its name. Next, (and this
1975: is important!), put in several index entries. Usually, you will find at
1976: least two and often as many as four or five ways of referring to the node
1977: in the index. Use them all. This will make it much easier for people to
1978: find the node.@refill
1979:
1980: The top node of the file, named @samp{Top}, should have as its parent the
1981: name of a node in another file, where there is a menu that leads to this
1982: file. Specify the file name in parentheses. If the file is to be
1983: installed directly in the Info directory file, use @samp{(dir)} as the
1984: parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
1985: in the file @file{dir}, which is the main menu of Info. For example,@refill
1986:
1987: @example
1988: @@node Top, Overview, (dir), (dir)
1989: @@comment node-name, next, previous, up
1990: @end example
1991:
1992: For more information about installing an Info file in the @file{info}
1993: directory, @pxref{Installing an Info File}
1994:
1995: @node Menu, , Node, Structuring
1996: @comment node-name, next, previous, up
1997: @section @@menu
1998: @cindex Menus
1999: @findex menu
2000:
2001: Info file nodes can contain @dfn{menus} which point to other nodes. You
2002: must type the menus in by hand, and surround them with lines containing
2003: @code{@@menu} and @code{@@end menu}. In Info, the @code{@@menu} line
2004: changes into @samp{* Menu:}, which indicates the beginning of a menu to the
2005: Info program. Otherwise, the contents are unchanged by Texinfo, except for
2006: the processing of any other @@-commands within. The entire menu construct
2007: has no effect in the printed manual and will not appear there.@refill
2008:
2009: By convention, a menu is put at the end of a node. This way, it is easy
2010: for someone using Info to find the menu, using the @kbd{M->}
2011: (@code{end-of-buffer}) command.
2012:
2013: In a menu, every line that begins with a @samp{*} lists a single topic. A
2014: line that does not start with a @samp{*} will also appear in the menu and
2015: can be used as a comment.
2016:
2017: A menu item has three parts:
2018:
2019: @enumerate
2020: @item
2021: The menu item name.
2022:
2023: @item
2024: The name of the node.
2025:
2026: @item
2027: A description of the item.
2028: @end enumerate
2029:
2030: @noindent
2031: Only the first part is required. This part is the name of the topic---the
2032: name of the menu item that the user must give to the @kbd{m} command to
2033: select this topic when using Info. The first part comes right after the
2034: asterisk and a space, and is followed by a colon, spaces and tabs, and then
2035: the name of the node which discusses that topic. The name of the node is
2036: terminated by a tab, comma, newline or period. If the node name and topic
2037: name are the same, rather than give the name twice, put two colons after
2038: the name instead. For example, @samp{* Name::}. (You should do this
2039: whenever possible, since it reduces visual clutter in the menu).
2040:
2041: If the second part is present, it may be terminated with a tab, comma, or
2042: newline; or with a period.
2043:
2044: For example,@refill
2045:
2046: @group
2047: @example
2048: @@menu
2049: A Section on Foo and Switches
2050: * Foo:: The node named Foo tells you how to go fooing.
2051: * Sw: Switches. Type @@code@{m Sw@} to see node @@code@{Switches@}
2052: which describes the switches available here.
2053: @@end menu
2054: @end example
2055: @end group
2056:
2057: @noindent
2058: produces
2059:
2060: @group
2061: @example
2062: * menu:
2063:
2064: A Section on Foo and Switches
2065: * Foo:: The node named foo tells you how to go fooing.
2066: * Sw: Switches. Type `m Sw' to see node `Switches'
2067: which describes the switches available here.
2068: @end example
2069: @end group
2070:
2071: In this example, the menu has two items. @samp{Foo} is both a menu item
2072: name and the name of the node referred to by that item. @samp{Sw} is the
2073: other menu item name, and it refers to the node named @samp{Switches}.
2074: Since no file name is specified with @samp{Foo} or @samp{Switches}, they
2075: must be the names of other nodes in the same Info file.
2076:
2077: Nodes in other Info files can be referred to by putting the file name in
2078: parentheses at the beginning of the node name. For example,
2079:
2080: @example
2081: @@menu
2082: * Outlining: (emacs) Outline Mode. The major mode for editing outlines.
2083: * Rebinding: (emacs) Rebinding. How to redefine the meaning of a key.
2084: @@end menu
2085: @end example
2086:
2087: @noindent
2088: When this is done, the item has to have at least two parts: the first part
2089: is the menu item name and the second part is the name of the node.
2090:
2091: @node Quotations and Examples, Lists and Tables, Structuring, Top
2092: @comment node-name, next, previous, up
2093: @chapter Making Quotations and Examples
2094: @cindex Quotations
2095: @cindex Examples
2096:
2097: Quotations and examples are blocks of text, consisting of one or more whole
2098: paragraphs that are set off from the bulk of the text and treated
2099: differently. They are usually indented.
2100:
2101: In Texinfo, an insertion is always begun by writing an @@-command on a line
2102: by itself, and ended by writing an @code{@@end} command that is also on a
2103: line by itself. For instance, an @dfn{example} is a kind of insertion that
2104: is begun with @code{@@example} and ended with @code{@@end example}.@refill
2105: @findex end
2106:
2107: There are three commands for quotations and examples:
2108:
2109: @table @code
2110: @item @@quotation
2111: Used to indicated text that is quoted.@refill
2112:
2113: @item @@example
2114: Used to illustrate code, commands and the like in a fixed width font
2115: without filling.@refill
2116:
2117: @item @@display
2118: Used for illustrative text.
2119: @end table
2120:
2121: @menu
2122: * Quotation::
2123: * Example::
2124: * Display::
2125: @end menu
2126:
2127: @node Quotation, Example, , Quotations and Examples
2128: @comment node-name, next, previous, up
2129: @section @@quotation
2130: @cindex Quotations
2131: @findex quotation
2132:
2133: @code{@@quotation} is used to indicate text that is excerpted from another
2134: (real or hypothetical) printed work. The inside of a quotation is
2135: processed normally except that
2136:
2137: @enumerate
2138: @item
2139: The margins are narrower.
2140: @item
2141: Paragraphs are not indented.
2142: @item
2143: Interline spacing and interparagraph spacing are reduced.
2144: @end enumerate
2145:
2146: Thus, the input
2147:
2148: @example
2149: @@quotation
2150: This is
2151: a foo.
2152: @@end quotation
2153: @end example
2154:
2155: @noindent
2156: produces in the printed manual
2157:
2158: @quotation
2159: @quotation
2160: This is a foo.
2161: @end quotation
2162: @end quotation
2163:
2164: @noindent
2165: and in the Info file
2166:
2167: @quotation
2168: @example
2169: This is
2170: a foo.
2171: @end example
2172: @end quotation
2173:
2174: @node Example, Display, Quotation, Quotations and Examples
2175: @comment node-name, next, previous, up
2176: @section @@example
2177: @cindex Examples
2178: @findex example
2179:
2180: @code{@@example} is used to indicate an example that is not part of the
2181: running text. In the printed manual, this is done by switching to
2182: a fixed width font, turning off filling, and making extra spaces
2183: and blank lines significant. In the Info file, an analogous result
2184: is obtained by indenting each line with five extra spaces.
2185:
2186: @code{@@example} should appear on a line by itself; this line will
2187: disappear from the output. Mark the end of the example with a line
2188: containing @code{@@end example}, which will likewise disappear. For
2189: example:@refill
2190:
2191: @example
2192: @@example
2193: mv foo bar
2194: @@end example
2195: @end example
2196:
2197: @noindent
2198: produces
2199:
2200: @example
2201: mv foo bar
2202: @end example
2203:
2204: Since the lines containing @code{@@example} and @code{@@end example} will
2205: disappear, you will want to put a blank line before the @code{@@example} and
2206: another blank line after the @code{@@end example}. (Remember that blank
2207: lines between the beginning @code{@@example} and the ending @code{@@end
2208: example} will appear in the output.)@refill
2209:
2210: Don't use tabs in lines of an example! @TeX{} has trouble with tabs: it
2211: treats them like single spaces, and that is not what they look like.
2212:
2213: @node Display, , Example, Quotations and Examples
2214: @comment node-name, next, previous, up
2215: @section @@display
2216: @cindex Display
2217: @findex display
2218:
2219: @code{@@display} is just like @code{@@example} except that, in the
2220: printed manual, @code{@@display} does not select the fixed-width font.
2221: In fact, it does not specify the font at all, so that the text appears
2222: in the same font it would have appeared in without the @code{@@display}.@refill
2223:
2224:
2225: @node Lists and Tables, Cross References, Quotations and Examples, Top
2226: @comment node-name, next, previous, up
2227: @chapter Making Lists and Tables
2228: @cindex Making lists and tables
2229: @cindex Lists and tables, making them
2230: @cindex Tables and lists, making them
2231:
2232: Texinfo has several ways of making lists and two-column tables. Lists can
2233: be bulleted or numbered while two-column tables can highlight the items in
2234: the first column.
2235:
2236: For example, this is an enumerated list:
2237:
2238: @enumerate
2239: @item
2240: This is a numbered item.
2241:
2242: @item
2243: This is the second item in this list.
2244:
2245: @item
2246: This is the third item on this list.
2247: @end enumerate
2248:
2249: Texinfo will automatically indent the text in lists or tables and number an
2250: enumerated list. This last feature is useful if you are reordering the
2251: list, since you do not have to renumber it yourself.
2252:
2253: Lists or tables are always begun by an @@-command on a line by itself and
2254: ended with an @code{@@end} command on a line by itself. For example, an
2255: enumerated list begins with the command @code{@@enumerate} and ends with
2256: the command @code{@@end enumerate}; and an itemized list begins with the
2257: command @code{@@itemize} and ends with the command @code{@@end
2258: itemize}.@refill
2259: @findex end
2260:
2261: The elements of a list are begun with the @code{@@item} command.
2262:
2263: Here is an itemized list of the different kinds of table and lists:
2264:
2265: @itemize @bullet
2266: @item
2267: Itemized lists with or without bullets.
2268:
2269: @item
2270: Numbered lists.
2271:
2272: @item
2273: two-column tables with highlighting.
2274: @end itemize
2275:
2276: @menu
2277: * Itemize::
2278: * Enumerate::
2279: * Table::
2280: @end menu
2281:
2282: @node Itemize, Enumerate, , Lists and Tables
2283: @comment node-name, next, previous, up
2284: @section @@itemize
2285: @cindex Itemize
2286: @findex itemize
2287:
2288: @code{@@itemize} is used to produce sequences of indented paragraphs, with
2289: a mark inside the left margin at the beginning of each paragraph. The rest
2290: of the line that starts with @code{@@itemize} should contain the character
2291: or Texinfo commands to generate such a mark. Usually, it is the @@-command
2292: @code{@@bullet}. Whatever mark you choose, ultimately, it should result in
2293: a single character in the Texinfo file, or the indentation will come out
2294: wrong. When you write the command, omit the @samp{@{@}} after the command
2295: if you use just one command and nothing else.
2296:
2297: The text of the indented paragraphs themselves come after the @code{@@itemize},
2298: up to another line that says @code{@@end itemize}.
2299:
2300: Before each paragraph for which a mark in the margin is desired, place a
2301: line that says just @code{@@item}. Don't put any other text on this line.
2302: @findex item
2303:
2304: Info indents the lines in an itemized list by five columns, but it does not
2305: fill them. This can produce lines in the Info file that are too wide. You
2306: can either write shorter lines in the Texinfo file by setting the fill
2307: column to five columns less than it is normally, or else you can tell Info
2308: to refill the paragraphs by adding the @@-command @code{@@refill} to the
2309: end of the paragraph. (@xref{Refill}, for more information about the use of
2310: the @code{@@refill} command.)
2311:
2312: Usually, you should put a blank line before an @code{@@item}. This puts a
2313: blank like in the Info file. Except when the entries are very brief, a
2314: blank line looks better.
2315:
2316: Here is an example of the use of @code{@@itemize}, followed by the output
2317: it produces. Note that @code{@@bullet} produces a @samp{*} in Texinfo and
2318: a round dot in @TeX{}.
2319:
2320: @group
2321: @example
2322: @@itemize @@bullet
2323: @@item
2324: Some text for foo.
2325:
2326: @@item
2327: Some text
2328: for bar.
2329: @@end itemize
2330: @end example
2331: @end group
2332:
2333: @noindent
2334: produces
2335:
2336: @group
2337: @quotation
2338: @itemize @bullet
2339: @item
2340: Some text for foo.
2341:
2342: @item
2343: Some text
2344: for bar.
2345: @end itemize
2346: @end quotation
2347: @end group
2348:
2349: @node Enumerate, Table, Itemize, Lists and Tables
2350: @comment node-name, next, previous, up
2351: @section @@enumerate
2352: @cindex Enumerate
2353: @findex enumerate
2354:
2355: @code{@@enumerate} is like @code{@@itemize} except that the marks in the
2356: left margin contain successive integers starting with 1. (@xref{Itemize}.)
2357: Do not put any argument on the same line as @code{@@enumerate}.@refill
2358:
2359: @group
2360: @example
2361: @@enumerate
2362: @@item
2363: Some text for foo.
2364: @@item
2365: Some text
2366: for bar.
2367: @@end enumerate
2368: @end example
2369: @end group
2370:
2371: @noindent
2372: produces
2373:
2374: @quotation
2375: @enumerate
2376: @item
2377: Some text for foo.
2378: @item
2379: Some text
2380: for bar.
2381: @end enumerate
2382: @end quotation
2383:
2384: If you want, you can put a blank line between the entries in the list.
2385: This often makes it easier to read the Info file. For example,
2386:
2387:
2388: @group
2389: @example
2390: @@enumerate
2391: @@item
2392: This is the first item.
2393:
2394: @@item
2395: This is the second item.
2396: @@end enumerate
2397: @end example
2398: @end group
2399:
2400: @ifinfo
2401: Info indents the lines of the enumerated list by five columns, but it does
2402: not fill them. As a result, the lines in the Info file may be too wide.
2403: To prevent this, you can either write shorter lines in the Texinfo file
2404: file by setting the fill column to five columns less than it is normally,
2405: or else you can tell Info to refill the paragraphs by adding the @@-command
2406: @code{@@refill} to the end of the paragraph. (@xref{Refill}, for more
2407: information about the use of the @code{@@refill} command.)
2408: @end ifinfo
2409:
2410: @iftex
2411: Info indents the lines of the enumerated list by five columns, but it does
2412: not fill them, just as it does with an itemized list. You may want to use
2413: shorter lines for text within an enumerated list or use the @code{@@refill}
2414: command at the end of the paragraph. (@xref{Refill}, for more information
2415: about the use of the @code{@@refill} command.)
2416: @end iftex
2417:
2418: @node Table, , Enumerate, Lists and Tables
2419: @comment node-name, next, previous, up
2420: @section @@table
2421: @cindex Tables, making two-column
2422: @findex table
2423:
2424: @code{@@table} is similar to @code{@@itemize}, but allows you to specify a
2425: name or heading line for each item. (@xref{Itemize}.) The command is used
2426: to produce two-column tables, and is especially useful for glossaries and
2427: explanatory exhibits.@refill
2428:
2429: You must follow each use of @code{@@item} inside of @code{@@table} with
2430: text to serve as the heading line for that item. This text is put on the
2431: same line as the @code{@@item} command. Each heading line is put into the
2432: first column of the table and the supporting text, which you put on the line
2433: following the line beginning with @code{@@item}, goes into the second
2434: column.@refill
2435: @findex item
2436:
2437: Also, @code{@@table} itself must be followed by an argument that is a
2438: Texinfo command such as @code{@@code}, @code{@@var}, @code{@@kbd} or
2439: @code{@@asis}. Although these commands are usually followed by arguments
2440: in braces, in this case you use the command name without an argument.
2441: (@code{@@item} supplies the argument.) This command will be applied to
2442: the text that goes into the first column of each item and determines how it
2443: will be highlighted. For example, @code{@@samp} will cause the text in the
2444: first column to be highlighted as if it were acted on by an @code{@@samp}
2445: command.@refill
2446:
2447: @code{@@asis} is a command that does nothing; in that case, each item will
2448: come out without highlighting, unless that particular piece of text
2449: contains @@-commands for highlighting.@refill
2450:
2451: (Various other command names might work with @code{@@table}. However, only
2452: commands that normally take arguments in braces may be used.)@refill
2453:
2454: @ifinfo
2455: Usually, you should put a blank line before an @code{@@item}. This puts a
2456: blank like in the Info file. Except when the entries are very brief, a
2457: blank line looks better.
2458: @end ifinfo
2459:
2460: The following table, for example, highlights the text in the first column
2461: as if each item were acted on by an @code{@@samp} command:@refill
2462:
2463: @example
2464: @@table @@samp
2465: @@item foo
2466: This is the text for
2467: @@samp@{foo@}.
2468:
2469: @@item bar
2470: Text for @@samp@{bar@}.
2471: @@end table
2472: @end example
2473:
2474: @noindent
2475: produces
2476:
2477: @quotation
2478: @table @samp
2479: @item foo
2480: This is the text for
2481: @samp{foo}.
2482: @item bar
2483: Text for @samp{bar}.
2484: @end table
2485: @end quotation
2486:
2487: Info indents the lines of text in the second column, but does not fill
2488: them. As a result, the lines in the Info file may be too wide. To prevent
2489: this, cause Info to refill the paragraphs after processing by adding the
2490: @@-command @code{@@refill} to the end of the paragraph. (@xref{Refill}, for
2491: more information about the use of the @code{@@refill} command.)
2492:
2493: If you want to list two or more named items with a single block of text,
2494: use the @code{@@itemx} command.
2495:
2496: @menu
2497: * Itemx::
2498: @end menu
2499:
2500: @node Itemx, , Table, Table
2501: @comment node-name, next, previous, up
2502: @subsection @@itemx
2503: @cindex Itemx
2504: @findex itemx
2505:
2506: @code{@@itemx} is used inside a @code{@@table} when you have two or more
2507: named items for the same block of text. Use @code{@@itemx} for all but the
2508: first of the items. It works exactly like @code{@@item} except that it
2509: does not generate extra vertical space above the item text.
2510: For example,@refill
2511:
2512: @example
2513: @@table @@code
2514: @@item upcase
2515: @@itemx downcase
2516: These two functions accept a character or a string as argument,
2517: and return the corresponding upper case (lower case) character
2518: or string. @@refill
2519: @@end table
2520: @end example
2521:
2522: @noindent
2523: produces
2524:
2525: @quotation
2526: @table @code
2527: @item upcase
2528: @itemx downcase
2529: These two functions accept a character or a string as argument,
2530: and return the corresponding upper case (lower case) character
2531: or string. @refill
2532: @end table
2533: @end quotation
2534:
2535: A more complicated example of the use of @code{@@itemx} comes from the
2536: chapter on structuring commands. Here is how the list showing how
2537: the chapter structuring commands fall into four groups was constructed.
2538: (@xref{Structuring, , Chapter Structuring Commands}.)
2539:
2540: @group
2541: @example
2542: @@table @@code
2543: @@item @@@@chapter
2544: @@itemx @@@@unnumbered
2545: @@itemx @@@@appendix
2546: For chapters and chapter-like parts of a document.
2547:
2548: @@item @@@@section
2549: @@itemx @@@@unnumberedsec
2550: @@itemx @@@@appendixsec
2551: For sections and section-like parts of a document.
2552:
2553: @@item @@@@subsection
2554: @@itemx @@@@unnumberedsubsec
2555: @@itemx @@@@appendixsubsec
2556: For subsections and subsection-like parts of a document.
2557:
2558: @@item @@@@subsubsection
2559: @@itemx @@@@unnumberedsubsubsec
2560: @@itemx @@@@appendixsubsubsec
2561: For subsubsections and similar parts of a document.
2562: @@end table
2563: @end example
2564: @end group
2565:
2566: @noindent
2567: and this is what the resulting table looks like:
2568:
2569:
2570: @table @code
2571:
2572: @item @@chapter
2573: @itemx @@unnumbered
2574: @itemx @@appendix
2575: For chapters and chapter-like parts of a document.
2576:
2577: @item @@section
2578: @itemx @@unnumberedsec
2579: @itemx @@appendixsec
2580: For sections and section-like parts of a document.
2581:
2582: @item @@subsection
2583: @itemx @@unnumberedsubsec
2584: @itemx @@appendixsubsec
2585: For subsections and subsection-like parts of a document.
2586:
2587: @item @@subsubsection
2588: @itemx @@unnumberedsubsubsec
2589: @itemx @@appendixsubsubsec
2590: For subsubsections and similar parts of a document.
2591: @end table
2592:
2593:
2594: Also, either column of a table can be empty.
2595:
2596: @node Cross References, Formatting Paragraphs, Lists and Tables, Top
2597: @comment node-name, next, previous, up
2598: @chapter Making Cross References
2599: @cindex Making cross references
2600: @cindex Cross references
2601: @cindex References
2602:
2603: Cross references are used to refer the reader to other parts of the same or
2604: different Texinfo files. In Texinfo, @dfn{nodes} are the points to which
2605: cross-references can refer.
2606:
2607: In general, a document should be designed so that it can be read
2608: sequentially. People soon tire of flipping back and forth to find
2609: information that should be presented to them as they need it. However,
2610: there will be information (often too detailed for whatever the current
2611: context may be) that is related to whatever is presented and to which
2612: reference should be made. More important, in an on-line help system or in
2613: a reference manual, readers do @emph{not} read everything in sequence from
2614: beginning to end. Instead, they look up what they need. For this reason,
2615: such creations should contain many cross references to help the reader find
2616: other information that he or she may not have read.
2617:
2618: Although nodes are not a fundamental concept in a printed manual, they
2619: still serve to define a cross-reference point and the variants of
2620: @code{@@xref} still serve to make references. Thus, if you are writing a
2621: manual that will only be printed, and will not be used on-line, you
2622: continue to use the @code{@@node} command for when you make cross
2623: references.
2624:
2625: There are several kinds of cross reference command.
2626:
2627: @table @code
2628: @item @@xref
2629: Used to start a sentence in the printed manual saying, `See @dots{}' @*
2630: or an entry in the Info file saying @samp{*note @dots{}}.
2631:
2632: @item @@pxref
2633: Used to make a reference that starts with a lowercase @samp{see} @*
2634: and is usually contained within parentheses.@refill
2635:
2636: @item @@inforef
2637: Used to make a reference to an Info file for which there is no printed
2638: manual.@refill
2639: @end table
2640:
2641: @menu
2642: * Xref::
2643: * Pxref::
2644: * Inforef::
2645: @end menu
2646:
2647:
2648: @node Xref, Pxref, Cross References, Cross References
2649: @comment node-name, next, previous, up
2650: @section @@xref
2651: @cindex Xref for cross references
2652: @findex xref
2653: @cindex Cross references using xref
2654:
2655: @code{@@xref} generates a cross-reference. In Texinfo, it turns into
2656: an Info cross-reference which the Info @samp{f} command can use
2657: to go directly to another node. In @TeX{}, it turns into a sentence
2658: of the form
2659:
2660: @example
2661: See section @var{section} [@var{topic}], page @var{page}
2662: @end example
2663:
2664: @noindent
2665: but does not generate a period to end it.
2666:
2667: @code{@@xref} must refer to an Info node created by @code{@@node}, by the
2668: node's name.
2669:
2670: @code{@@xref} is followed by an argument inside braces; but actually the
2671: text inside the braces is treated as several arguments, separated by
2672: commas. Whitespace after these commas is ignored. A period or comma
2673: @strong{must} follow the closing brace of an @code{@@xref}. It is required
2674: to terminate the cross reference. This period or comma will appear in the
2675: output, both in the Info file and in the printed manual.
2676:
2677: The simplest form of @code{@@xref} takes one argument, the name of another
2678: node in the same Info file. Here we show the input text, followed by a
2679: blank line and then the output text for Info files and the output text for
2680: printed manuals.
2681:
2682: @example
2683: @@xref@{node-name@}, for more info.
2684:
2685: *note node-name::, for more info.
2686: @end example
2687:
2688: @quotation
2689: See section @var{nnn} [node-name], page @var{ppp}, for more info.
2690: @end quotation
2691:
2692: With two arguments, the second one is used as the name of the Info
2693: cross-reference, while the first argument is still the node that the
2694: cross-reference points to:
2695:
2696: @example
2697: @@xref@{node-name, name-for-note@}, for more info.
2698:
2699: *note name-for-note: node-name, for more info.
2700: @end example
2701:
2702: @quotation
2703: See section @var{nnn} [node-name], page @var{ppp}, for more info.
2704: @end quotation
2705:
2706: A third argument replaces the node name when it actually appears in the
2707: @TeX{} output. It should state the topic discussed by the section being
2708: referenced. Often, you will want to use initial uppercase letters so it
2709: will be easier to read when the reference is printed. Use a third argument
2710: when the node name is unsuitable because of syntax, grammar or diction.
2711:
2712: @example
2713: @@xref@{node-name, name-for-note, Topic Description@}, for more info.
2714:
2715: *note name-for-note: node-name, for more info.
2716: @end example
2717:
2718: @quotation
2719: See section @var{nnn} [Topic Description], page @var{ppp}, for more info.
2720: @end quotation
2721:
2722: If a third argument is given and the second one is empty,
2723: then the third argument serves both purposes:
2724:
2725: @example
2726: @@xref@{node-name, , Topic Description@}, for more info.
2727:
2728: *note Topic Description: node-name, for more info.
2729: @end example
2730:
2731: @quotation
2732: See section @var{nnn} [Topic Description], page @var{ppp}, for more info.
2733: @end quotation
2734:
2735: A fourth argument specifies the name of the Info file in which the
2736: referenced node is located, assuming it is not the one in which the
2737: reference appears. @code{@@xref} with only four arguments is used when the
2738: reference is not within one Info file, but is within a single printed
2739: manual---when multiple Texinfo files are incorporated into the same @TeX{}
2740: run but make separate Info files. (This is seldom the case and usually you
2741: will use five arguments if you are making a reference that is outside the
2742: current Info file.)
2743:
2744: @example
2745: @@xref@{node-name, name-for-note, Topic, info-file-name@},
2746: for more info.
2747:
2748: *note name-for-note: (info-file-name) node-name, for more info.
2749: @end example
2750:
2751: @quotation
2752: See section @var{nnn} [Topic], page @var{ppp}, for more info.
2753: @end quotation
2754:
2755: A fifth argument is used when you are making a reference to another Info
2756: file which is also part of another printed manual. Write the title of the
2757: manual in this slot. Since a different manual is made during a different
2758: @TeX{} run, the printed reference will not have a page number.
2759:
2760: @noindent
2761: Whenever you refer to another manual, use this version of @code{@@xref}
2762: with five arguments.
2763:
2764: @example
2765: @@xref@{node-name, name-for-note, Topic, info-file-name, A Printed Manual@},
2766: for more info.
2767:
2768: *note name-for-note: (info-file-name) node-name, for more info.
2769: @end example
2770:
2771: @quotation
2772: See section Topic of @i{A Printed Manual}, for more info.
2773: @end quotation
2774:
2775: @noindent
2776: The name of the printed manual will be typeset in italics.
2777:
2778: Often, you will leave out the second argument when you use the long version
2779: of @code{@@xref}. In this case, the third argument, the topic description,
2780: will replace the node name:
2781:
2782:
2783: @example
2784: @@xref@{node-name, , Topic Description, info-file-name, A Printed Manual@},
2785: for more info.
2786:
2787: *note Topic Description: (info-file-name) node-name, for more info.
2788: @end example
2789:
2790: @quotation
2791: See section Topic Description of @i{A Printed Manual}, for more info.
2792: @end quotation
2793:
2794:
2795: @node Pxref, Inforef, Xref, Cross References
2796: @comment node-name, next, previous, up
2797: @section @@pxref
2798: @cindex Cross references using pxref
2799: @cindex Pxref for cross references
2800: @findex pxref
2801:
2802: @code{@@pxref} is nearly the same as @code{@@xref}; it differs in only
2803: two ways:
2804:
2805: @enumerate
2806: @item
2807: The output starts with lower case `see' rather than `See'.@refill
2808: @item
2809: A period is generated automatically in the Info file output to end the Info
2810: cross-reference, but no period is generated for the printed manual.@refill
2811: @end enumerate
2812:
2813: The purpose of @code{@@pxref} is to be used inside parentheses as part of
2814: another sentence. In the printed manual, no period is needed after the
2815: cross reference text itself (within the parentheses), but a period is
2816: needed after the cross reference text in the Info file because only thus
2817: can Info recognize the end of the cross-reference. @code{@@pxref} spares
2818: you the need to use complicated methods to put a period into one form of
2819: the output and not the other.
2820:
2821: @code{@@pxref} can be used with up to five arguments just like
2822: @code{@@xref}. (@xref{Xref}.)@refill
2823:
2824: @node Inforef, , Pxref, Cross References
2825: @comment node-name, next, previous, up
2826: @section @@inforef
2827: @cindex Inforef for cross references
2828: @cindex Cross references using inforef
2829: @findex inforef
2830:
2831: @code{@@inforef} is used for cross-references to Info files for which there
2832: are no printed manuals. Even in a printed manual, @code{@@inforef}
2833: generates a reference directing the user to look in an Info file.
2834: @code{@@inforef} takes exactly three arguments. The syntax is
2835: @code{@@inforef@{@var{node}, @var{name}, @var{file}@}}.
2836:
2837: @example
2838: @@inforef@{node-name, name-for-note, info-file-name@}, for more information.
2839:
2840: *note name-for-note: (info-file-name) node-name, for more information.
2841: @end example
2842:
2843: @quotation
2844: See Info file @file{info-file-name}, node `node-name', for more information.
2845: @end quotation
2846:
2847: @node Formatting Paragraphs, Marking Text, Cross References, Top
2848: @comment node-name, next, previous, up
2849: @chapter Formatting Paragraphs
2850: @cindex Formatting paragraphs
2851: @cindex Paragraphs, formatting
2852:
2853: Usually, a Texinfo file will be processed both by @TeX{} and by the
2854: @kbd{M-x texinfo-format-buffer} command. Consequently, you must make sure
2855: that text will come out looking right both in the printed manual and in the
2856: on-line help.@refill
2857:
2858: For example, unless told otherwise, @kbd{M-x texinfo-format-buffer} will
2859: not refill a paragraph after processing it although @TeX{} will. This
2860: means that a paragraph with numerous or large @@-commands may not look
2861: properly filled after processing by Info. The @@-commands are removed from
2862: the text but the lines are not refilled so some are much shorter than they
2863: were. To cause the @kbd{M-x texinfo-format-buffer} command to refill such
2864: a paragraph, put @code{@@refill} at the end of the paragraph.@refill
2865:
2866: @TeX{} may also format a document improperly. For example, page breaks may
2867: occur in the ``wrong place''; to control this, text can be held together by a
2868: group command that keeps the text within the group from being split across
2869: two pages.
2870:
2871: @iftex
2872: The first section that follows is about refilling and preventing
2873: indentation; the second section is about line and paragraph breaks,
2874: creating blank lines, and grouping text.
2875: @end iftex
2876:
2877: @menu
2878: * Refilling & Noindent:: Refilling paragraphs & preventing indentation
2879: * Breaks Blank-Lines Groups:: Line and paragraph breaks, blank lines, grouping
2880: @end menu
2881:
2882: @node Refilling & Noindent, Breaks Blank-Lines Groups, Formatting Paragraphs, Formatting Paragraphs
2883: @comment node-name, next, previous, up
2884: @section Refilling Paragraphs and Preventing Indentation
2885: @cindex Refilling paragraphs automatically
2886: @cindex Preventing indentation in the printed text
2887:
2888: The @code{@@refill} and @code{@@noindent} commands are used just after or
2889: just before paragraphs which, after processing by either Info or @TeX{},
2890: might look bad. The @code{@@refill} command refills a paragraph in the
2891: Info file after all the other processing has been done. In the printed
2892: manual, the @code{@@noindent} command prevents a piece of text that is a
2893: continuation of the preceding paragraph from being indented as if it were a
2894: new paragraph.@refill
2895:
2896: @menu
2897: * Refill:: Refilling an info paragraph after other processing.
2898: * Noindent:: Preventing paragraph indentation in continuation text.
2899: @end menu
2900:
2901: @node Refill, Noindent, Refilling & Noindent, Refilling & Noindent
2902: @comment node-name, next, previous, up
2903: @subsection @@refill
2904: @findex refill
2905:
2906: If a paragraph contains sizable @@-constructs, it may look badly filled
2907: after @code{texinfo-format-buffer} is through with it.
2908:
2909: Put @code{@@refill} at the end of the paragraph to tell
2910: @code{texinfo-format-buffer} to refill the paragraph after finishing all
2911: other processing on it. @code{@@refill} has no effect on @TeX{}, which
2912: always fills everything that ought to be filled. For example,@refill
2913:
2914: @example
2915: To use @@code@{foo@}, pass @@samp@{xx%$@} and @@var@{flag@} and type @@kbd@{x@}
2916: after running @@code@{make-foo@}.@@refill
2917: @end example
2918:
2919: @noindent
2920: produces (in the Info file)
2921:
2922: @example
2923: To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
2924: @end example
2925:
2926: @noindent
2927: whereas without the @code{@@refill} it would produce
2928:
2929: @example
2930: To use `foo', pass `xx%$' and FLAG and type `x'
2931: after running `make-foo'.
2932: @end example
2933:
2934: @noindent
2935: with the line broken at the same place as in the Texinfo input file.
2936:
2937: Do not put a space before @code{@@refill}; otherwise the command might be
2938: put at the beginning of the line when you refill the paragraph in the
2939: Texinfo file with @kbd{M-q} (@code{fill-paragraph}). If this were to
2940: happen, the @code{@@refill} command might fail to work
2941:
2942: @node Noindent, , Refill, Refilling & Noindent
2943: @comment node-name, next, previous, up
2944: @subsection @@noindent
2945: @findex noindent
2946:
2947: If you have text following an @code{@@example} or other similar ``special
2948: paragraph'' that reads as a continuation of the text before the
2949: @code{@@example}, it is good to prevent this text from being indented as a
2950: new paragraph. To accomplish this, put @code{@@noindent} on a line by
2951: itself before the start of the text that should not be indented. For
2952: example,@refill
2953:
2954: @example
2955: @@example
2956: This is an example
2957: @@end example
2958:
2959: @@noindent
2960: This line will not be indented.
2961: @end example
2962:
2963: @noindent
2964: produces
2965:
2966: @example
2967: This is an example
2968: @end example
2969:
2970: @noindent
2971: This line will not be indented.
2972:
2973: To adjust the number of blank lines properly in the Info file output,
2974: remember that the line containing @code{@@noindent} does not generate a
2975: blank line, and neither does the @code{@@end example} line.
2976:
2977: In the Texinfo source file for this documentation, each of the lines that
2978: says `produces' is preceded by a line containing @code{@@noindent}.
2979:
2980: @node Breaks Blank-Lines Groups, , Refilling & Noindent, Formatting Paragraphs
2981: @comment node-name, next, previous, up
2982: @section Breaks, Blank Lines and Groups
2983:
2984: Texinfo has several commands for making blank lines, for forcing paragraph
2985: and page breaks in the printed manual and for preventing text from running
2986: from one page to the next.
2987:
2988: @table @code
2989: @item @@*
2990: Force a line break in the printed manual. This
2991: command has no effect on the Info file.@refill
2992:
2993: @item @@sp
2994: Generate blank lines in both the printed manual and in the Info file.@refill
2995:
2996: @item @@br
2997: Force a paragraph break in the printed manual. This command has no effect
2998: on the Info file.@refill
2999:
3000: @item @@w
3001: Prevent text from being split across two lines in the printed manual. This
3002: command has no effect on the Info file.@refill
3003:
3004: @item @@page
3005: Start a new page in the printed manual. This
3006: command has no effect on the Info file.@refill
3007:
3008: @item @@group
3009: Hold text together that must appear on one printed page. This
3010: command has no effect on the Info file.@refill
3011:
3012: @item @@need
3013: Start a new printed page if required space not on this one. This
3014: command has no effect on the Info file.@refill
3015: @end table
3016:
3017: @menu
3018: * Line Breaks:: Force a line break in the printed manual.
3019: * Sp:: Generate blank lines.
3020: * Br:: Force a paragraph break in the printed manual.
3021: * W:: Prevent a paragraph break in the printed manual.
3022: * Page:: Start a new page in the printed manual.
3023: * Group:: Hold text together that must appear on one printed page.
3024: * Need:: Start a new printed page if required space not on this one.
3025: @end menu
3026:
3027:
3028: @node Line Breaks, Sp, Breaks Blank-Lines Groups, Breaks Blank-Lines Groups
3029: @comment node-name, next, previous, up
3030: @subsection @@*
3031: @findex asterisk
3032: @findex *
3033: @cindex Line breaks
3034: @cindex Breaks in a line
3035:
3036:
3037: @code{@@*} forces a line break in the printed manual. It has no effect on
3038: the Info file output, where line breaks follow those in the source file.
3039: If you want a line break at a certain spot in both forms of output, break
3040: the line there in the source file and put @code{@@*} at the end of the
3041: line.
3042:
3043:
3044: @node Sp, Br, Line Breaks, Breaks Blank-Lines Groups
3045: @comment node-name, next, previous, up
3046: @subsection @@sp
3047: @findex sp (line spacing)
3048: @cindex Spaces from line to line
3049: @cindex Line spacing
3050:
3051: A line containing @code{@@sp @var{n}} generates @var{n} blank lines of
3052: space in either the printed manual or the Info file. For example,
3053:
3054: @example
3055: @@sp 2
3056: @end example
3057:
3058: @noindent
3059: generates two blank lines.
3060:
3061: @node Br, W, Sp, Breaks Blank-Lines Groups
3062: @comment node-name, next, previous, up
3063: @subsection @@br
3064: @findex br (paragraph breaks)
3065: @cindex Paragraph breaks
3066: @cindex Breaks in a paragraph
3067:
3068: In a printed manual, a line containing @code{@@br} forces a paragraph
3069: break; in the Info file output, it does nothing (not even a blank line
3070: results from it).
3071:
3072: @node W, Page, Br, Breaks Blank-Lines Groups
3073: @comment node-name, next, previous, up
3074: @subsection @@w
3075: @findex w (preventing a line break)
3076: @cindex Line breaks, preventing
3077:
3078: In a printed manual, @code{@@w@{@var{text}@}} outputs @var{text} and prohibits
3079: line breaks within @var{text}. @code{@@w} has no effect on the Info file
3080: output; it is the same as would result from just @var{text}.
3081:
3082:
3083: @node Page, Group, W, Breaks Blank-Lines Groups
3084: @comment node-name, next, previous, up
3085: @subsection @@page
3086: @cindex Page breaks
3087: @findex page
3088:
3089: A line containing @code{@@page} starts a new page in a printed manual. The
3090: line has no effect on Info files since they are not paginated.
3091:
3092: @node Group, Need, Page, Breaks Blank-Lines Groups
3093: @comment node-name, next, previous, up
3094: @subsection @@group
3095: @cindex Group
3096: @cindex Holding text together vertically
3097: @cindex Vertically holding text together
3098: @findex group
3099:
3100: A line containing @code{@@group} begins an unsplittable vertical group,
3101: which must appear entirely on one page. The group is terminated by a line
3102: containing @code{@@end group}. These two lines produce no output of their
3103: own, and in the Info file output they have no effect at all.
3104:
3105: If you forget to end a group, you may get strange and unfathomable error
3106: messages when you run @TeX{}. This is because @TeX{} keeps trying to put
3107: the rest of the Texinfo file into the group and error messages do not start
3108: to get generated until @TeX{} has gone a long way. It's a good rule of
3109: thumb to look for a missing @code{@@end group} if you get incomprehensible
3110: error messages in @TeX{}.
3111:
3112: @node Need, , Group, Breaks Blank-Lines Groups
3113: @comment node-name, next, previous, up
3114: @subsection @@need
3115: @cindex Need
3116: @findex need
3117:
3118: A line containing @code{@@need @var{n}} starts a new page in a printed
3119: manual if fewer than @var{n} mils (thousandths of an inch) remain on the
3120: current page. The line has no effect on Info files since they are not
3121: paginated.@refill
3122:
3123: @node Marking Text, Conditionals , Formatting Paragraphs, Top
3124: @comment node-name, next, previous, up
3125: @chapter Marking Text Within a Paragraph
3126: @cindex Marking text within a paragraph
3127:
3128: In Texinfo, text within a paragraph can be marked in a variety of ways.
3129: The most important way is to specify whether a word or phrase is a
3130: definition, a metasyntactic variable, a literal example of a program or
3131: what not.
3132:
3133: In addition, there are special commands for inserting single characters
3134: that have special meaning in Texinfo, such as braces, and for inserting
3135: symbols with special handling, such as dots and bullets. Finally, there
3136: are ways to emphasize words.
3137:
3138: @menu
3139: * Specifying:: Specifying commands, files and so on.
3140: * Braces Atsigns Periods:: Inserting braces, @samp{@@} and periods.
3141: * Dots Bullets Tex:: Inserting dots, bullets and the @TeX{} logo
3142: * Emphasis:: Emphasizing text.
3143: @end menu
3144:
3145: @node Specifying, Braces Atsigns Periods, , Marking Text
3146: @comment node-name, next, previous, up
3147: @section Specifying Definitions, Files, Commands etc.
3148: @cindex Highlighting
3149: @cindex Specifying commands, files and the like
3150: @cindex Definitions, specifying them within text
3151: @cindex Commands, specifying them within text
3152: @cindex Files, specifying them within text
3153:
3154: Texinfo has a variety of commands for specifying just what kind of object a
3155: piece of text refers to. Metasyntactic variables, for example, are marked
3156: by one @@-command and code by another. Texinfo uses this information to
3157: determine how to highlight the text. Since the pieces of text are labelled
3158: by commands that tell what kind of object they are, it is easy to change
3159: the way Texinfo formats and typesets such text. For example, code is
3160: usually illustrated in a typewriter font, but it would be easy to change
3161: the way Texinfo highlights code to use another font. This change would not
3162: effect how metasyntatic variables are highlighted. If straight typesetting
3163: commands were used in the body of the file, you would have to check every
3164: single occurrence to make sure that you were changing code and not
3165: something else that should not be changed.
3166:
3167: In addition, the commands can be used to generate useful information from
3168: the file, such as lists of functions or file names. It is possible, for
3169: example, to write code in Emacs Lisp (or a keyboard macro) to insert an
3170: index entry after every paragraph that contains the text labelled by a
3171: specified command. You could do this to construct an index of functions if
3172: you had not already made the entries.
3173:
3174: The commands serve a variety of purposes:
3175:
3176: @table @code
3177: @item @@code
3178: Indicates text that is a literal example of a piece of a program.@refill
3179:
3180: @item @@samp
3181: Indicates text that is a literal example of a sequence of characters.@refill
3182:
3183: @item @@file
3184: Indicates the name of a file.@refill
3185:
3186: @item @@kbd
3187: Indicates the names of keys on the keyboard or characters you type.@refill
3188:
3189: @item @@key
3190: Used for the conventional name for a key on a keyboard.@refill
3191:
3192: @item @@ctrl
3193: Indicates an ASCII control character.
3194:
3195: @item @@var
3196: Indicates a metasyntactic variable.
3197:
3198: @item @@dfn
3199: Indicates the introductory or defining use of a term.
3200:
3201: @item @@cite
3202: Indicates the name of a book.
3203: @end table
3204:
3205:
3206:
3207: @menu
3208: * Code:: A literal example of a piece of a program.
3209: * Samp:: A literal example of a sequence of characters.
3210: * File:: The name of a file.
3211: * Kbd:: The names of keys or else characters you type.
3212: * Key:: The conventional name for a key on a keyboard.
3213: * Ctrl:: Indicates the ASCII control character.
3214: * Var:: A variable.
3215: * Dfn:: The introductory or defining use of a term.
3216: * Cite:: The name of a book.
3217: @end menu
3218:
3219: @node Code, Samp, , Specifying
3220: @comment node-name, next, previous, up
3221: @subsection @@code
3222: @findex code
3223:
3224: @code{@@code} is used to indicate text that is a piece of a program which
3225: consists of entire syntactic tokens. The text follows, enclosed in braces.
3226:
3227: For example, @code{@@code} is used for an expression in a program, the name
3228: of a variable or function used in a program, or a keyword. @code{@@code}
3229: is not used for a piece of a token, such as when speaking about the
3230: characters used in a token; for example, when you are explaining what
3231: letters or printable symbols can be used in the names of functions. It is
3232: also not used for input to programs unless the input is written in a
3233: language that is like a programming language. For example, it is not used
3234: for the single character commands of GNU Emacs although it is used for the
3235: names of Emacs Lisp functions that the keyboard commands invoke.
3236:
3237: You should also @code{@@code} for command names in command languages that
3238: resemble programming languages, such as Texinfo or the shell. Note,
3239: however, that @code{@@code} is not used for options such as @samp{-c} when
3240: such options stand alone. There is some argument as to whether an entire
3241: shell command incorporating an option should be written using @code{@@code}
3242: or @code{@@samp}.@refill
3243:
3244: It is an error to alter the case of a word inside an @code{@@code}
3245: command. This is a particularly insidious error if the language being
3246: documented is case sensitive. If the command is @code{printf}, then
3247: @code{Printf} is a misspelling. If you do not like having such a command
3248: with lower case at the beginning of a sentence, you may wish to rearrange
3249: the sentence.
3250:
3251: In the printed manual, @code{@@code} puts the argument in bold face.
3252: In the Info file, it uses `@dots{}' quotation. For example:
3253:
3254: @example
3255: To compare two files, showing text inserted or removed, use @@code@{diff@}.
3256: @end example
3257:
3258: @noindent
3259: produces
3260:
3261: @quotation
3262: To compare two files, showing text inserted or removed, use @code{diff}.
3263: @end quotation
3264:
3265: @iftex
3266: In the Info file, it looks like this:
3267:
3268: @example
3269: @dots{}, use `diff'
3270: @end example
3271: @end iftex
3272:
3273: @node Samp, File, Code, Specifying
3274: @comment node-name, next, previous, up
3275: @subsection @@samp
3276: @findex samp
3277:
3278: @code{@@samp} is used to indicate text that is a literal example of a
3279: sequence of characters in a file, string, pattern, etc. The text follows,
3280: enclosed in braces. The argument appears within `@dots{}' quotation in
3281: both the Info file and the printed manual; in addition, it is printed in a
3282: fixed-width font.
3283:
3284: @example
3285: To match @@samp@{foo@} at the end of the line, use the regexp @@samp@{foo$@}.
3286: @end example
3287:
3288: @noindent
3289: produces
3290:
3291: @quotation
3292: To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
3293: @end quotation
3294:
3295: Any time you are referring to single characters, you should use @code{@@samp}
3296: unless @code{@@kbd} is more appropriate. Basically, @code{@@samp} is a
3297: catchall for whatever is not covered by @code{@@code}, @code{@@file},
3298: @code{@@kbd}.
3299:
3300: Punctuation marks that are part of the English text that surrounds the
3301: strings you are specifying are @emph{never} included within the braces. In
3302: the following sentence, for example, the commas and period are outside of
3303: the braces:
3304:
3305: @example
3306: A symbol name ends in @@samp@{a@}, @@samp@{b@}, or @@samp@{c@}.
3307: @end example
3308:
3309: @node File, Kbd, Samp, Specifying
3310: @comment node-name, next, previous, up
3311: @subsection @@file
3312: @findex file
3313:
3314: @code{@@file} is used to indicate text that is the name of a file or
3315: directory. Currently, it is equivalent to @code{@@samp} in its effects on
3316: the output. For example,@refill
3317:
3318: @example
3319: The @@file@{.el@} files are in
3320: the @@file@{/gnu/emacs/lisp@} directory.
3321: @end example
3322:
3323: @noindent
3324: produces
3325:
3326: @quotation
3327: The @file{.el} files are in
3328: the @file{/gnu/emacs/lisp} directory.
3329: @end quotation
3330:
3331: @node Kbd, Key, File, Specifying
3332: @comment node-name, next, previous, up
3333: @subsection @@kbd
3334: @findex kbd
3335:
3336: @code{@@kbd} is used much like @code{@@code}. The difference is that
3337: @code{@@kbd} is for names of keys on the keyboard, or of characters you can
3338: type. For example, to refer to the command @kbd{M-a}, you would use
3339:
3340: @example
3341: @@kbd@{M-a@}
3342: @end example
3343:
3344: @noindent
3345: and to refer to @kbd{M-x shell}, you would use
3346:
3347: @example
3348: @@kbd@{M-x shell@}
3349: @end example
3350:
3351: The @code{@@kbd} command has the same effect as @code{@@code} in Info,
3352: but may produce a different font in a printed manual.@refill
3353:
3354: You can embed another @@-command inside the braces of a @code{@@kbd}
3355: command. This is the way to describe a command that would be described
3356: more verbosely as ``press an @samp{r} and then press the @key{RET} key'':
3357:
3358: @example
3359: @@kbd@{r @@key@{RET@}@}
3360: @end example
3361:
3362: @noindent
3363: This produces: @kbd{r @key{RET}}
3364:
3365: You also use the @code{@@kbd} command if you are spelling out the letters
3366: you type; for example:
3367:
3368: @example
3369: To give the @@code@{logout@} command,
3370: type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
3371: @end example
3372:
3373: @noindent
3374: This produces
3375:
3376: @quotation
3377: To give the @code{logout} command,
3378: type the characters @kbd{l o g o u t @key{RET}}.
3379: @end quotation
3380:
3381: @node Key, Ctrl, Kbd, Specifying
3382: @comment node-name, next, previous, up
3383: @subsection @@key
3384: @findex key
3385:
3386: @code{@@key} is used for the conventional name for a key on a keyboard, as
3387: in
3388:
3389: @example
3390: @@key@{RET@}
3391: @end example
3392:
3393: Often, @code{@@key} is used within the argument of a @code{@@kbd}
3394: command, whenever the sequence of characters to be typed includes one or
3395: more keys that are described by name.@refill
3396:
3397: For example, to produce @kbd{C-x @key{ESC}} you would use
3398:
3399: @example
3400: @@kbd@{C-x @@key@{ESC@}@}
3401: @end example
3402:
3403:
3404: The recommended names to use for keys are in upper case and are
3405:
3406: @table @t
3407: @item SPC
3408: Space.
3409: @item RET
3410: Return.
3411: @item LFD
3412: Linefeed.
3413: @item TAB
3414: Tab.
3415: @item BS
3416: Backspace.
3417: @item ESC
3418: Escape.
3419: @item DEL
3420: Delete.
3421: @item SFT
3422: Shift.
3423: @item CTL
3424: Control.
3425: @item META
3426: Meta.
3427: @end table
3428:
3429: There are subtleties to handling words like `meta' or `ctrl' which are
3430: names of shift keys. When mentioning a character in which the shift key is
3431: used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone without the
3432: @code{@@key} command, but when you are referring to shift key in isolation,
3433: use the @code{@@key} command. For example, you would use
3434: @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and @samp{@@key@{META@}} to
3435: produce @key{META}.
3436:
3437: @node Ctrl, Var, Key, Specifying
3438: @comment node-name, next, previous, up
3439: @subsection @@ctrl
3440: @findex ctrl
3441:
3442: @code{@@ctrl} is used to describe an ASCII control character. The pattern
3443: of usage is @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
3444: whose control-equivalent is wanted. Thus, you put in an @samp{f} when
3445: you want to indicate a @samp{control-f}
3446:
3447: Thus, to specify @samp{control-f}, you would enter
3448:
3449: @example
3450: @@ctrl@{f@}
3451: @end example
3452:
3453: @noindent
3454: which produces
3455:
3456: @quotation
3457: @ctrl{f}
3458: @end quotation
3459:
3460: In the Info file, this generates the specified control character, output
3461: literally into the file. This is done so a user can copy the specified
3462: control character (along with whatever else he or she wants) into another
3463: Emacs buffer and use it. Since the `control-h',`control-i', and
3464: `control-j' characters are formatting characters, they should not be
3465: indicated this way.@refill
3466:
3467: In a printed manual, this generates text to describe or identify that
3468: control character: an uparrow followed by the character @var{ch}.
3469:
3470: @node Var, Dfn, Ctrl, Specifying
3471: @comment node-name, next, previous, up
3472: @subsection @@var
3473: @findex var
3474:
3475: @code{@@var} is used to indicate metasyntactic variables. A metasyntactic
3476: variable is something that stands for another piece of text. You would use
3477: a metasyntactic variable in the documentation of a function to describe the
3478: arguments that are passed to that function.
3479:
3480: @code{@@var} is not used for names of particular variables in programming
3481: languages. For example, the Texinfo variable @code{texinfo-tex-command} is
3482: not a metasyntactic variable.
3483:
3484: Its effect in the Info file is to upcase the argument; in the printed
3485: manual, to italicize it. Example:
3486:
3487: @example
3488: To delete file @@var@{filename@}, type @@code@{rm @@var@{filename@}@}.
3489: @end example
3490:
3491: @noindent
3492: produces
3493:
3494: @quotation
3495: To delete file @var{filename}, type @code{rm @var{filename}}.
3496: @end quotation
3497:
3498: In some documentation styles, metasyntactic variables are shown with angle
3499: brackets, for example:
3500:
3501: @example
3502: @dots{}, type rm <filename>
3503: @end example
3504:
3505: @node Dfn, Cite, Var, Specifying
3506: @comment node-name, next, previous, up
3507: @subsection @@dfn
3508: @findex dfn
3509:
3510: @code{@@dfn} is used to identify the introductory or defining use of a
3511: technical term. The command should be used only in a passage whose purpose
3512: is to introduce a term which will be used again or which the reader ought
3513: to know. Mere passing mention of a term for the first time doesn't deserve
3514: @code{@@dfn}. It generates italics in the printed manual, and double
3515: quotation marks in the Info file. Example:
3516:
3517: @example
3518: Getting rid of a file is called @@dfn@{deleting@} it.
3519: @end example
3520:
3521: @noindent
3522: produces
3523:
3524: @quotation
3525: Getting rid of a file is called @dfn{deleting} it.
3526: @end quotation
3527:
3528: @node Cite, , Dfn, Specifying
3529: @comment node-name, next, previous, up
3530: @subsection @@cite
3531: @findex cite
3532:
3533: @code{@@cite} is used for the name of a book. It produces italics
3534: in the printed manual, and quotation marks in the Info file.
3535:
3536:
3537: @node Braces Atsigns Periods, Dots Bullets Tex, Specifying , Marking Text
3538: @comment node-name, next, previous, up
3539: @section Inserting Braces, @samp{@@} and Periods
3540: @cindex Inserting braces, @@ and periods
3541: @cindex Braces, inserting
3542: @cindex Periods, inserting
3543: @cindex Single characters, commands to insert
3544: @cindex Commands to insert single characters
3545:
3546: @samp{@@} and curly braces are special characters in Texinfo. This means
3547: that you have to put an @samp{@@} in front of these characters in order to
3548: insert them into text.
3549:
3550: Periods are also special. Depending on whether the period is inside of or
3551: at the end of a sentence, less or more space is inserted after a period in
3552: a typeset manual. Since it is not always possible for Texinfo to determine
3553: when a period ends a sentence and when it is used in an abbreviation,
3554: special commands are needed. (Usually, Texinfo figures out how to handle
3555: periods, so you don't have to use the special commands; you just enter a
3556: period as you would if you were using a typewriter, which means you put two
3557: spaces after the period that ends a sentence and after a colon.)@refill
3558:
3559: @menu
3560: * Inserting an Atsign:: inserting an atsign.
3561: * Insert Left Brace:: Inserting a left brace.
3562: * Insert Colon:: Preventing unintended additional whitespace.
3563: * Insert Period:: Inserting a period that does end a sentence.
3564: @end menu
3565:
3566: @node Inserting An Atsign, Insert Left Brace, , Braces Atsigns Periods
3567: @comment node-name, next, previous, up
3568: @subsection @@@@
3569: @findex at-signs
3570: @comment for version 19: this does not work findex @@
3571:
3572: @code{@@@@} stands for a single @@ in either printed or Info output.
3573:
3574: @node Insert Left Brace, Insert Colon, Inserting an Atsign, Braces Atsigns Periods
3575: @comment node-name, next, previous, up
3576: @subsection @@@{
3577: @findex left-braces
3578: @comment for version 19: this does not work findex @{
3579:
3580: @code{@@@{} stands for a single @{ in either printed or Info output.
3581:
3582: @subsection @@@}
3583: @findex right-braces
3584: @comment for version 19: this does not work findex @}
3585:
3586: @code{@@@}} stands for a single @} in either printed or Info output.
3587:
3588: @node Insert Colon, Insert Period, Insert Left Brace, Braces Atsigns Periods
3589: @comment node-name, next, previous, up
3590: @subsection @@:
3591: @findex at-sign colons
3592: @comment for version 19: this does not work findex @:
3593:
3594: @code{@@:}@: is used after a character such as period or colon which
3595: normally causes @TeX{} to increase the width of the following whitespace,
3596: to suppress that effect. For example, it can be used after periods that
3597: end abbreviations and do not end sentences. @code{@@:}@: has no effect
3598: on the Info file output.
3599:
3600: @example
3601: It displays @@code@{Foo:@}@@: at that time.
3602: @end example
3603:
3604: @noindent
3605: produces
3606:
3607: @quotation
3608: It displays @code{Foo:}@: at that time.
3609: @end quotation
3610:
3611: The meanings of @code{@@:}@: and @code{@@.}@: in Texinfo are designed to
3612: work well with the Emacs sentence motion commands. This means they are
3613: different from their meanings in some other formatting systems that use
3614: @@-commands.
3615:
3616: @refill
3617:
3618: @node Insert Period, , Insert Colon, Braces Atsigns Periods
3619: @comment node-name, next, previous, up
3620: @subsection @@.
3621: @findex at-sign periods
3622: @comment for version 19: this does not work at-sign period
3623:
3624: @code{@@.}@: stands for a period that really does end a sentence, useful
3625: when @TeX{} would otherwise assume by its heuristics that that is not so.
3626: This happens when there is a single-capital-letter word at the end of a
3627: sentence: @TeX{} normally guesses that it is an abbreviation.
3628:
3629: In the Info file output, @code{@@.}@: is equivalent to a simple @samp{.}.
3630: The Texinfo program preserves the amount of space that you use, so put
3631: two spaces after a period if you intend it to be the end of a sentence
3632: (as well as using @code{@@.}, if necessary, for the printed manual's sake).
3633:
3634: @example
3635: Give it to X. Give it to X@@. Give it to X@@.
3636: @end example
3637:
3638: @noindent
3639: produces
3640:
3641: @quotation
3642: Give it to X. Give it to X@. Give it to X@.
3643: @end quotation
3644:
3645: @node Dots Bullets Tex, Emphasis, Braces Atsigns Periods, Marking Text
3646: @comment node-name, next, previous, up
3647: @section Inserting Dots, Bullets and @TeX{}
3648: @cindex Dots, inserting
3649: @cindex Bullets, inserting
3650: @cindex TeX-logo, inserting
3651: @cindex Special typesetting commands
3652: @cindex Typesetting commands for dots and the like
3653:
3654: An ellipsis, a line of dots, is typeset differently than a string of
3655: periods; more whitespace is put between the dots in the ellipsis than is
3656: put between the periods. Because of this, a special command is used in
3657: Texinfo for inserting dots. Also, the trademark, @TeX{}, is typeset in a
3658: special fashion and it needs an @@-command, as does the command for
3659: inserting the copyright symbol. The @code{@@bullet} command is special,
3660: too. Each of these commands is followed by a pair of braces, @samp{@{@}},
3661: without any whitespace between the name of the command and the braces.
3662:
3663: @menu
3664: * Dots:: Inserting dots.
3665: * Bullet:: Inserting bullets.
3666: * Tex:: Inserting the @TeX{} trademark.
3667: @end menu
3668:
3669: @node Dots, Bullet, , Dots Bullets Tex
3670: @comment node-name, next, previous, up
3671: @subsection @@dots@{@}
3672: @findex dots
3673: @cindex Inserting dots
3674: @cindex Dots, inserting
3675:
3676:
3677: @code{@@dots@{@}} generates an ellipsis which is three dots in a row,
3678: appropriately spaced, like this: `@dots{}'. Do not simply write three
3679: periods in the input file; that would work for the Info file output, but
3680: would produce the wrong amount of space between the periods in the printed
3681: manual.
3682:
3683: @iftex
3684: Here is an ellipsis: @dots{}
3685:
3686: Here are three periods in a row: ...
3687:
3688: The three periods in a row are closer together than the dots in the ellipsis.
3689:
3690: @end iftex
3691:
3692: @node Bullet, Tex, Dots, Dots Bullets Tex
3693: @comment node-name, next, previous, up
3694: @subsection @@bullet@{@}
3695: @findex bullet
3696:
3697: @code{@@bullet@{@}} generates a large round dot, or the closest possible
3698: thing to one.
3699:
3700: Here is a bullet: @bullet{}
3701:
3702: @node Tex, , Bullet, Dots Bullets Tex
3703: @comment node-name, next, previous, up
3704: @subsection @@TeX@{@}
3705: @findex TeX
3706:
3707: @code{@@TeX@{@}} generates `@TeX{}'. In a printed manual, this is a special
3708: logo that is different from three ordinary letters.
3709:
3710:
3711:
3712: @node Emphasis, , Dots Bullets Tex, Marking Text
3713: @comment node-name, next, previous, up
3714: @section Emphasizing Text
3715: @cindex Emphasizing text
3716:
3717: Usually, Texinfo changes the font automatically to mark words in the text
3718: according to what category the words belong to. The @code{@@code} command,
3719: for example, does this. Most often, this is the best way to mark specified
3720: words. However, sometimes you will want to emphasize text directly.
3721: Texinfo has two ways to do this: commands that tell Texinfo to emphasize
3722: the text but leave the method to the program, and commands that specify the
3723: font to use. The first method is generally the best and it makes it
3724: possible to change the style of a document without have to re-edit it line
3725: by line.
3726:
3727: @menu
3728: * Emph and Strong:: Emphasizing text.
3729: * Fonts:: Selecting italic, bold or typewriter fonts.
3730: @end menu
3731:
3732: @node Emph and Strong, Fonts, , Emphasis
3733: @comment node-name, next, previous, up
3734: @subsection @@emph and @@strong
3735: @findex emph
3736: @findex strong
3737:
3738: @code{@@emph} and @code{@@strong} are two forms of emphasis. @code{@@strong}
3739: is stronger.
3740:
3741: In printed output, @code{@@emph} produces @emph{italics} and @code{@@strong}
3742: produces @strong{bold}.
3743:
3744: In the Info file, both of these commands put asterisks around the
3745: argument.
3746:
3747: @node Fonts, , Emph and Strong, Emphasis
3748: @comment node-name, next, previous, up
3749: @subsection @@i, @@b and @@t
3750: @findex i (italic font)
3751: @findex b (bold font)
3752: @findex t (typewriter font)
3753:
3754: These three commands specify font changes in the printed manual and have no
3755: effect in the Info file. @code{@@i} requests @i{italic} font (in some
3756: versions of @TeX{}, a slanted font is used), @code{@@b} requests @b{bold}
3757: face, and @code{@@t} requests the @t{fixed-width} font used by
3758: @code{@@kbd}. All three commands apply to an argument that follows,
3759: surrounded by braces.@refill
3760:
3761: If possible, you should avoid using these three commands. If you find a
3762: need to use one, it probably indicates a lack in the Texinfo language.
3763:
3764: @node Conditionals, Printing Hardcopy, Marking Text, Top
3765: @comment node-name, next, previous, up
3766: @chapter Conditionals
3767: @cindex Conditionals
3768: @cindex Ifinfo
3769: @cindex Iftex
3770: @findex ifinfo
3771: @findex iftex
3772:
3773:
3774: You may not always be able to use the same text for both the printed manual
3775: and the on-line Info file. In this case, you can use the conditional
3776: commands to specify which text is for the printed manual and which is for
3777: the Info file.
3778:
3779: @code{@@ifinfo} begins text that should be ignored by @TeX{} when it
3780: typesets the printed manual. The text appears only in the Info file. The
3781: @code{@@ifinfo} command should appear on a line by itself. End the
3782: info-only text with a line containing @code{@@end ifinfo} by itself. At
3783: the beginning of a Texinfo file, the Info permissions are contained within a
3784: region marked by @code{@@ifinfo} and @code{@@end ifinfo}.@refill
3785:
3786: Likewise, @code{@@iftex} and @code{@@end iftex} lines delimit text that
3787: will not appear in the Info file but will appear in the printed manual.@refill
3788:
3789: For example,
3790:
3791: @example
3792: @@iftex
3793: This text will appear only in the printed manual.
3794: @@end iftex
3795:
3796:
3797: @@ifinfo
3798: However, this text will appear only in the info manual.
3799: @@end ifinfo
3800: @end example
3801:
3802: @noindent
3803: The preceding example produces the following. Note how you only see one of
3804: the two lines, depending on whether you are reading the on-line Info version
3805: or the printed version of this manual.
3806:
3807:
3808: @iftex
3809: This text will appear only in the printed manual.
3810: @end iftex
3811:
3812: @ifinfo
3813: However, this text will appear only in the info manual.
3814: @end ifinfo
3815:
3816: The @code{@@titlepage} command is a special variant of @code{@@iftex} that
3817: is used for making the title and copyright pages of the printed manual.
3818:
3819: @menu
3820: * Using Tex Commands:: Using commands from regular @TeX{}.
3821: @end menu
3822:
3823: @node Using Tex Commands, , Conditionals, Conditionals
3824: @comment node-name, next, previous, up
3825: @section Using @TeX{} Commands
3826: @cindex Using TeX commands
3827: @cindex TeX commands, using them
3828:
3829: Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
3830: can embed ordinary @TeX{} commands. Info will ignore these commands since
3831: they are only in that part of the file that is seen by @TeX{}. The @TeX{}
3832: commands are the same as any @TeX{} commands except that an @samp{@@}
3833: replaces the @samp{\} used by @TeX{}. For example, in the
3834: @code{@@titlepage} section of a Texinfo file, the @TeX{} command
3835: @code{@@vskip} is used to format the copyright page.@refill
3836:
3837: You can enter @TeX{} completely, and use @samp{\} in the @TeX{} commands by
3838: delineating a region with the @code{@@tex} and @code{@@end tex} commands.
3839: (These commands automatically put the region inside of @code{@@iftex} and
3840: @code{@@end iftex} commands.) For example,@refill
3841:
3842: @example
3843: @@tex
3844: Here you would put text with @TeX{} commands;
3845: such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
3846: that will appear only in the printed manual.
3847: @@end tex
3848: @end example
3849:
3850: @noindent
3851: In the Info file, nothing between @code{@@tex} and @code{@@end tex} will
3852: appear.@refill
3853:
3854: @iftex
3855: In the printed manual, the mathematics will look like this:
3856:
3857: @tex
3858: $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
3859: @end tex
3860: @end iftex
3861:
3862: @node Printing Hardcopy, Creating an Info File, Conditionals, Top
3863: @comment node-name, next, previous, up
3864: @chapter Printing Hardcopy
3865: @cindex Printing hardcopy
3866: @cindex Hardcopy, printing it
3867: @cindex Making a printed manual
3868: @cindex Sorting indices
3869: @cindex Indices, sorting
3870: @findex texindex (for sorting indices)
3871:
3872: There are three shell commands for printing a hardcopy of a Texinfo file.
3873: One is for formatting the file, the second is for sorting the index and the
3874: third is for printing the formatted document. When you use the shell
3875: commands, you can either work directly in the operating system shell or
3876: work within a shell inside of GNU Emacs.
3877:
3878: The typesetting program @TeX{} is used for formatting a Texinfo file.
3879: @TeX{} is a very powerful typesetting program and, if used right, does an
3880: exceptionally good job. The @@-commands in a Texinfo file are translated
3881: by a file called @file{texinfo.tex} into commands that @TeX{} understands.
3882: (That is why the beginning of every Texinfo file starts with the line that
3883: says @samp{\input texinfo}; this command tells @TeX{} to use the
3884: @file{texinfo.tex} file in processing the Texinfo file. Customarily,
3885: @file{texinfo.tex} is in a directory called @file{/usr/lib/tex/macros}.)
3886: @code{texinfo-format-buffer} reads the very same @@-commands in the Texinfo
3887: file and processes them differently from @TeX{} to make an Info
3888: file.@refill
3889:
3890: Usually, the @TeX{} formatting command is the shell command @code{tex}
3891: followed by the name of the Texinfo file. The @TeX{} command produces a
3892: formatted DVI file as well as several auxiliary files containing indices,
3893: cross references, etc. The DVI file (for @dfn{DeVice Independent} file)
3894: can be printed on a wide variety of printers.@refill
3895:
3896: The @TeX{} formatting command itself does not sort the indices. This is a
3897: misfeature of @TeX{}. Hence, to generate a printed index, you first need a
3898: sorted index to work from.@refill
3899:
3900: @TeX{} outputs raw, unsorted index files under names that obey a standard
3901: convention. These names are the name of your main input file to @TeX{},
3902: with everything after the first period thrown away, and the two letter
3903: names of indices added at the end. For example, the raw index output files
3904: for the input file @file{foo.texinfo} would be @file{foo.cp},
3905: @file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and
3906: @file{foo.ky}. Those are exactly the arguments to give to @code{texindex}.
3907: Or else, you can use @samp{??} as ``wild-cards'' and give the command in
3908: this form:@refill
3909:
3910: @example
3911: texindex foo.??
3912: @end example
3913:
3914: For each file specified, @code{texindex} generates a sorted index file
3915: whose name is made by appending @samp{s} to the input file name. The
3916: @code{@@printindex} command knows to look for a file of that name.
3917: @code{texindex} does not alter the raw index output file. After you have
3918: sorted the indices, you need to rerun the @TeX{} command on the Texinfo
3919: file. This regenerates a formatted DVI file with the index entries in the
3920: correct order.@refill
3921:
3922: To summarize, this is a three step process:
3923:
3924: @enumerate
3925: @item
3926: Run the @TeX{} command on the Texinfo file. This generates the formatted
3927: DVI file as well as the raw index files with two letter extensions.@refill
3928:
3929: @item
3930: Run the shell command @code{texindex} on the raw index files to sort them.
3931: The arguments to @code{texindex} are the names of the raw index files.
3932: @code{texindex} creates sorted index files whose names are the names of the
3933: raw index files with an @samp{s} appended. To cause @code{texindex} to
3934: sort all the raw index files, append @samp{??} to the Texinfo file name in
3935: place of the @file{.texinfo} extension.@refill
3936:
3937: @item
3938: Rerun the @TeX{} command on the Texinfo file. This regenerates a formatted
3939: DVI file with the index entries in the correct order. This second run also
3940: makes all the cross references correct as well. (The tables of contents
3941: are always correct.)@refill
3942: @end enumerate
3943:
3944: You need not run @code{texindex} after each @TeX{} run. If you don't, the
3945: next @TeX{} run will use whatever sorted index files happen to exist from
3946: the previous use of @code{texindex}. This is usually ok while you are
3947: debugging.
3948:
3949: Finally, the document can be printed out with the DVI print command
3950: (a shell command). Depending on the system used, the DVI print command
3951: will be a command such as @code{lpr -d}. The DVI print command may require
3952: a file name without any extension or with a @samp{.dvi} extension.
3953:
3954: The following commands, for example, sort the indices, format and print
3955: the @cite{Bison Manual} (where @samp{%} is the shell prompt):
3956:
3957: @example
3958: % tex bison.texinfo
3959: % texindex bison.??
3960: % tex bison.texinfo
3961: % lpr -d bison.dvi
3962: @end example
3963:
3964: @noindent
3965: (Remember that the words for the shell commands may be different at your
3966: site; but these are commonly used versions.)
3967:
3968: It is often most convenient to give formatting and printing commands from a
3969: shell within GNU Emacs. This way, you can easily keep track of errors. To
3970: create a shell within Emacs, type @kbd{M-x shell}. In this shell, you can
3971: format and print the document. You can switch to and from this shell while
3972: it is running and do other things. If you are formatting a very long
3973: document on a slow machine, this can be very convenient; on a VAX 750, for
3974: example, formatting often takes 8 seconds or more per page depending on how
3975: loaded the computer is. Faster machines take correspondingly less time.
3976:
3977: @menu
3978: * Requirements:: Formatting requirements.
3979: * Compile-Command:: Formatting with the compile command.
3980: @end menu
3981:
3982: @node Requirements, Compile-Command, , Printing Hardcopy
3983: @comment node-name, next, previous, up
3984: @section Formatting Requirements
3985: @cindex Requirements for formatting
3986: @cindex Formatting requirements
3987:
3988: Every Texinfo file that is to be input to @TeX{} must begin with a line
3989: that looks like
3990:
3991: @example
3992: \input texinfo @@c -*-texinfo-*-
3993: @end example
3994:
3995: @noindent
3996: This serves two functions.
3997:
3998: @enumerate
3999: @item
4000: When the file is processed by @TeX{}, it loads the macros needed for
4001: processing a Texinfo file.@refill
4002: @item
4003: When the file is edited in Emacs, it causes Texinfo mode to be used.@refill
4004: @end enumerate
4005:
4006: Every Texinfo file must end with a line saying
4007:
4008: @example
4009: @@bye
4010: @end example
4011:
4012: which terminates @TeX{} processing and forces out unfinished pages.
4013:
4014: You also have to include two lines that specify the Info file name and the
4015: title of the printed manual:
4016:
4017: @example
4018: @@setfilename @var{name-of-texinfo-file}
4019: @@settitle @var{Name of Manual}
4020: @end example
4021:
4022: You might also want to include a line saying
4023:
4024: @example
4025: @@setchapternewpage odd
4026: @end example
4027:
4028: @noindent
4029: to cause each chapter to start on a fresh odd-numbered page.
4030:
4031: By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
4032: format. However, you can direct @TeX{} to typeset a document in a 7 by
4033: 9.25 inch format that is suitable for bound books by inserting the
4034: following command on a line by itself at the beginning of the Texinfo
4035: file, before the @code{@@setchapternewpage} command:
4036:
4037: @example
4038: @@smallbook
4039: @end example
4040:
4041: @noindent
4042: The Free Software Foundation distributes printed copies of the @cite{GNU
4043: Emacs Manual} in this size.
4044:
4045: Finally, @TeX{} sometimes is unable to typeset a line without extending
4046: it into the right margin. This can occur when @TeX{} comes upon what it
4047: interprets as a long word that it cannot hyphenate, like a net address,
4048: or a very long title. When this happens, @TeX{} prints an error message
4049: like this:
4050:
4051: @example
4052: Overfull \hbox (20.76302pt too wide)
4053: @end example
4054:
4055: @noindent
4056: and gives the line number along with the text of the offending line
4057: marked at all the places that @TeX{} knows to hyphenate words. (In
4058: @TeX{} lines are in `horizontal boxes', hence the term, `hbox'.)
4059:
4060: If the Texinfo file has an overfull hbox, you can rewrite the sentence
4061: so the overfull hbox does not occur or you can decide to leave it. A
4062: small excursion into the right margin often does not matter and may not
4063: even be noticable. However, unless told otherwise, @TeX{} will print a
4064: large, ugly, black rectangle beside every line that is overfull. This is
4065: so you will notice the location of the problem if you are correcting a
4066: draft. To prevent such monstrosities from marring your final printout,
4067: put the following in the beginning of the Texinfo file on lines of their
4068: own, before the @code{@@setchapternewpage} command:
4069:
4070: @example
4071: @@iftex
4072: @@finalout
4073: @@end iftex
4074: @end example
4075:
4076: @xref{Titlepage}, for information about creating a title page.
4077: @xref{Contents}, for information about creating a table of contents.@refill
4078:
4079: @node Compile-Command, , Requirements, Printing Hardcopy
4080: @comment node-name, next, previous, up
4081: @section Using Local Variables and the Compile Command
4082: @cindex Local variables
4083: @cindex Compile command for formatting
4084: @cindex Formatting with the compile command
4085:
4086: Another way to give the @TeX{} formatting command to Texinfo is to put that
4087: command in a @dfn{local variables list} at the end of the Texinfo file.
4088: You can then specify the @TeX{} formatting command as a
4089: @code{compile-command} and have Emacs run the @TeX{} formatting command by
4090: giving the command @kbd{M-x compile}. This creates a special shell called
4091: the @samp{*compilation buffer*}. For example, at the end of the
4092: @file{gdb.texinfo} file, after the @code{@@bye}, you would put the
4093: following:@refill
4094:
4095: @example
4096: @@c Local Variables:
4097: @@c compile-command: "tex gdb.texinfo"
4098: @@c End:
4099: @end example
4100:
4101: @noindent
4102: This technique is most often used by programmers who compile programs
4103: this way.
4104:
4105: @node Creating an Info File, Catching Mistakes, Printing Hardcopy, Top
4106: @comment node-name, next, previous, up
4107: @chapter Creating an On-line Info file
4108: @cindex Creating an on-line Info file
4109: @cindex Running Info
4110: @cindex Info, creating an on-line file
4111: @cindex Formatting a file for Info
4112: @cindex Indirect subfiles
4113: @findex texinfo-format-buffer
4114:
4115: In GNU Emacs, using Texinfo mode, you can see what part or all of a Texinfo
4116: file will look like in Info by using the keyboard command @kbd{C-c C-f}
4117: (@code{texinfo-format-region}). This formats a region and displays in a
4118: temporary buffer called @samp{*Info Region*}; however, this command does
4119: not turn on Info reading program---it just displays what the region will
4120: look like. The @code{texinfo-format-region} command is described more
4121: extensively in the chapter on using Texinfo mode. @xref{Info on a Region}.
4122: @refill
4123:
4124: In GNU Emacs, the way to create a working Info file is to visit the file
4125: and invoke
4126:
4127: @example
4128: @kbd{M-x texinfo-format-buffer}
4129: @end example
4130:
4131: @noindent
4132: A new buffer is created and the Info file text is generated there.
4133: @kbd{C-x C-s} will save it under the name specified in the
4134: @code{@@setfilename} command.@refill
4135:
4136: If the Texinfo file has more than 30,000 bytes,
4137: @code{texinfo-format-buffer} will automatically create a @dfn{tag table}
4138: for it. With a tag table, Info can jump to new nodes more quickly than it
4139: can otherwise. In addition, if the file has more than 100,000 bytes in it,
4140: @code{texinfo-format-buffer} will split the file into shorter Indirect
4141: subfiles of about 50,000 bytes each. Files are split so that Info does not
4142: have to make a large buffer to hold the whole of a large Info file;
4143: instead, Info allocates just enough memory for the small, split off file
4144: that is needed at the time. This way, Emacs avoids wasting memory when you
4145: run Info. (Before splitting was implemented, Info files were always short
4146: and @dfn{include} files were designed as a way to create a single, large
4147: printed manual out of the smaller Info files. @xref{Include Files}, for
4148: more information.)@refill
4149:
4150: When the file is split, Info itself works through a shortened version of
4151: the original file that contains the tag table and references to the files
4152: that were split off. The split off files are called @dfn{indirect} files.
4153:
4154: The split off files have names that are created by appending @samp{-1},
4155: @samp{-2}, @samp{-3} and so on to the file names specified by the
4156: @code{@@setfilename} command. The shortened version of the original file
4157: continues to have the name specified by @code{@@setfilename}.
4158:
4159: At one stage in writing this document, for example, the Info file was saved
4160: as @file{test-texinfo} and that file looked like this:
4161:
4162: @group
4163: @example
4164: Info file: test-texinfo, -*-Text-*-
4165: produced by texinfo-format-buffer
4166: from file: new-texinfo-manual.texinfo
4167:
4168: ^_
4169: Indirect:
4170: test-texinfo-1: 102
4171: test-texinfo-2: 50422
4172: test-texinfo-3: 101300
4173: ^_^L
4174: Tag table:
4175: (Indirect)
4176: Node: overview^?104
4177: Node: info file^?1271
4178: Node: printed manual^?4853
4179: Node: conventions^?6855
4180: @dots{}
4181: @end example
4182: @end group
4183:
4184: @noindent
4185: (But @file{test-texinfo} had far more nodes than are shown here.) Each of
4186: the split off, indirect files, @file{test-texinfo-1},
4187: @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
4188: after the line that says @samp{Indirect:}. The tag table is listed after
4189: the line that says @samp{Tag table:}. @refill
4190:
4191: You cannot run the @kbd{M-x Info-validate} node checking command on indirect
4192: files. For information on how to prevent files from being split and how to
4193: validate the structure of the nodes, @pxref{Info-Validating a Large
4194: File}@refill
4195:
4196: @menu
4197: * Installing an Info File:: Putting the Info file in the info directory.
4198: @end menu
4199:
4200: @node Installing an Info File, , Creating an Info File, Creating an Info File
4201: @comment node-name, next, previous, up
4202: @section Installing an Info file
4203: @cindex Installing an Info file
4204: @cindex Info file installation
4205: @cindex Dir directory for Info installation
4206:
4207: An Info file is usually installed in the GNU Emacs directory called
4208: @file{info}. For Info to work, this directory must contain all the Info
4209: files, including the split off files. In addition, the @file{info}
4210: directory must have a file that serves as a top level directory for the
4211: Info system. This file is called @file{dir}.
4212:
4213:
4214: For example, in the @file{info} directory, the file called @file{dir} has
4215: the top level menu for all the Info files in the system. This file has a
4216: master menu that looks like this:
4217:
4218: @example
4219: * Menu:
4220:
4221: * Info: (info). Documentation browsing system.
4222: * Emacs: (emacs). The extensible self-documenting text editor.
4223: * Texinfo: (texinfo). With one source file, make either a printed
4224: manual using TeX or an Info file using
4225: Texinfo.
4226: @end example
4227:
4228: To add a new Info file, just add it to this menu. For example, if you
4229: were adding documentation for GDB, you would make the following entry:
4230:
4231: @example
4232: * GDB: (gdb). The source-level C debugger.
4233: @end example
4234:
4235: @noindent
4236: The first item is the menu item name; it is followed by a colon. The
4237: second item is the name of the Info file, in parentheses; it is followed by
4238: a period. The third part of the entry is the description of the item.
4239:
4240:
4241:
4242: The top node of the file, named @samp{top}, should have as its parent the
4243: name of a node in another file, where there is a menu that leads to this
4244: file. Specify the file name in parentheses. If the file is to be
4245: installed directly in the Info directory file, use @samp{(dir)} as the
4246: parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
4247: in the file @file{dir}, which is the main menu of Info.
4248:
4249:
4250:
4251:
4252: @node Catching Mistakes, Command Syntax, Creating an Info File, Top
4253: @comment node-name, next, previous, up
4254: @chapter Catching Mistakes
4255: @cindex Structure of Texinfo, catching mistakes
4256: @cindex Nodes, catching mistakes
4257: @cindex Nodes, correcting mistakes
4258: @cindex Catching mistakes
4259: @cindex Correcting mistakes
4260: @cindex Mistakes, catching
4261: @cindex Problems, catching
4262: @cindex Debugging the Texinfo structure
4263:
4264: Besides mistakes with the content of what ever you are describing, there
4265: are two kinds of mistake you can make with Texinfo: you can make mistakes
4266: with @@-commands, and you can make mistakes with the structure of the
4267: nodes and chapters.
4268:
4269: There are two tools for catching the first kind of mistake and two for
4270: catching the second.
4271:
4272: For finding problems with @@-commands, your best action is to run @kbd{M-x
4273: texinfo-format-region} on regions of your file as you write it. In Texinfo
4274: mode, the @code{texinfo-format-region} command is bound to @kbd{C-c C-f}.
4275: In addition, you can run @TeX{} on the whole file.@refill
4276:
4277: For finding problems with the structure of nodes and chapters, you can use
4278: @kbd{C-c C-s} (@code{texinfo-show-structure}) (and the related @code{occur}
4279: command) and you can use the @kbd{M-x Info-validate} command.
4280:
4281:
4282: @menu
4283: * Debugging with Info:: Catching errors with info formatting.
4284: * Debugging with Tex:: Catching errors with @TeX{} formatting.
4285: * Using texinfo-show-structure:: Using @code{texinfo-show-structure}
4286: to catch mistakes.
4287: * Running Info-Validate:: Checking for unreferenced nodes.
4288: @end menu
4289:
4290:
4291: @node Debugging with Info, Debugging with Tex, , Catching Mistakes
4292: @comment node-name, next, previous, up
4293: @section Catching Errors with Info Formatting
4294: @cindex Catching errors with Info Formatting
4295: @cindex Debugging with Info Formatting
4296:
4297: After you have written part of a Texinfo file, you can use the @kbd{M-x
4298: texinfo-format-region} command to see whether the region formats properly.
4299: In Texinfo mode, this command is bound to the keyboard command @kbd{C-c
4300: C-f}.
4301:
4302: If you have made a mistake with an @@-command, @kbd{M-x
4303: texinfo-format-region} will stop processing at or after the error and give
4304: an error message. To see where in the file the error occurred, switch to
4305: the @samp{*Info Region*} buffer; the cursor will be in a position that is
4306: after the location of the error. Also, the text will not be formatted
4307: after the place the error occurred.@refill
4308:
4309: For example, if you accidently end a menu with the command @code{@@end
4310: menus} with an `s' on the end, instead of with @code{@@end menu}, you will
4311: get an error message that says:
4312:
4313: @example
4314: @@end menus is not handled by texinfo.
4315: @end example
4316:
4317: @noindent
4318: The cursor will stop at the point in the file where the error occurs, or
4319: not long after it. It will look like this:
4320:
4321: @group
4322: @example
4323: @@menu
4324: * Using texinfo-show-structure:: Using @code{texinfo-show-structure}
4325: to catch mistakes.
4326: * Running Info-Validate:: Checking for unreferenced nodes.
4327: @@end menus
4328: @end example
4329: @end group
4330:
4331: The @code{texinfo-format-region} command does not always recognize errors.
4332: For example, no errors were reported when @code{texinfo-format-region} was
4333: run on the whole itemized list of which the following is a part:
4334:
4335: @example
4336: name of the Texinfo file as an extension. The @@samp@{??@} are `wildcards'
4337: that cause the shell to substitute all the raw index files. (@@xref@{sorting
4338: indices), for more information about sorting indices.) @@refill
4339: @@cindex Sorting indices
4340: @@cindex Indices, sorting
4341:
4342: @@item
4343: @@emph@{Third@}, rerun the @@TeX@{@} command on the Texinfo file. This
4344: regenerates a formatted DVI file with the index entries in the correct
4345: order. This second run also makes all the cross references and table of
4346: contents correct as well.
4347: @end example
4348:
4349: @noindent
4350: Instead, @code{texinfo-format-region} ran without reporting the error, but
4351: it produced output that looked like this:
4352:
4353: @example
4354: name of the texinfo file as an extension. The `??' are `wildcards'
4355: that cause the shell to substitute all the raw index files. (*Note for more information about sorting indices.) @@refill @@cindex Sorting indices @@cindex Indices: sorting indices), rerun the TeX command on the texinfo file. This
4356: regenerates a formatted DVI file with the index entries in the correct
4357: order. This second run also makes all the cross references and table of
4358: contents correct as well.
4359: @end example
4360:
4361: @noindent
4362: However, when @code{texinfo-format-region} was run on part of the list that
4363: is shown, it did give an error message, @samp{Search failed: "[@{,@}"}. (This
4364: error message is explained in the section on using the Emacs Lisp Debugger, @pxref{Using the Emacs Lisp Debugger})
4365:
4366: Sometimes @code{texinfo-format-region} will stop long after the original
4367: error; this is because it does not discover the problem until then. In this
4368: case, you will have to backtrack.@refill
4369:
4370: @node Using the Emacs Lisp Debugger, , ,Debugging with Info
4371: @comment node-name, next, previous, up
4372: @subsection Using the Emacs Lisp Debugger
4373: @cindex Using the Emacs Lisp debugger
4374: @cindex Emacs Lisp debugger
4375: @cindex Debugger, using the Emacs Lisp
4376:
4377: If an error is especially elusive, you can turn on the Emacs Lisp debugger
4378: and look at the backtrace; this tells you where in the
4379: @code{texinfo-format-region} function the problem occurred. You can turn
4380: on the debugger with the command:@refill
4381:
4382: @example
4383: M-x set-variable @key{RET} debug-on-error @key{RET} t
4384: @end example
4385:
4386: @noindent
4387: and turn it off with
4388:
4389: @example
4390: M-x set-variable @key{RET} debug-on-error @key{RET} nil
4391: @end example
4392:
4393: Often, when you are using the debugger, it is easier to follow what is
4394: going on if you use the Emacs Lisp files that are not byte-compiled. The
4395: byte-compiled sources send octal numbers to the debugger that may look
4396: mysterious. To use the uncompiled source files, load @file{texinfmt.el}
4397: and @file{texinfo.el} with the @kbd{M-x load-file} command.@refill
4398:
4399: The debugger will not catch an error if @code{texinfo-format-region} does
4400: not detect one. In the example shown above, @code{texinfo-format-region}
4401: did not find the error when the whole list was formatted, but only when
4402: part of the list was formatted. When @code{texinfo-format-region} did not
4403: find an error, the debugger did not find one either. @refill
4404:
4405: However, when @code{texinfo-format-region} did report an error, it invoked
4406: the debugger. This is the backtrace it produced:
4407:
4408: @example
4409: Signalling: (search-failed "[@},]")
4410: re-search-forward("[@},]")
4411: (while ...)
4412: (let ...)
4413: texinfo-format-parse-args()
4414: (let ...)
4415: texinfo-format-xref()
4416: funcall(texinfo-format-xref)
4417: (if ...)
4418: (let ...)
4419: (if ...)
4420: (while ...)
4421: texinfo-format-scan()
4422: (save-excursion ...)
4423: (let ...)
4424: texinfo-format-region(103370 103631)
4425: * call-interactively(texinfo-format-region)
4426: @end example
4427:
4428: The backtrace is read from the bottom up. @code{texinfo-format-region} was
4429: called interactively; and it, in turn, called various functions, including
4430: @code{texinfo-format-scan}, @code{texinfo-format-xref} and
4431: @code{texinfo-format-parse-args}. Inside the function
4432: @code{texinfo-format-parse-args}, the function @code{re-search-forward} was
4433: called; it was this function that could not find the missing right hand
4434: brace.@refill
4435:
4436: @xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs Manual}, for
4437: more information.@refill
4438:
4439:
4440:
4441: @node Debugging with Tex, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
4442: @comment node-name, next, previous, up
4443: @section Catching Errors with @TeX{} Formatting
4444: @cindex Catching errors with TeX Formatting
4445: @cindex Debugging with TeX Formatting
4446:
4447: You can also catch mistakes when you format a file with @TeX{}.
4448:
4449:
4450: Usually, you will want to do this after you have run
4451: @code{texinfo-format-buffer} on the same file.
4452: @code{texinfo-format-buffer} is usually faster and sometimes gives error
4453: messages that make more sense. @xref{Debugging with Info}, for more
4454: information.@refill
4455:
4456: For example, @TeX{} was run on the same itemized list discussed
4457: in the section on the use of @code{texinfo-format-region}
4458: (@pxref{Debugging with Info}); the fragment with the error looked like
4459: this:
4460:
4461: @example
4462: name of the texinfo file as an extension. The @@samp@{??@} are `wildcards'
4463: that cause the shell to substitute all the raw index files. (@@xref@{sorting
4464: indices, for more information about sorting indices.) @@refill
4465: @end example
4466:
4467: @noindent
4468: This produced the following output, after which @TeX{} stopped:
4469:
4470: @example
4471: Runaway argument?
4472: @{sorting indices, for more information about sorting indices.) @@refill @@ETC.
4473: ! Paragraph ended before \xref was complete.
4474: <to be read again>
4475: \par
4476: l.27
4477:
4478: ?
4479: @end example
4480:
4481: In this case, @TeX{} produced an accurate and understandable error message:
4482: @samp{Paragraph ended before \xref was complete.} (Note, however, that
4483: @TeX{} translated the @samp{@@} into a @samp{\}.) Also, @samp{\par} is an
4484: internal @TeX{} command of no relevance to Texinfo.)
4485:
4486: Unfortunately, @TeX{} is not always so helpful, and sometimes you have to be
4487: truly a Sherlock Holmes to discover what went wrong.
4488:
4489: In any case, if you run into a problem like this, you can do one of two
4490: things.
4491:
4492: @enumerate
4493: @item
4494: You can tell @TeX{} to continue running and to ignore errors
4495: as best it can by typing @kbd{r @key{RET}} at the
4496: @samp{?} prompt.@refill
4497:
4498: This is often the best thing to do. However, beware: the one error may
4499: produce a cascade of additional error messages as it consequences are felt
4500: through the rest of the file.@refill
4501:
4502: @item
4503: You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
4504: at the @samp{?} prompt.
4505: @end enumerate
4506:
4507: Sometimes @TeX{} will format a file without producing error messages even
4508: though there is a problem. This usually occurs if a command is not ended
4509: but @TeX{} is able to continue processing anyhow. For example, if you fail
4510: to end an itemized list with the @code{@@end itemize} command, @TeX{} will
4511: write a DVI file that you can print out. The only error message that
4512: @TeX{} will give you is the somewhat mysterious comment that
4513:
4514: @example
4515: (\end occurred inside a group at level 1)
4516: @end example
4517:
4518: @noindent
4519: However, if you print the DVI file, you will find that the text of the file
4520: that follows the itemized list is entirely indented as if it were part of
4521: the last item in the itemized list. The error message is the way @TeX{}
4522: says that it expected to find an @code{@@end} command somewhere in the
4523: file; but that it could not locate where it was needed. @refill
4524:
4525: Another source of notoriously hard to find errors is a missing @code{@@end
4526: group} command. If you ever are stumped by incomprehensible errors, look
4527: for a missing @code{@@end group} command first.@refill
4528:
4529: If you do not have the header lines in the file, @TeX{} may stop in the
4530: beginning of its run and display output that looks like the following.
4531: The @samp{*} indicates that @TeX{} is waiting for input.@refill
4532:
4533: @example
4534: This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm
4535: 87.10.25) (#tz-bar-a02987.tex [1])
4536: *
4537: @end example
4538:
4539: @noindent
4540: In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
4541: put the header lines into the Texinfo file and run the @TeX{} command
4542: again.@refill
4543:
4544:
4545: @node Using texinfo-show-structure, Running Info-Validate, Debugging with Tex, Catching Mistakes
4546: @comment node-name, next, previous, up
4547: @section Using @code{texinfo-show-structure}
4548: @cindex Showing the structure of a file
4549: @cindex Using texinfo-show-structure to catch mistakes
4550: @cindex texinfo-show-structure for catching mistakes
4551: @findex texinfo-show-structure
4552:
4553: It is not always easy to keep track of the nodes, chapters, sections and
4554: subsections of a Texinfo file. This is especially true if you are revising
4555: or adding to a Texinfo file that someone else has written.
4556:
4557: In GNU Emacs, in Texinfo mode, there is a command that will list all the
4558: lines that begin with the @@-commands that specify the structure: @@node,
4559: @@chapter, @@section, @@appendix and so on. This is the
4560: @code{texinfo-show-structure} command. It is bound to the keyboard command
4561: @kbd{C-c C-s}. @code{texinfo-show-structure} displays the lines that begin
4562: with the node and chapter structuring @@-commands in another window called
4563: the @samp{*Occur*} buffer. For example, when @code{texinfo-show-structure}
4564: is run on the first part of this chapter, it produces the following:@refill
4565:
4566: @example
4567: Lines matching
4568: "^@@\\(chapter\\|unnum\\|appendix\\|sect\\|sub\\|heading\\|major
4569: \\|node\\)" in buffer new-texinfo-manual.texinfo.
4570: 2:@@node catching mistakes, @@-Command Syntax, running info, top
4571: 4:@@chapter Catching Mistakes
4572: 41:@@node debugging with info, debugging with tex, , catching mistakes
4573: 43:@@section Catching errors with Info Formatting
4574: @end example
4575:
4576: This means that lines 2, 4, 41 and 43 began with @code{@@node},
4577: @code{@@chapter}, @code{@@node}, and @code{@@section} respectively. If you
4578: move your cursor into the @samp{*Occur*} window, you can position the
4579: cursor over one of the lines and use the @kbd{C-c C-c} command
4580: (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot in
4581: the Texinfo file.
4582: @xref{Other Repeating Search, , Using Occur, emacs, The GNU Emacs Manual},
4583: for more information about @code{occur-mode-goto-occurrence}.@refill
4584:
4585: The first line in the @samp{*Occur*} window describes the @dfn{regular
4586: expression} specified by @var{texinfo-heading-pattern}. This regular
4587: expression is the pattern that @code{texinfo-show-structure} looks for.
4588: @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
4589: for more information.@refill
4590:
4591: When you give the @code{texinfo-show-structure} command, it will show the
4592: structure of the whole buffer. If you want to see the structure of just a
4593: part of the buffer, of one chapter, for example, use the @kbd{C-x n}
4594: (@code{narrow-to-region}) command to mark the region. (@xref{Narrowing, ,
4595: , emacs, The GNU Emacs Manual}.) This is how the example used above was
4596: generated. (To see the whole buffer again, use @kbd{C-x w}
4597: (@code{widen}).)@refill
4598:
4599: You can remind yourself of the structure of a Texinfo file by looking at
4600: the list in the @samp{*Occur*} window; and if you have mis-named a node
4601: or left out a section, you can correct the mistake.
4602:
4603: @menu
4604: * Using Occur::
4605: @end menu
4606:
4607: @node Using Occur, , Using texinfo-show-structure, Using texinfo-show-structure
4608: @comment node-name, next, previous, up
4609: @subsection Using @code{occur}
4610: @cindex Using occur
4611: @cindex Occur, using the command
4612:
4613: Sometimes the @code{texinfo-show-structure} command produces too much
4614: information. Perhaps you want to remind yourself of the overall structure
4615: of a Texinfo file, and are overwhelmed by the detailed list produced by
4616: @code{texinfo-show-structure}. In this case, you can use the @code{occur}
4617: command itself. To do this, type
4618:
4619: @example
4620: @kbd{M-x occur}
4621: @end example
4622:
4623: @noindent
4624: and then, when prompted, type a @dfn{regexp}, a regular expression for the
4625: pattern you want to match.
4626: (@xref{Regexps, , Regular Expressions, emacs, The GNU Emacs Manual}.)
4627: @code{occur} works from the current location of
4628: the cursor in the buffer to the end of the buffer. If you want to run
4629: @code{occur} on the whole buffer, place the cursor at the beginning of the
4630: buffer. For example, to see all the lines that contain the word
4631: @samp{@@chapter} in them, just type @samp{@@chapter}. This will produce a
4632: list of the chapters. It will also list all the sentences with
4633: @samp{@@chapter} in the middle of the line. If you want to see only those
4634: lines that start with the word @samp{@@chapter}, type @samp{^@@chapter}
4635: when prompted by @code{occur}. If you want to see all the lines that end
4636: with a word or phrase, end the last word with a @samp{$}; for example,
4637: @samp{catching mistakes$}. This can be helpful when you want to see all
4638: the nodes that are part of the same chapter or section and therefore have
4639: the same `Up' pointer.@refill
4640:
4641: @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
4642: for more information.@refill
4643:
4644: @node Running Info-Validate, , Using texinfo-show-structure, Catching Mistakes
4645: @comment node-name, next, previous, up
4646: @section Finding Badly Referenced Nodes
4647: @cindex Running Info-validate
4648: @cindex Info-validate, running the command
4649: @cindex Nodes, checking for badly referenced nodes
4650: @cindex Checking for badly referenced nodes
4651: @cindex Looking for badly referenced nodes
4652: @cindex Finding badly referenced nodes
4653: @cindex Badly referenced nodes
4654:
4655: You can check whether any of the `Next', `Previous', `Up' or other node
4656: pointers fail to point to a node with the @code{Info-validate} command.
4657: This command checks that every node pointer points to an existing node.
4658:
4659: To use this command, you first need to load the @code{info} library and then do
4660: @kbd{M-x Info-validate}.
4661:
4662: @example
4663: @kbd{M-x load-library @key{RET} info @key{RET}}
4664: @kbd{M-x Info-validate}
4665: @end example
4666:
4667: @noindent
4668: (Note that all the @code{Info} commands require an uppercase `I'.)
4669:
4670: If your file is ok, you will receive a message that says ``File appears
4671: valid''. However, if you have a pointer that does not point to a node,
4672: error messages will be displayed in a buffer called @samp{*problems in
4673: info file*}.
4674:
4675: For example, @code{Info-validate} was run on a test file that contained
4676: only the first node of this manual. One of the messages said:
4677:
4678: @example
4679: In node "Overview", invalid Next: Texinfo Mode
4680: @end example
4681:
4682: @noindent
4683: This meant that the node called @samp{Overview} had a `Next' pointer that
4684: did not point to anything (which was true in this case, since the test file
4685: had only one node in it).
4686:
4687: Now suppose we add a node named @samp{Texinfo Mode} to our test case
4688: but we don't specify a `Previous' for this node. Then we will get
4689: the following error message:
4690:
4691: @example
4692: In node "Texinfo Mode", should have Previous: Overview
4693: @end example
4694:
4695: @noindent
4696: This is because every `Next' pointer should be matched by a
4697: `Previous' (in the node where the `Next' points) which points back.
4698:
4699: @code{Info-validate} also checks that all menu items and cross-references
4700: point to actual nodes.
4701:
4702: Significantly, @code{Info-validate} does not work with large files that
4703: have been split. (Info thinks of a large file as being over 100,000 bytes,
4704: approximately.) In order to use @code{Info-validate} on a large file, you
4705: must run @code{texinfo-format-buffer} with an argument so that it does not
4706: split the Info file, and then create a tag table.
4707:
4708: @menu
4709: * Info-Validating a Large File:: Running @code{Info-validate} on a large file.
4710: * Splitting:: Splitting a file manually.
4711: @end menu
4712:
4713: @node Info-Validating a Large File, Splitting, Running Info-Validate, Running Info-Validate
4714: @comment node-name, next, previous, up
4715: @subsection Running @code{Info-validate} on a Large File.
4716: @cindex Running Info-validate on a large file
4717: @cindex Info validating a large file
4718: @cindex Validating a large file
4719:
4720:
4721: You can run @code{Info-validate} only on a single Info file. The command
4722: will not work on indirect subfiles that are generated when the master file
4723: is split. If you have a large file (longer than 100,000 bytes), you need
4724: to run the @code{texinfo-format-buffer} command in such a way that it does
4725: not create indirect subfiles. You will also need to create a tag table.
4726: When you have done this, you can run @code{Info-validate} and look for
4727: badly referenced nodes.@refill
4728:
4729: After you have validated the node structure, you can rerun
4730: @code{texinfo-format-buffer} in the normal way so it will construct the tag
4731: table and split the file automatically or, you can make the tag table and
4732: split the file manually.@refill
4733:
4734: To prevent the @code{texinfo-format-buffer} command from splitting a
4735: Texinfo file into smaller Info files, give a prefix to the @kbd{M-x
4736: texinfo-format-buffer} command:
4737:
4738: @example
4739: C-u M-x texinfo-format-buffer
4740: @end example
4741:
4742: @noindent
4743: When you do this, Texinfo will not split the file and will not create a tag
4744: table for it. @refill
4745: @cindex Making a tag table manually
4746: @cindex Tag table, making manually
4747:
4748: Before you can run @kbd{M-x Info-validate} on the Info file, you need to
4749: create a tag table for it. In order to do this, you first need to load the
4750: @code{info} library into Emacs with the following command:@refill
4751:
4752: @example
4753: M-x load-library @key{RET} info @key{RET}
4754: @end example
4755:
4756: @noindent
4757: Then you can give the command:
4758:
4759: @example
4760: M-x Info-tagify
4761: @end example
4762:
4763: This creates a file which you can validate.@refill
4764:
4765: @example
4766: M-x Info-validate
4767: @end example
4768:
4769: After you have checked the validity of the nodes, you can either run
4770: @kbd{M-x texinfo-format-buffer} as you would normally, or else tagify and
4771: split the file manually with the two commands @code{Info-tagify} and
4772: @code{Info-split}.@refill
4773:
4774: @node Splitting, ,Info-Validating a Large File , Running Info-Validate
4775: @comment node-name, next, previous, up
4776: @subsection Splitting a File Manually
4777: @cindex Splitting an Info file manually
4778: @cindex Info file, splitting manually
4779:
4780: If the file has more than 100,000 or so bytes in it, you should split it or
4781: else let the @code{texinfo-format-buffer} command do it for you
4782: automatically. (Generally you will let @code{texinfo-format-buffer} do
4783: this job for you. @xref{Creating an Info File}.)@refill
4784:
4785: The split off files are called the indirect subfiles.
4786:
4787: Info files are split to save memory. With smaller files, Emacs does not
4788: have make such a large buffer to hold the information. This way, Emacs
4789: can save memory.
4790:
4791: If the Info file has more than 30 nodes, you should also make a tag table for
4792: it. @xref{Info-Validating a Large File}, for information about creating a
4793: tag table.
4794:
4795: Before running @code{Info-split}, you need to load the @code{info} library
4796: into Emacs by giving the command @kbd{M-x load-library @key{RET} info
4797: @key{RET}}. After you have done this, you can give the two commands:@refill
4798:
4799: @example
4800: M-x Info-tagify
4801: M-x Info-split
4802: @end example
4803:
4804: @noindent
4805: (Note that the @samp{I} in @samp{Info} is uppercase.)
4806:
4807: When you use the @code{Info-split} command, the buffer is modified into a
4808: (small) Info file which lists the indirect subfiles. This file should be
4809: saved in place of the original visited file. The indirect subfiles are
4810: written in the same directory the original file is in, with names generated
4811: by appending @samp{-} and a number to the original file name.
4812:
4813: The primary file still functions as an Info file, but it contains just
4814: the tag table and a directory of subfiles.
4815:
4816: @c ;;;;;;;;;;;;;;;; Appendix starts here ;;;;;;;;;;;;;;;;
4817:
4818: @node Command Syntax, Include Files , Catching Mistakes , Top
4819: @comment node-name, next, previous, up
4820: @appendix @@-Command Syntax
4821: @cindex @@-Command Syntax
4822:
4823: The character @samp{@@} is used to start special Texinfo commands. (It has the
4824: same meaning that @samp{\} has in plain @TeX{}.) Syntactically, there
4825: are three classes of @@-commands:
4826:
4827: @table @asis
4828: @item 1. Non-alphabetic commands: @@ followed by a punctuation character.
4829: These commands are always part of the text within a paragraph, and
4830: never take any argument. The two characters (@@ and the other one)
4831: are complete in themselves. For example, @code{@@.}, @code{@@:},
4832: @code{@@@{} and @code{@@@}}.@refill
4833:
4834: @item 2. Alphabetic commands used within a paragraph.
4835: These commands have @@ followed by a letter or a word, followed by an
4836: argument within braces. For example, the command @code{@@dfn} indicates
4837: the introductory or defining use of a term; it is used as follows: @samp{In
4838: Texinfo, @@-commands are @@dfn@{mark-up@} commands.}@refill
4839:
4840: @item 3. Alphabetic commands used outside of paragraphs.
4841: Each such command occupies an entire line. The line starts with @@,
4842: followed by the name of the command (a word) such as @code{@@center} or
4843: @code{@@cindex}. If no argument is needed, the word is followed by the end
4844: of the line. If there is an argument, it is separated from the command
4845: name by a space.@refill
4846: @end table
4847:
4848: Thus, the alphabetic commands fall into two classes that have different
4849: argument syntax. You cannot tell which class a command falls in by the
4850: appearance of its name, but you can tell by the command's meaning: if it
4851: makes sense to use the command together with other words as part of a
4852: paragraph, the command is in class 2 and must be followed by an argument in
4853: braces; otherwise, it is in class 3 and uses the rest of the line as its
4854: argument.
4855:
4856: The purpose of having different syntax for commands of classes 2 and 3 is
4857: to make the Texinfo file easier to read, and also to help the GNU Emacs
4858: paragraph and filling commands work properly. There is only one exception
4859: to this rule: the command @code{@@refill}, which is always used at the end
4860: of a paragraph immediately following the final period or other punctuation
4861: character. @code{@@refill} takes no argument. @code{@@refill} never
4862: confuses the Emacs paragraph commands because it cannot start at the
4863: beginning of a line.@refill
4864:
4865:
4866: @node Include Files, TeX Input, Command Syntax, Top
4867: @comment node-name, next, previous, up
4868: @appendix Include Files
4869: @cindex Include files
4870:
4871: When Info was first created, it was customary to create many small Info
4872: files on one subject. By doing this, Emacs did not have to make a large
4873: buffer to hold the whole of a large Info file; instead, Emacs allocated
4874: just enough memory for the small Info file that was needed at the time.
4875: This way, Emacs could avoid wasting memory. Include files were designed as
4876: a way to create a single, large printed manual out of several smaller Info
4877: files.
4878:
4879: However, because large Info files can now be split, include files are no
4880: longer strictly necessary and they are used infrequently. Most often, they
4881: are now used in projects where several different people are writing
4882: different sections of a document simultaneously.
4883:
4884: @appendixsec How Include Files Work
4885:
4886: In a Texinfo file, a line of the form @code{@@include @file{filename}} is
4887: ignored when the Info file is generated, but in a printed manual it causes
4888: the contents of the file @file{filename} to be processed and included in the
4889: manual. The contents of the file @file{filename} can be ignored by Info
4890: because the first file can refer to @file{filename} with menus as well as
4891: cross references. In the Info system, all the information is, as it were,
4892: `in one place'. However, when two printed manuals are made from two
4893: separate Texinfo files, the two manuals are separate, and even if they give
4894: each other as references, the references are to separate documents.
4895: Consequently, you will sometimes want to create a comprehensive, printed
4896: manual that contains all the necessary information together in one place.
4897:
4898: @code{@@include} files are special Texinfo files that are used only for
4899: making such a comprehensive manual. They are listed inside an outer file
4900: that contains nothing but the beginning and end matter of a Texinfo file
4901: and a number of @code{@@include} commands listing the included files.
4902:
4903: An @code{@@include} file--a file that will be listed inside an outer file
4904: and processed with the @code{@@include} command--should not start with
4905: @samp{\input texinfo}, as that has already been done by the outer file, and
4906: the character @samp{\} has already been redefined to generate a backslash
4907: in the output. Instead, an @code{@@include} file usually begins with a
4908: node; it lacks the beginning and ending of a Texinfo file that are
4909: described in the chapters on beginning and ending a file. @xref{Beginning
4910: a File}, and @pxref{Ending a File} @refill
4911:
4912: Likewise, an @code{@@include} file should not end with @code{@@bye}, since
4913: that would terminate @TeX{} processing immediately.
4914:
4915: Here is an example of a outer Texinfo file with @code{@@include} files
4916: within it:@refill
4917:
4918: @example
4919: \input texinfo @@c -*-texinfo-*-
4920: @@setfilename include
4921: @@settitle Include Manual
4922:
4923: @@setchapternewpage odd
4924: @@titlepage
4925: @@sp 12
4926: @@center @@titlefont@{Include Manual@}
4927: @@sp 2
4928: @@center by Whom Ever
4929:
4930: @@page
4931: Copyright @@copyright@{@} 1988 Free Software Foundation, Inc.
4932: @@end titlepage
4933:
4934: @@include foo.texinfo
4935: @@include bar.texinfo
4936:
4937: @@unnumbered Concept Index
4938: @@printindex cp
4939:
4940: @@summarycontents
4941: @@contents
4942:
4943: @@bye
4944: @end example
4945:
4946: @node TeX Input, Sample Permissions, Include Files, Top
4947: @comment node-name, next, previous, up
4948: @appendix @TeX{} Input Initialization
4949: @cindex TeX Input Initialization
4950: @cindex TEXINPUTS environment variable
4951: @cindex profile initialization file
4952: @cindex cshrc initialization file
4953:
4954: You must put an input command on the first line of every Texinfo file to
4955: tell @TeX{} to use the @file{texinfo.tex} file when it is processing the
4956: Texinfo source file. Otherwise @TeX{} will not know what to do with the
4957: @@-commands. (The @TeX{} input command is written as @samp{\input
4958: texinfo}. @xref{First Line}.)@refill
4959:
4960: @TeX{} needs to be told where to find the @file{texinfo.tex} file that you
4961: have told it to input. The preferred way to do this is to put
4962: @file{texinfo.tex} in the default inputs directory, which is the
4963: @file{/usr/lib/tex/macros} directory. If this is done (as it usually is
4964: when GNU Emacs is installed), @TeX{} will find the file and you don't have
4965: to do anything. Alternatively, you can put @file{texinfo.tex} in the
4966: directory in which the Texinfo source file is located.@refill
4967:
4968: However, you may want to specify the location of the @code{\input} file
4969: yourself. One way to do this is to write the complete path for the file
4970: after the @code{\input} command. Another way is to set the
4971: @samp{TEXINPUTS} environment variable in your @file{.cshrc} or
4972: @file{.profile} file. The @samp{TEXINPUTS} environment variable will tell
4973: @TeX{} where to find the @file{texinfo.tex} file and any other file that
4974: you might want @TeX{} to use.@refill
4975:
4976: Whether you use a @file{.cshrc} or @file{.profile} file depends on whether
4977: you use @samp{csh} or @samp{sh} for your shell command interpreter. When
4978: you use @samp{csh}, it looks to the @file{.cshrc} file for initialization
4979: information, and when you use @samp{sh}, it looks to the @file{.profile}
4980: file.@refill
4981:
4982: In a @file{.cshrc} file, you could use the following @code{csh} command
4983: sequence:@refill
4984:
4985: @example
4986: setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros
4987: @end example
4988:
4989: @noindent
4990: In a @file{.profile} file, you could use the following @code{sh} command
4991: sequence:
4992:
4993: @example
4994: TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
4995: export TEXINPUTS
4996: @end example
4997:
4998: @noindent
4999: This would cause @TeX{} to look for @file{\input} file first in the current
5000: directory, indicated by the @samp{.}, then in a hypothetical user's
5001: @file{me/mylib} directory, and finally in the system library.@refill
5002:
5003: @node Sample Permissions, Command Index, TeX Input, Top
5004: @comment node-name, next, previous, up
5005: @appendix Standard text for Copying Permissions
5006: @cindex Permissions
5007: @cindex Copying permissions
5008:
5009: Texinfo files should contain sections that tell the readers that they have
5010: the right to copy and distribute the Info file, the printed manual and any
5011: accompanying software. This appendix contains the standard text of the
5012: Free Software Foundation copying permission notice. For an example of the
5013: text that could be used for the Distribution, General Public License and NO
5014: WARRANTY sections of a document, see the latest version of the @cite{GNU
5015: Emacs Manual}.
5016:
5017: The texts of the Free Software Foundation copying permission notice in the
5018: @code{@@ifinfo} section and in the @code{@@titlepage} section are slightly
5019: different.
5020:
5021: The @code{@@ifinfo} section usually begins with a line that says what the
5022: file documents. This is what a person looking at the file will first read
5023: if he or she reads the unprocessed Texinfo file or if he or she uses the
5024: advanced Info command @kbd{g *}. @inforef{Expert, info, info}, for more
5025: information. (If the reader uses the regular Info commands, he or she will
5026: usually start reading at the first node and skip this first section, which
5027: is not in a node.)
5028:
5029: In the @code{@@ifinfo} section, the summary sentence should be followed by
5030: a copyright notice and then by the copying permission notice. One of the
5031: copying permission paragraphs is enclosed in @code{@@ignore} and
5032: @code{@@end ignore} commands. This paragraph states that the Texinfo file
5033: can be processed through @TeX{} and printed, provided the printed manual
5034: carries the proper copying permission notice. This paragraph is not made
5035: part of the Info file since it is not relevant to the Info file; but it is
5036: a mandatory part of the Texinfo file since it permits people to process the
5037: Texinfo file in @TeX{}.@refill
5038:
5039: In the printed manual, the Free Software Foundation copying permission
5040: notice follows the copyright notice and publishing information and is
5041: located within the region delineated by the @code{@@titlepage} and
5042: @code{@@end titlepage} commands. The copying permission notice is exactly
5043: the same as the notice in the @code{@@ifinfo} section except that the
5044: paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
5045: not part of the notice.@refill
5046:
5047: To make it simpler to copy the permission notice into each section of the
5048: Texinfo file, the complete permission notices for each section are
5049: reproduced in full below even though most of the information is
5050: redundant.@refill
5051:
5052: Note that you my have to specify the correct name of a section mentioned in
5053: the permission notice. For example, in the @cite{GDB Manual}, the name of
5054: the section referring to the General Public License is called the ``GDB
5055: General Public License'', but in the sample shown below, that section is
5056: referred to generically as the ``General Public License''.
5057:
5058: @menu
5059: * Ifinfo Permissions::
5060: * Titlepage Permissions::
5061: @end menu
5062:
5063:
5064: @node Ifinfo Permissions, Titlepage Permissions, Sample Permissions, Sample Permissions
5065: @comment node-name, next, previous, up
5066: @appendixsec Ifinfo Copying Permissions
5067: @cindex Ifinfo permissions
5068:
5069: In the @code{@@ifinfo} section of the Texinfo file, the standard Free
5070: Software Foundation permission notices reads as follows:
5071:
5072: @example
5073: This file documents @dots{}
5074:
5075: Copyright 1988 Free Software Foundation, Inc.
5076:
5077: Permission is granted to make and distribute verbatim copies of
5078: this manual provided the copyright notice and this permission notice
5079: are preserved on all copies.
5080:
5081: @@ignore
5082: Permission is granted to process this file through TeX and print the
5083: results, provided the printed document carries a copying permission
5084: notice identical to this one except for the removal of this paragraph
5085: (this paragraph not being relevant to the printed manual).
5086:
5087: @@end ignore
5088: Permission is granted to copy and distribute modified versions of this
5089: manual under the conditions for verbatim copying, provided also that the
5090: sections entitled ``Distribution'' and ``General Public License'' are
5091: included exactly as in the original, and provided that the entire
5092: resulting derived work is distributed under the terms of a permission
5093: notice identical to this one.
5094:
5095: Permission is granted to copy and distribute translations of this manual
5096: into another language, under the above conditions for modified versions,
5097: except that the sections entitled ``Distribution'' and ``General Public
5098: License'' may be included in a translation approved by the author instead
5099: of in the original English.
5100: @end example
5101:
5102: @node Titlepage Permissions, , Ifinfo Permissions, Sample Permissions
5103: @comment node-name, next, previous, up
5104: @appendixsec Titlepage Copying Permissions
5105: @cindex Titlepage permissions
5106:
5107: In the @code{@@titlepage} section of the Texinfo file, the standard Free
5108: Software Foundation copying permission notices follows the copyright notice
5109: and publishing information. The standard phrasing is:
5110:
5111: @example
5112: Permission is granted to make and distribute verbatim copies of
5113: this manual provided the copyright notice and this permission notice
5114: are preserved on all copies.
5115:
5116: Permission is granted to copy and distribute modified versions of this
5117: manual under the conditions for verbatim copying, provided also that the
5118: sections entitled ``Distribution'' and ``General Public License'' are
5119: included exactly as in the original, and provided that the entire
5120: resulting derived work is distributed under the terms of a permission
5121: notice identical to this one.
5122:
5123: Permission is granted to copy and distribute translations of this manual
5124: into another language, under the above conditions for modified versions,
5125: except that the sections entitled ``Distribution'' and ``General Public
5126: License'' may be included in a translation approved by the author instead
5127: of in the original English.
5128: @end example
5129:
5130: @node Command Index, Concept Index, Sample Permissions, Top
5131: @comment node-name, next, previous, up
5132: @unnumbered Command Index
5133:
5134: (When used in a Texinfo file, @@-commands are preceded by an
5135: @samp{@@}.)@refill
5136:
5137: @printindex fn
5138:
5139: @node Concept Index, , Command Index, Top
5140: @comment node-name, next, previous, up
5141: @unnumbered Concept Index
5142:
5143: @printindex cp
5144:
5145: @summarycontents
5146: @contents
5147: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.