![[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] / 43BSD / contrib / emacs / man|
Return to texinfo.texinfo CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / emacs / man |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2: @setfilename ../info/texinfo
3: @settitle Texinfo
4:
5: @titlepage
6: @center @titlefont{Texinfo}
7: @sp 1
8: @center The GNU Documentation Format
9: @sp 2
10: @center Richard M. Stallman
11: @end titlepage
12:
13: @unnumbered Distribution
14:
15: Copyright @copyright{} 1985 Richard M. Stallman.
16:
17: Permission is granted to make and distribute verbatim copies of
18: this manual provided the copyright notice and this permission notice
19: are preserved on all copies.
20:
21: @ignore
22: Permission is granted to process this file through Tex and print the
23: results, provided the printed document carries copying permission
24: notice identical to this one except for the removal of this paragraph
25: (this paragraph not being relevant to the printed manual).
26:
27: @end ignore
28: Permission is granted to copy and distribute modified versions of this
29: manual under the conditions for verbatim copying, provided that the entire
30: resulting derived work is distributed under the terms of a permission
31: notice identical to this one.
32:
33: Permission is granted to copy and distribute translations of this manual
34: into another language, under the same conditions as for modified versions.
35:
36: @node top, commands, , (DIR)
37: @chapter Texinfo Files
38:
39: Documentation for GNU utilities and libraries should be written
40: in a format called @dfn{texinfo}. This format can be translated
41: mechanically into either printed manuals or on-line readable
42: Info files.@refill
43:
44: @menu
45: * info:: What Info files do.
46: * commands:: What goes into a texinfo file.
47: * make-info:: Making a texinfo file into an Info file.
48: * manual:: Making a texinfo file into a printed manual.
49: @end menu
50:
51: @node info, commands, top, top
52: @section What Info Files Do
53:
54: An Info file is a file formatted so that the Info documentation reading
55: program can operate on it. Info files are divided into pieces called
56: @dfn{nodes}, each of which contains the discussion of one topic. Each node
57: has a name, and contains both text for the user to read and pointers to
58: other nodes, which are identified by their names. Info displays one node
59: at a time, and provides commands with which the user can move to the other
60: nodes that the current node points to.
61:
62: Normally most of the nodes are arranged in a tree which branches down.
63: Each node may have any number of child nodes that describe subtopics of the
64: node's topic. The names of these child nodes, if any, are listed in a
65: @dfn{menu} within the parent node; this allows certain Info commands to
66: be used to move to one of the child nodes. Each child node records the
67: parent node name, as its `up' pointer.
68:
69: All the children of any one parent are linked together in a bidirectional
70: chain of `next' and `previous' pointers. Normally the order in this chain
71: is the same as the order of the children in the parent's menu. The last
72: child has no `next' pointer, and the first child normally has the parent as
73: its `previous' pointer (as well as its `up' pointer, of course).
74:
75: The root of the tree is the top node of the file, through which users
76: enter the file from the Info directory. By convention, this node is always
77: called @samp{top}. This node normally contains just a brief summary of the
78: file's purpose, and a large menu through which the rest of the file is
79: reached.
80:
81: Structuring the nodes in a tree is a matter of convention, not a
82: requirement. In fact, the `up', `previous' and `next' pointers of a node
83: can point to any other nodes, and the menu can contain any other nodes.
84: The structure of nodes can be any directed graph. But it is usually more
85: comprehensible to the user to make it a tree. Info provides another kind
86: of pointer between nodes, called a reference, that can be sprinkled through
87: the text of a node. This is usually the best way to represent links that
88: do not fit the tree structure.
89:
90: Most often the nodes fall into a strict tree structure, and most often this
91: structure corresponds to the structure of chapters, sections, subsections,
92: and so on of a printed manual. But there are times when this is not right
93: for the material being discussed. Therefore, texinfo format uses separate
94: commands to specify the node structure of the Info file and the section
95: structure of the a printed manual. Also, texinfo requires menus to be
96: specified explicitly, rather than generating them automatically based on an
97: assumed tree structure.
98:
99: @node commands, make-info, info, top
100: @section General Syntactic Conventions
101:
102: Texinfo files contain a strictly limited set of constructs for a @TeX{}
103: macro package quite different from plain @TeX{}. The strict limits make it
104: possible for texinfo files to be understood also by the @code{texinfo}
105: program, which converts them into Info files.
106:
107: In order to be made into an Info file, a texinfo file must start with a
108: line that looks like
109: @example
110: @@setfilename @var{info-file-name}
111: @end example
112: @noindent
113: which specifies the name of the Info file to be generated. In fact, there
114: can be other things in the file before this line, but they are ignored in
115: the generation of an Info file. The @code{@@setfilename} line is ignored
116: when a printed manual is generated.
117:
118: All ASCII printing characters except @code{@@}, @code{@{} and @code{@}} can
119: appear in body text in a texinfo file and stand for themselves. @code{@@}
120: is the escape character which introduces commands. @code{@{} and @code{@}}
121: should be used only to surround arguments to certain commands. @code{@{}
122: and @code{@}} appearing anywhere else will be treated by @TeX{} as a
123: grouping but treated by texinfo as themselves; this inconsistency is
124: undesirable, so don't let it occur. To put one of these special characters
125: into the document, put an @samp{@@} character in front of it.@refill
126:
127: It is customary in @TeX{} to use doubled single-quote characters to begin
128: and end quotations. This convention should be followed in texinfo files.
129:
130: @TeX{} ignores the line-breaks in the input text, except for blank lines,
131: which separate paragraphs. Texinfo generally preserves the line breaks
132: that are present in the input file. Therefore, you break the lines in the
133: texinfo file the way you want them to appear in the output Info file, and
134: let @TeX{} take care of itself.
135:
136: @section @@-Command Syntax
137:
138: The character @@ is used to start special texinfo commands. (It has the
139: same meaning that @t{\} has in plain @TeX{}.) Syntactically, there
140: are three classes of @@-commands:
141:
142: @enumerate
143: @item
144: Non-alphabetic commands, @@ followed by a punctuation character.
145: These commands are always part of the text within a paragraph, and
146: never take any argument. The two characters (@@ and the other one)
147: are complete in themselves.
148: @item
149: Alphabetic commands used within a paragraph. These commands have @@
150: followed by a word, followed by an argument within braces. For
151: example, the command @code{@@i} specifies italic font (for @TeX{}
152: processing only); it is used as follows: @samp{I do @@i@{not@} want
153: to eat that.}
154: @item
155: Alphabetic commands used outside of paragraphs. Each such command
156: occupies an entire line. The line starts with @@, followed by the
157: name of the command (a word). If no argument is needed, the word is
158: followed by the end of the line. If there is an argument, it is
159: separated from the command name by a space.
160: @end enumerate
161:
162: Thus, the alphabetic commands fall into two classes that have different
163: argument syntax. You cannot tell which class a command falls in by the
164: appearance of its name, but you can tell by the command's meaning: if it
165: makes sense to use the command together with other words as part of a
166: paragraph, the command is in class 2 and must be followed by an argument in
167: braces; otherwise, it is in class 3 and uses the rest of the line as its
168: argument.
169:
170: The purpose of having different syntax for commands of classes 2 and 3 is
171: to make the texinfo file easier to read, and also to help the Emacs
172: paragraph and filling commands work properly. There is only one exception
173: to this rule: the command @code{@@refill}, which is always used at the end
174: of a paragraph immediately following the final period or other punctuation
175: character. @code{@@refill} takes no argument. @code{@@refill} never
176: confuses the Emacs paragraph commands because it cannot start at the
177: beginning of a line.@refill
178:
179: @section Within-Paragraph Commands
180:
181: The @@-commands used within a paragraph either generate a small amount of
182: text or modify the treatment of some text.
183:
184: @subsection @@@@
185:
186: @code{@@@@} stands for a single @@ in either printed or Info output.
187:
188: @subsection @@@{
189:
190: @code{@@@{} stands for a single @{ in either printed or Info output.
191:
192: @subsection @@@}
193:
194: @code{@@@}} stands for a single @} in either printed or Info output.
195:
196: @subsection @@:
197:
198: @code{@@:}@: is used after a character such as period or colon which
199: normally causes @TeX{} to increase the width of the following whitespace,
200: to suppress that effect. For example, it can be used after periods that
201: end abbreviations and do not end sentences. @code{@@:}@: has no effect
202: on the Info file output.
203:
204: @example
205: It displays @@code@{Foo:@}@@: at that time.
206: @end example
207:
208: @noindent
209: produces
210:
211: @quotation
212: It displays @code{Foo:}@: at that time.
213: @end quotation
214:
215: Note that the meanings of @code{@@:}@: and @code{@@.}@: in texinfo are
216: not compatible with their meanings in Scribe; in fact, they are nearly the
217: opposite. The meanings in texinfo were designed to work well with the
218: Emacs sentence motion commands.@refill
219:
220: @subsection @@.
221:
222: @code{@@.}@: stands for a period that really does end a sentence, useful when
223: @TeX{} will assume by its heuristics that that is not so. This happens
224: when there is a single-capital-letter word at the end of a sentence: @TeX{}
225: normally guesses that it is an abbreviation.
226:
227: In the Info file output, @code{@@.}@: is equivalent to a simple @samp{.}.
228: The texinfo program preserves the amount of space that you use, so put
229: two spaces after a period if you intend it to be the end of a sentence
230: (as well as using @code{@@.}, if necessary, for the printed manual's sake).
231:
232: @example
233: Give it to X. Give it to X@@. Give it to X@@.
234: @end example
235:
236: @noindent
237: produces
238:
239: @quotation
240: Give it to X. Give it to X@. Give it to X@.
241: @end quotation
242:
243: @subsection @@*
244:
245: @code{@@*} forces a line break in the printed manual. It has no effect on
246: the Info file output, where line breaks follow those in the source file.
247: If you want a line break at a certain spot in both forms of output, break
248: the line there in the source file and put @code{@@*} at the end of the
249: line.
250:
251: @subsection @@dots
252:
253: @code{@@dots@{@}} generates an ellipsis: three periods in a row, or `@dots{}'.
254: Do not simply write three periods in the input file; that would work ok for
255: the Info file output, but would produce the wrong amount of space between
256: the periods in the printed manual.
257:
258: @subsection @@bullet
259:
260: @code{@@bullet@{@}} generates a large round dot, or the closest possible
261: thing to one.
262:
263: @subsection @@TeX
264:
265: @code{@@TeX@{@}} generates `@TeX{}'. In a printed manual, this is a special
266: logo that is different from three ordinary letters.
267:
268: @subsection @@copyright
269:
270: @code{@@copyright@{@}} generates a @samp{C} inside a circle.
271:
272: @subsection @@code
273:
274: @code{@@code} is used to indicate text that is a literal example of input
275: to a program. The text follows, enclosed in braces. Any time you give a
276: sample of an expression in C, or of a command for the shell, or any such
277: thing, use @code{@@code}. In the printed manual, it puts the argument in
278: bold face. In the Info file, it uses `@dots{}' quotation. Example:
279:
280: @example
281: To compare two files, showing text inserted or removed, use @@code@{diff@}.
282: @end example
283:
284: @noindent
285: produces
286:
287: @quotation
288: To compare two files, showing text inserted or removed, use @code{diff}.
289: @end quotation
290:
291: @subsection @@samp
292:
293: @code{@@samp} is used to indicate text that is a literal example of a
294: sequence of characters in a file, string, pattern, etc. The text follows,
295: enclosed in braces. The argument appears within `@dots{}' quotation in
296: both the Info file and the printed manual; in addition, it is printed in
297: a fixed-width font.
298:
299: @example
300: To match @@samp@{foo@} at the end of the line, use the regexp @@samp@{foo$@}.
301: @end example
302:
303: @noindent
304: produces
305:
306: @quotation
307: To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
308: @end quotation
309:
310: @subsection @@file
311:
312: @code{@@file} is used to indicate text that is a file name. Currently
313: it is equivalent to @code{@@samp} in its effects on the output.
314:
315: @subsection @@kbd
316:
317: @code{@@kbd} is used much like @code{@@code}. The difference is that
318: @code{@@kbd} is for names of keys on the keyboard, or of characters you can
319: type. It has the same effect as @code{@@code} in texinfo, but may produce
320: a different font in a printed manual.@refill
321:
322: @example
323: To give the @@code@{logout@} command, type the characters @@kbd@{l o g o u t
324: @@key@{RET@}@}.
325: @end example
326:
327: @noindent
328: produces
329:
330: @quotation
331: To give the @code{logout} command, type the characters @kbd{l o g o u t
332: @key{RET}}.
333: @end quotation
334:
335: @subsection @@key
336:
337: @code{@@key} is used to indicate text that is the name of a key on
338: the keyboard, as in
339:
340: @example
341: @@key@{RET@}
342: @end example
343:
344: Often, @code{@@key} is used within the argument of a @code{@@kbd}
345: command, whenever the sequence of characters to be typed includes one or
346: more keys that are described by name.@refill
347:
348: The recommended names to use for keys are
349:
350: @table @t
351: @item SPC
352: Space.
353: @item RET
354: Return.
355: @item LFD
356: Linefeed.
357: @item TAB
358: Tab.
359: @item BS
360: Backspace.
361: @item ESC
362: Escape.
363: @item DEL
364: Delete.
365: @item SFT
366: Shift.
367: @item CTL
368: Control.
369: @item META
370: Meta.
371: @end table
372:
373: @subsection @@ctrl
374:
375: @code{@@ctrl} is used to describe an ASCII control character. The pattern
376: of usage is @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character whose
377: control-equivalent is wanted.
378:
379: In the Info file, this generates the specified control character, output
380: literally into the file.
381:
382: In a printed manual, this generates text to describe or identify that
383: control character: an uparrow followed by the character @var{ch}.
384:
385: @subsection @@var
386:
387: @code{@@var} is used to indicate metasyntactic variables. Its effect in
388: the Info file is to upcase the argument; in the printed manual, to
389: italicize it. Example:
390:
391: @example
392: To delete file @@var@{file@}, type @@code@{rm @@var@{file@}@}.
393: @end example
394:
395: @noindent
396: produces
397:
398: @quotation
399: To delete file @var{file}, type @code{rm @var{file}}.
400: @end quotation
401:
402: @subsection @@dfn
403:
404: @code{@@dfn} is used to identify the introductory or defining use of a
405: technical term. It generates italics in the printed manual, and double
406: quotation marks in the Info file. Example:
407:
408: @example
409: Getting rid of a file is called @@dfn@{deleting@} it.
410: @end example
411:
412: @noindent
413: produces
414:
415: @quotation
416: Getting rid of a file is called @dfn{deleting} it.
417: @end quotation
418:
419: @subsection @@i or @@b or @@t
420:
421: These three commands specify font change in the printed manual and have no
422: effect in the Info file. @code{@@i} requests italic font (actually,
423: slanted font is used by @TeX{}), @code{@@b} requests bold face, and
424: @code{@@t} requests the fixed-width font used by @code{@@kbd}.
425: All three commands apply to an argument that follows, surrounded by
426: braces.@refill
427:
428: @subsection @@w
429:
430: In a printed manual, @code{@@w@{@var{text}@}} outputs @var{text} and prohibits
431: line breaks within @var{text}. @code{@@w} has no effect on the Info file
432: output; it is the same as would result from just @var{text}.
433:
434: @subsection @@refill
435:
436: If a paragraph contains sizeable @@-constructs, it may look badly filled
437: once texinfo is through with it.
438:
439: Put @code{@@refill} at the end of the paragraph to tell texinfo to
440: refill the paragraph after finishing all other processing on it.
441: @code{@@refill} has no effect on @TeX{}, which always fills everything
442: that ought to be filled. Example:@refill
443:
444: @example
445: To use @@code@{foo@}, pass @@samp@{xx%$@} and @@var@{flag@} and type @@kbd@{x@}
446: after running @@code@{make-foo@}.@@refill
447: @end example
448:
449: @noindent
450: produces (in the Info file)
451:
452: @example
453: To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
454: @end example
455:
456: @noindent
457: whereas without the @code{@@refill} it would produce
458:
459: @example
460: To use `foo', pass `xx%$' and FLAG and type `x'
461: after running `make-foo'.
462: @end example
463:
464: @noindent
465: with the line broken at the same place as in the input.
466:
467: @section Chapter Structuring Commands
468:
469: The chapter structuring commands divide a document into a hierarchy of
470: chapters, sections, subsections and subsubsections. These commands
471: generate large headings in the middle of the text.
472:
473: In a printed manual, the table of contents is based on the information
474: specified by the chapter structuring commands.
475:
476: @subsection @@chapter
477:
478: @code{@@chapter} identifies a chapter in the document. It is followed by a
479: single argument which is the rest of the line, as in
480:
481: @example
482: @@chapter Texinfo Files
483: @end example
484:
485: In @TeX{}, it serves to create a chapter of the document, specifying the
486: chapter title.
487:
488: In the Info file, @code{@@chapter} causes its argument to appear on a line
489: by itself, with a line of asterisks inserted underneath. Thus, the above
490: example produces the output@refill
491:
492: @example
493: Texinfo Files
494: *************
495: @end example
496:
497: @subsection @@unnumbered, @@appendix
498:
499: These are equivalent to @code{@@chapter} for Info file output. In a
500: printed manual, they generate chapters that are numbered differently in the
501: table of contents. @code{@@unnumbered} chapters appear without chapter
502: numbers of any kind, and @code{@@appendix} chapters are given a letter
503: instead of a number.
504:
505: @subsection @@section
506:
507: @code{@@section} is like @code{@@chapter} except that in @TeX{} it makes
508: a section rather than a chapter. Sections go within chapters. In the Info
509: file, @code{@@chapter} and @code{@@section} differ only in that
510: @code{@@section} underlines with @samp{=}.@refill
511:
512: @subsection @@unnumberedsec, @@appendixsec
513:
514: Use these constructs for sections within chapters made by
515: @code{@@unnumbered} or @code{@@appendix}.
516:
517: @subsection @@subsection
518:
519: Subsections are to sections as sections are to chapters. They are
520: underlined with @samp{-}.
521:
522: @subsection @@unnumberedsubsec, @@appendixsubsec
523:
524: Use these constructs for subsections within sections within chapters made
525: by @code{@@unnumbered} or @code{@@appendix}.
526:
527: @subsection @@subsubsection
528:
529: Subsubsections are to subsections as subsections are to sections. They are
530: underlined with periods.
531:
532: @section Nodes and Cross References
533:
534: @dfn{Nodes} are the points to which cross-references can refer. The
535: @code{@@node} command is used to define them. Each node must be, also, a
536: chapter, section, subsection or subsubsection, and the @code{@@node}
537: command must always be followed by a chapter structuring command (with no
538: blank line between them).
539:
540: In the Info file, nodes play a fundamental role. Each node has a name,
541: and other nodes can refer to it by that name. The @code{@@node} command
542: specifies the name of the node that it defines, and also defines certain
543: references to other nodes. References to other nodes can also be defined
544: with @code{@@menu} and the variants of @code{@@xref}.
545:
546: In a printed manual, nodes are not a fundamental concept, but the
547: @code{@@node} command still serves to define a cross-reference point
548: and the variants of @code{@@xref} still serve to make references.
549:
550: @subsection @@node
551:
552: @code{@@node} defines the beginning of a new node in the Info output file
553: (@inforef{top, info, info}.). It is followed by four arguments, separated
554: by commas, making up the rest of the line. For example,@refill
555:
556: @example
557: @@node info, tex, commands, top
558: @end example
559:
560: @noindent
561: defines a node named @code{info}, whose `next' pointer is to node
562: @code{tex}, whose `previous' pointer is to node @code{commands}, and whose
563: `up' pointer is to node @code{top}. What this means is that texinfo
564: changes @w{@code{@@node @var{args}}} into the special text string necessary to
565: separate Info nodes and to identify the node that is starting and say what
566: nodes it points to.@refill
567:
568: The pointer names should be the names of nodes defined elsewhere. For this
569: example, nodes named @code{tex}, @code{commands} and @code{top} should be
570: defined elsewhere in the file with other @code{@@node} commands. It does
571: not matter whether they are before or after the node that refers to
572: them.@refill
573:
574: Normally, node @var{a}'s `up' should point at the node whose menu mentions
575: node @var{a}. Node @var{a}'s `next' should point at the node that follows
576: @var{a} in that menu, and node @var{a}'s `previous' should point at the
577: node that precedes @var{a} in that menu.@refill
578:
579: The top node of the file, named @samp{top}, should have as its parent the
580: name of a node in another file, where there is a menu that leads to this
581: file. Specify the file name in parentheses. If this file is to be
582: installed directly in the Info directory file, use @samp{(dir)} as the
583: parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
584: in the file @file{dir}, which is the main menu of Info.
585:
586: In @TeX{}, @code{@@node} is nearly ignored. It generates no text. Its
587: only function is to identify the name to use for cross-references to the
588: following chapter or section which makes up the body of the node. (Cross
589: references are made with @code{@@xref}.)@refill
590:
591: @code{@@node} should always be followed immediately by a
592: chapter-structuring command such as @code{@@chapter}, @code{@@section},
593: @code{@@subsection} or @code{@@subsubsection}.
594:
595: @subsection @@menu
596:
597: Info file nodes can contain @dfn{menus} which point to other nodes. You
598: must type the menus in by hand, and surround them with lines containing
599: @code{@@menu} and @code{@@end menu}. The @code{@@menu} line changes
600: into @code{* Menu:}, which indicates the beginning of a menu to the Info
601: program. The contents are unchanged by texinfo, except for the processing
602: of any other @@ commands within. The entire menu construct has no effect
603: in the printed manual.@refill
604:
605: @example
606: @@menu
607: * foo:: The node named foo tells you how to go fooing.
608: * sw: switches. Type @@code@{m sw@} to see node @@code@{switches@}.
609: which describes the switches available here.
610: @@end menu
611: @end example
612:
613: @noindent
614: produces
615:
616: @example
617: * menu:
618:
619: * foo:: The node named foo tells you how to go fooing.
620: * sw: switches. Type `m sw' to see node `switches'
621: which describes the switches available here.
622: @end example
623:
624: In this example, the menu has two items. @samp{foo} is both a menu item name
625: and the name of the node referred to by that item. @samp{sw} is the other
626: menu item name, and it refers to the node named @samp{switches}. Since no
627: file name is specified with @samp{foo} or @samp{switches}, they must be the names
628: of other nodes in the same Info file. Nodes in other Info files can be
629: referred to by putting the file name in parentheses at the beginning of the
630: node name.
631:
632: @subsection @@xref
633:
634: @code{@@xref} generates a cross-reference. In texinfo, it turns into
635: an Info cross-reference which the Info @code{f} command can use
636: to go directly to another node. In @TeX{}, it turns into a sentence
637: of the form
638:
639: @example
640: See section @var{section} [@var{topic}], page @var{page}
641: @end example
642:
643: @noindent
644: but does not generate a period to end it.
645:
646: @code{@@xref} must refer to an Info node created by @code{@@node}, by the
647: node's name. If I were in less of a rush, I would have made a node in this
648: file for each texinfo command, and put in plenty of @@xref's to
649: cross-reference them together. The big node named @code{commands} would
650: actually contain a menu naming the nodes for individual commands.
651:
652: @code{@@xref} is followed by an argument inside braces, since it is used
653: within a paragraph; but actually the text inside the braces is treated as
654: several arguments, separated by commas. Whitespace after these commas is
655: ignored. The closing brace must be followed by a period or a comma, since
656: one of those two is required to terminate an Info cross-reference. This
657: period or comma will appear in the output, both Info file and printed
658: manual.
659:
660: The simplest form of @code{@@xref} takes one argument, the name of another
661: node in the same Info file. Here we show the input text, followed after a
662: blank line by the output text for Info files and the output text for
663: printed manuals.
664:
665: @example
666: @@xref@{foo@}, for more info.
667:
668: *note foo::, for more info.
669: @end example
670:
671: @quotation
672: See section @var{nnn} [foo], page @var{ppp}, for more info.
673: @end quotation
674:
675: With two arguments, the second one is used as the name of the Info
676: cross-reference, while the first argument is still the node that the
677: cross-reference points to:
678:
679: @example
680: @@xref@{foo node, foo@}, for more info.
681:
682: *note foo: foo node, for more info.
683: @end example
684:
685: @quotation
686: See section @var{nnn} [foo node], page @var{ppp}, for more info.
687: @end quotation
688:
689: A third argument replaces the node name when it actually appears
690: in the TeX output. It should state the topic discussed by the
691: section being referenced. Use a third argument when the node
692: name is unsuitable because of syntax, grammar or diction.
693:
694: @example
695: @@xref@{foo node, foo, using foo@}, for more info.
696:
697: *note foo: foo node, for more info.
698: @end example
699:
700: @quotation
701: See section @var{nnn} [using foo], page @var{ppp}, for more info.
702: @end quotation
703:
704: If a third argument is given and the second one is empty,
705: then the third argument serves both purposes:
706:
707: @example
708: @@xref@{foo node, , using foo@}, for more info.
709:
710: *note using foo: foo node, for more info.
711: @end example
712:
713: @quotation
714: See section @var{nnn} [using foo], page @var{ppp}, for more info.
715: @end quotation
716:
717: A fourth argument specifies the name of the Info file in which
718: the referenced node is located, assuming it is not the one which
719: the reference appears in. @code{@@xref} with only four arguments
720: is used when the reference is not within one Info file, but is
721: within a single printed manual---when multiple texinfo files are
722: incorporated into the same TeX run but make separate Info files.
723:
724: @example
725: @@xref@{foo node, foo, using foo, myinfofile@}, for more info.
726:
727: *note foo: (myinfofile) foo node, for more info.
728: @end example
729:
730: @quotation
731: See section @var{nnn} [using foo], page @var{ppp}, for more info.
732: @end quotation
733:
734: A fifth argument is used when referencing another Info file
735: which is also part of another printed manual. It gives the
736: title of that manual.
737:
738: @example
739: @@xref@{foo node, foo, using foo, myinfofile, Mymanual@},
740: for more info.
741:
742: *note foo: (myinfofile) foo node, for more info.
743: @end example
744:
745: @quotation
746: See section @var{nnn} [using foo], page @var{ppp}
747: of Mymanual, for more info.
748: @end quotation
749:
750: @subsection @@pxref
751:
752: @code{@@pxref} is nearly the same as @code{@@xref}; it differs in only
753: two ways:
754:
755: @enumerate
756: @item
757: The output starts with lower case `see' rather than `See'.
758: @item
759: A period is generated automatically in the Info file output to end the
760: Info cross-reference.
761: @end enumerate
762:
763: The purpose of @code{@@pxref} is to be used inside parentheses as part of
764: another sentence. In the printed manual, no period is needed after the
765: cross reference text itself (within the parentheses), but a period is
766: needed there in the Info file because only thus can Info recognize the end
767: of the cross-reference. @code{@@pxref} spares you the need to use complicated
768: methods to put a period into one form of the output and not the other.
769:
770: @subsection @@inforef
771:
772: @code{@@inforef} is used for cross-references to Info files for which
773: there are no printed manuals. Even in a printed manual, @code{@@inforef}
774: generates a reference directing the user to look in an Info file. The
775: syntax is @code{@@inforef@{@var{node}, @var{name}, @var{file}@}}.
776:
777: @example
778: @@inforef@{foo node, fooing, FOO@}, to lose.
779:
780: *note fooing: (FOO) foo node, to lose.
781: @end example
782:
783: @quotation
784: See Info file @file{FOO}, node `foo node', to lose.
785: @end quotation
786:
787: @section Insertions
788:
789: Insertions are blocks of text, consisting of one or more whole paragraphs
790: that are set off from the bulk of the text and treated differently. They
791: are usually indented, and often not filled.
792:
793: In texinfo, an insertion is always begun by an @@-command on a line by
794: itself, and ended with an @code{@@end} command. For example, an @dfn{example}
795: is a kind of insertion that is begun with @code{@@example} and ended with
796: @code{@@end example}.
797:
798: @subsection @@quotation
799:
800: @code{@@quotation} is used to indicate text that is excerpted from another
801: (real or hypothetical) printed work. The inside of a quotation is
802: processed normally except that
803:
804: @enumerate
805: @item
806: The margins are narrower.
807: @item
808: Paragraphs are not indented.
809: @item
810: Interline spacing and interparagraph spacing are reduced.
811: @end enumerate
812:
813: Thus, the input
814:
815: @example
816: @@quotation
817: This is
818: a foo.
819: @@end quotation
820: @end example
821:
822: @noindent
823: produces in the printed manual
824:
825: @quotation
826: @quotation
827: This is a foo.
828: @end quotation
829: @end quotation
830:
831: @noindent
832: and in the Info file
833:
834: @quotation
835: @example
836: This is
837: a foo.
838: @end example
839: @end quotation
840:
841: @subsection @@example
842:
843: @code{@@example} is used to indicate an example that is not part of the
844: running text. In the printed manual, this is done by switching to
845: a fixed width font, turning off filling, and making extra spaces
846: and blank lines significant. In the Info file, an analogous result
847: is obtained by indenting each line with five extra spaces.
848:
849: @code{@@example} should appear on a line by itself; this line will
850: disappear from the output. Mark the end of the example with a line
851: containing @code{@@end example}, which will likewise disappear.
852: Example:
853:
854: @example
855: @@example
856: mv foo bar
857: @@end example
858: @end example
859:
860: @noindent
861: produces
862:
863: @quotation
864: @example
865: mv foo bar
866: @end example
867: @end quotation
868:
869: Don't use tabs in lines of an example!
870:
871: @subsection @@display
872:
873: @code{@@display} is just like @code{@@example} except that, in the
874: printed manual, @code{@@display} does not select the fixed-width font.
875: In fact, it does not specify the font at all, so that the text appears
876: in the same font it would have appeared in without the @code{@@display}.@refill
877:
878: @subsection @@itemize
879:
880: @code{@@itemize} is used to produce sequences of indented paragraphs, with
881: a mark inside the left margin at the beginning of each. The rest of the
882: line that starts with @code{@@itemize} should contain the character or
883: texinfo commands to generate such a mark. It should ultimately result in a
884: single character, or the indentation will come out wrong. You may use
885: the texinfo commands that are normally followed by @samp{@{@}}; in fact, you
886: may omit the @samp{@{@}} after the command if you use just one command
887: and nothing else.
888:
889: The text of the indented paragraphs themselves come after the @code{@@itemize},
890: up to another line that says @code{@@end @@itemize}.
891:
892: Before each paragraph for which a mark in the margin is desired, place a
893: line that says just @code{@@item}.
894:
895: Here is an example of the use of @code{@@itemize}, followed by the output
896: it produces. Note that @code{@@bullet} produces a @code{*} in texinfo and
897: a round dot in @TeX{}.
898:
899: @example
900: @@itemize @@bullet
901: @@item
902: Some text for foo.
903: @@item
904: Some text
905: for bar.
906: @@end itemize
907: @end example
908:
909: @noindent
910: produces
911:
912: @quotation
913: @itemize @bullet
914: @item
915: Some text for foo.
916: @item
917: Some text
918: for bar.
919: @end itemize
920: @end quotation
921:
922: Texinfo indents the lines of the itemization by five additional columns,
923: but it does not fill them. If @code{@@refill} is used, the paragraph is
924: filled to the narrowed width.
925:
926: @subsection @@enumerate
927:
928: @code{@@enumerate} is like @code{@@itemize} except that the marks in the
929: left margin contain successive integers starting with 1. Do not put any
930: argument on the same line as @code{@@enumerate}.@refill
931:
932: @example
933: @@enumerate
934: @@item
935: Some text for foo.
936: @@item
937: Some text
938: for bar.
939: @@end enumerate
940: @end example
941:
942: @noindent
943: produces
944:
945: @quotation
946: @enumerate
947: @item
948: Some text for foo.
949: @item
950: Some text
951: for bar.
952: @end enumerate
953: @end quotation
954:
955: @subsection @@table
956:
957: @code{@@table} is similar to @code{@@itemize}, but allows you to specify a
958: name or heading line for each item.
959:
960: You must follow each use of @code{@@item} inside of @code{@@table} with
961: text to serve as the heading line for that item.
962:
963: Also, @code{@@table} itself must be followed by an argument that is a
964: texinfo command such as @code{@@code}, @code{@@var}, @code{@@kbd} or
965: @code{@@asis}. This command will be applied to the text of each item.
966: @code{@@asis} is a command that does nothing; in that case, each item will
967: come out exactly as it specifies. (Various other command names might work
968: in this context. Only commands that normally take arguments in braces may
969: be used, but here you use the command name without an argument.
970: @code{@@item} supplies the arguments.)@refill
971:
972: @example
973: @@table @@samp
974: @@item foo
975: This is the text for
976: @@samp@{foo@}.
977: @@item bar
978: Text for @@samp@{bar@}.
979: @@end table
980: @end example
981:
982: @noindent
983: produces
984:
985: @quotation
986: @table @samp
987: @item foo
988: This is the text for
989: @samp{foo}.
990: @item bar
991: Text for @samp{bar}.
992: @end table
993: @end quotation
994:
995: @subsection @@itemx
996:
997: @code{@@itemx} is used inside a @code{@@table} when you have
998: two or more named items for the same block of text. Use @code{@@itemx}
999: for all but the first of the items. It works exactly like @code{@@item}
1000: except that it does not generate extra vertical space above the item text.
1001: Example:@refill
1002:
1003: @example
1004: @@table @@code
1005: @@item upcase
1006: @@itemx downcase
1007: These two functions accept a character or a string as argument,
1008: and return the corresponding upper case (lower case) character
1009: or string.
1010: @@end table
1011: @end example
1012:
1013: @noindent
1014: produces
1015:
1016: @quotation
1017: @table @code
1018: @item upcase
1019: @itemx downcase
1020: These two functions accept a character or a string as argument,
1021: and return the corresponding upper case (lower case) character
1022: or string.
1023: @end table
1024: @end quotation
1025:
1026: @subsection @@noindent
1027:
1028: @code{@@noindent} is not a kind of insertion, but it is normally used
1029: following an insertion.
1030:
1031: If you have text following an @code{@@example} or other similar ``special
1032: paragraph'' that reads as a continuation of the text before the
1033: @code{@@example}, it is good to prevent this text from being indented as a
1034: new paragraph. To accomplish this, put @code{@@noindent} on a line by
1035: itself before the start of the text that should not be indented.
1036:
1037: To adjust the number of blank lines properly in the Info file output,
1038: remember that the line containing @code{@@noindent} does not generate a
1039: blank line, and neither does the @code{@@end example} line.
1040:
1041: In the texinfo source file for this documentation, each of the lines that
1042: says `produces' is preceded by a line containing @code{@@noindent}.
1043:
1044: @section Other Paragraph-Separating Commands
1045:
1046: @subsection @@setfilename
1047:
1048: @code{@@setfilename @var{file}} informs texinfo that the Info file being
1049: produced is named @var{file}. This information is entered in every node
1050: header. It also tells texinfo the name for the output file.
1051:
1052: @subsection @@comment
1053:
1054: A line starting with @code{@@comment} or @code{@@c} is ignored in both
1055: printed and Info output.
1056:
1057: @subsection @@ignore
1058:
1059: A line saying @code{@@ignore} causes everything up to the following
1060: @code{@@end ignore} to be ignored in both printed and Info output.
1061:
1062: @subsection @@br
1063:
1064: In a printed manual, a line containing @code{@@br} forces a paragraph
1065: break; in the Info file output, it does nothing (not even a blank line
1066: results from it).
1067:
1068: @subsection @@sp
1069:
1070: A line containing @code{@@sp @var{n}} generates @var{n} blank lines of space in either the
1071: printed manual or the Info file.
1072:
1073: @subsection @@page
1074:
1075: A line containing @code{@@page} starts a new page in a printed manual. The
1076: line has no effect on Info files since they are not paginated.
1077:
1078: @subsection @@group
1079:
1080: A line containing @code{@@group} begins an unsplittable vertical group,
1081: which must appear entirely on one page. The group is terminated by a line
1082: containing @code{@@end group}. These two lines produce no output of their
1083: own, and in the Info file output they have no effect at all.
1084:
1085: @subsection @@need
1086:
1087: A line containing @code{@@need @var{n}} starts a new page in a printed
1088: manual if fewer than @var{n} mils (thousandths of an inch) remain on the
1089: current page. The line has no effect on Info files since they are not
1090: paginated.@refill
1091:
1092: @subsection @@center
1093:
1094: A line containing @code{@@center @var{text}} produces a line of output containing @var{text},
1095: centered between the margins.
1096:
1097: @subsection Conditionals
1098:
1099: You may not always be able to use the same text for @TeX{} and texinfo.
1100: Use the conditional commands to specify which text is for @TeX{} and which
1101: is for texinfo.
1102:
1103: @code{@@ifinfo} begins text that should be ignored by @TeX{}. It should
1104: appear on a line by itself. End the texinfo-only text with a line
1105: containing @code{@@end ifinfo}.@refill
1106:
1107: Likewise, @code{@@iftex} and @code{@@end iftex} lines delimit code
1108: that should be ignored by texinfo.@refill
1109:
1110: @section Generating Indices
1111:
1112: Texinfo files can generate indices automatically. Each index covers
1113: a certain kind of entry (functions, or variables, or concepts, etc.)@:
1114: and lists all of those entries in alphabetical order, together with
1115: information on how to find the discussion of each entry. In a printed
1116: manual, this information consists of page numbers. In an Info file,
1117: it consists of a menu item leading to the node in which the entry
1118: is discussed.
1119:
1120:
1121: Normally, six indices are provided for:
1122:
1123: @itemize @bullet
1124: @item
1125: A @dfn{program index} listing names of programs and leading to the places
1126: where those programs are documented.
1127:
1128: @item
1129: A @dfn{function index} listing functions (such as, entry points of
1130: libraries).
1131:
1132: @item
1133: A @dfn{variables index} listing variables (such as, external variables of
1134: libraries).
1135:
1136: @item
1137: A @dfn{data type index} listing data types (such as, structures defined in
1138: header files).
1139:
1140: @item
1141: A @dfn{keystroke index} listing keyboard commands.
1142:
1143: @item
1144: A @dfn{concept index} listing concepts that are discussed.
1145: @end itemize
1146:
1147: @noindent
1148: Not every manual needs all of these. Two or more indices can be combined
1149: into one using the @code{@@synindex} command as described below.
1150:
1151: @subsection Defining the Entries of an Index
1152:
1153: The data to make an index comes from many individual commands scattered
1154: throughout the source file. Each command says to add one entry to a
1155: particular index, giving the current page number or node name as the
1156: reference.
1157:
1158: @table @code
1159: @item @@cindex @var{concept}
1160: Make an entry in the concept index for @var{concept}, referring to the
1161: current page or node.
1162: @item @@findex @var{function}
1163: Make an entry in the function index for @var{function}, referring to the
1164: current page or node.
1165: @item @@vindex @var{variable}
1166: Make an entry in the variable index for @var{variable}, referring to the
1167: current page or node.
1168: @item @@pindex @var{program}
1169: Make an entry in the program index for @var{program}, referring to the
1170: current page or node.
1171: @item @@kindex @var{key}
1172: Make an entry in the key index for @var{key}, referring to the
1173: current page or node.
1174: @item @@tindex @var{data type}
1175: Make an entry in the data type index for @var{data type}, referring to the
1176: current page or node.
1177: @end table
1178:
1179: If the same name is indexed on several pages, all the pages are listed
1180: in the printed manual's index. However, only the first node referenced
1181: will appear in the index of an Info file.
1182:
1183: You are not actually required to use these indices for their canonical
1184: purposes. For example, you might wish to index some C preprocessor macros.
1185: You could put them in the function index along with actual functions, just
1186: by writing @code{@@findex} commands for them; then, when you print the
1187: ``function index'', you could give it the title `Function and Macro Index'
1188: and all will be consistent for the reader. Or you could put the macros in
1189: with the data types by writing @code{@@tindex} commands for them, and give
1190: that index a suitable title so the reader will understand.
1191:
1192: @subsection Combining Indices
1193:
1194: Sometimes you will want to combine two disparate indices such as functions
1195: and variables, perhaps because you have few enough of one of them that
1196: a separate index for them would look silly.
1197:
1198: You could put variables into the function index by writing @code{@@findex}
1199: commands for them instead of @code{@@vindex} commands, and produce a
1200: consistent manual by printing the function index with the title `Function
1201: and Variable Index' and not printing the ``variable index'' at all; but this
1202: is not a robust procedure. It works only as long as your document is never
1203: included in part of or together with another document that is designed to
1204: have a separate variable index; if you did that, the variables from your
1205: document and those from the other would not end up together.
1206:
1207: What you should do instead when you want functions and variables in one
1208: index is to index the variables with @code{@@vindex} as they should be,
1209: but in the overall file for the document use @code{@@synindex} to redirect
1210: these @code{@@vindex} commands to the function index. @code{@@synindex} takes two
1211: arguments: the name of an index to redirect, and the name of an index to
1212: redirect it to. For this purpose, the indices are given two-letter names:
1213:
1214: @table @samp
1215: @item cp
1216: the concept index.
1217: @item vr
1218: the variable index.
1219: @item fn
1220: the function index.
1221: @item ky
1222: the key index.
1223: @item pg
1224: the program index.
1225: @item tp
1226: the data type index.
1227: @end table
1228:
1229: Thus, @code{@@synindex vr fn} at the front of an overall manual file
1230: will cause all entries designated for the variable index to go to
1231: the function index as well. But the included files of this manual
1232: could be used in some other manual, that does not do @code{@@synindex},
1233: and generate a separate variable index.
1234:
1235: If the texinfo file containing @code{@@synindex} is also to be made into
1236: an Info file itself, you should use @code{@@iftex} around the @code{@@synindex}
1237: commands.
1238:
1239: @subsection Printing an Index
1240:
1241: To print an index means to include it as part of a manual or Info file.
1242: This does not happen automatically just because you use @code{@@cindex} or
1243: other index-entry generating commands in the input; those just cause the
1244: raw data for the index to be accumulated. To print an index, you must
1245: include special texinfo commands at the place in the document where you
1246: want the index to appear. Also, for the case of the printed manual, you
1247: must run a special program to sort the raw data to produce a sorted index
1248: file, which is what will actually be used to print the index.@refill
1249:
1250: The texinfo command you need is @code{@@printindex}. It takes the
1251: two-letter index name (see table above) as an argument without braces, and
1252: reads the corresponding sorted index file and formats it appropriately into
1253: an index.@refill
1254:
1255: @code{@@printindex} does not generate a chapter heading for the index.
1256: You should precede it with a suitable section or chapter command (usually
1257: @code{@@unnumbered}) to supply the chapter heading and put the index into
1258: the table of contents. And before that, you probably need a @code{@@node}
1259: command. For example,@refill
1260:
1261: @example
1262: @@node Variables Index, Concept Index, Function Index, Top
1263: @@unnumbered Variable Index
1264:
1265: @@printindex vr
1266:
1267: @@node Concept index,, Variables Index, Top
1268: @@unnumbered Concept Index
1269:
1270: @@printindex cp
1271: @end example
1272:
1273: @subsection Sorting Indices
1274:
1275: In @TeX{}, @code{@@printindex} needs a sorted index file to work from.
1276: @TeX{} does not know how to do sorting; this is one of the main
1277: deficiencies of @TeX{}. You must invoke the program @code{texindex} to do
1278: so, giving it the names of the raw index files to be sorted as arguments.
1279: You do not have to run @code{texindex} on all of them; only the ones you
1280: are going to print.
1281:
1282: @TeX{} outputs raw index files under names that obey a standard convention.
1283: These names are the name of your main input file to @TeX{}, with everything
1284: after the first period thrown away, and the two letter names of indices
1285: added at the end. For example, the raw index output files for the input
1286: file @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr},
1287: @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are
1288: exactly the arguments to give to @code{texindex}.@refill
1289:
1290: For each file specified, @code{texindex} generates a sorted index file whose
1291: name is made by appending @samp{s} to the input file name. The
1292: @code{@@printindex} command knows to look for a file of that name.
1293: @code{texindex} does not alter the raw index output file.@refill
1294:
1295: You need not run @code{texindex} after each @TeX{} run. If you don't, the
1296: next @TeX{} run will use whatever sorted index files happen to exist from
1297: the previous use of @code{texindex}. This is usually ok while you are
1298: debugging.
1299:
1300: @node make-info, manual ,commands, top
1301: @section Converting Texinfo Files into Info Files
1302:
1303: Just visit a texinfo file and invoke
1304:
1305: @example
1306: @kbd{Meta-x texinfo-format-buffer}
1307: @end example
1308:
1309: @noindent
1310: to convert it to an Info file. A new buffer is created and the Info file
1311: text is generated there. @kbd{C-x C-s} will save it under the name specified
1312: in the @code{@@setfilename} command.
1313:
1314: If the file is large (more than 30 nodes) it is desirable to make a
1315: @dfn{tag table} for it. To do this, load the @code{info} library
1316: into Emacs with @kbd{M-x load @key{RET} info @key{RET}} and then
1317: do @kbd{M-x Info-tagify}.@refill
1318:
1319: To check your node structure for errors, load Info and then do
1320: @kbd{M-x Info-validate}.
1321:
1322: @node manual,, make-info, top
1323: @section Generating a Real Manual
1324:
1325: Most of the time a single printed manual will be made from several texinfo
1326: source files, each of which is made into a single Info file. Also, the
1327: real manual should have a table of contents. Several special commands are
1328: used for these purposes.
1329:
1330: Every texinfo file that is to be the top-level input to @TeX{} must begin
1331: with a line that looks like
1332:
1333: @example
1334: \input texinfo @@c -*-texinfo-*-
1335: @end example
1336:
1337: @noindent
1338: This serves two functions.
1339:
1340: @enumerate
1341: @item
1342: When the file is processed by @TeX{}, it loads the macros needed for
1343: processing a texinfo file.
1344: @item
1345: When the file is edited in Emacs, it causes Texinfo Mode to be used.
1346: @end enumerate
1347:
1348: Every such texinfo file must end with a line saying
1349:
1350: @example
1351: @@bye
1352: @end example
1353:
1354: which terminates @TeX{} processing and forces out unfinished pages.
1355:
1356: You might also want to include a line saying
1357:
1358: @example
1359: @@setchapternewpage odd
1360: @end example
1361:
1362: @noindent
1363: to cause each chapter to start on a fresh odd-numbered page.
1364:
1365: Here is an example of a texinfo file used to generate a manual from two
1366: other texinfo files, @samp{foo.texinfo} and @samp{bar.texinfo}, each of
1367: which makes a separate Info file. The commands used in it are explained
1368: in the rest of this section.@refill
1369:
1370: @example
1371: \input texinfo @@c -*-texinfo-*-
1372: @@settitle This Manual
1373:
1374: @@c put entries intended for the data type index
1375: @@c into the variable index instead.
1376: @@synindex tp vr
1377: @@setchapternewpage odd
1378:
1379: @@titlepage
1380: @@sp 10
1381: @@center @@titlefont@{This Manual@}
1382: @@sp 3
1383: @@center by
1384: @@sp 3
1385: @@center @@titlefont@{Me@}
1386: @@end titlepage
1387:
1388: @@c Include the files with the actual text
1389: @@include foo.texinfo
1390: @@include bar.texinfo
1391:
1392: @@c Print the indices
1393: @@unnumbered Function Index
1394: @@printindex fn
1395: @@unnumbered Variable and Data Type Index
1396: @@printindex vr
1397: @@unnumbered Program Index
1398: @@printindex pg
1399: @@unnumbered Concept Index
1400: @@printindex cp
1401:
1402: @@c Print the tables of contents
1403: @@summarycontents
1404: @@contents
1405:
1406: @@c That's all
1407: @@bye
1408: @end example
1409:
1410: @subsection Title Page
1411:
1412: Start the material for the title page with @samp{@@titlepage} and follow it
1413: with @samp{@@end titlepage}. Both of these commands should stand alone on
1414: a line. They cause the title material to appear only in the printed
1415: manual, not in an info file. Also, the @samp{@@end titlepage} command
1416: starts a new page and turns on page numbering (generation of headings).
1417:
1418: The within-paragraph command @samp{@@titlefont} can be used to select a
1419: large font suitable for the title itself.
1420:
1421: @subsection Headings
1422:
1423: Texinfo prints the manual title on every other page as a heading, and the
1424: current chapter title on the remaining pages. It knows the chapter title
1425: automatically, but you must tell it the manual title with @code{@@settitle}:
1426:
1427: @example
1428: @@settitle @var{title}
1429: @end example
1430:
1431: @noindent
1432: on a line by itself causes @var{title} to be used for the headings.
1433:
1434: The @code{@@settitle} command should precede everything that generates
1435: actual output.
1436:
1437: Normally, headings start appearing after the @samp{@@end titlepage} command.
1438: (They are not wanted on the title page.) However, you can turn headings on
1439: and off explicitly with the @samp{@@headings} command:
1440:
1441: @example
1442: @@headings on
1443: @end example
1444:
1445: @noindent
1446: to start output of headings (starting with the page containing the command)
1447: or
1448:
1449: @example
1450: @@headings off
1451: @end example
1452:
1453: @noindent
1454: to stop output of headings (starting also with the current page).
1455:
1456: @subsection @@include
1457:
1458: A line of the form @code{@@include @var{filename}} is ignored when generating an
1459: Info file, but in a printed manual it causes the contents of the file
1460: @var{filename} to be processed at that point.
1461:
1462: Normally, the file named @var{filename} is made into a separate Info file.
1463: The file containing the @code{@@include} may refer to the other Info file
1464: with Info cross-references or menus, since those fill the function of
1465: inclusion for the Info data base.
1466:
1467: Another technique is to have a special file, used only for making a
1468: comprehensive manual, containing nothing but the beginning, the end, and a
1469: bunch of @code{@@include} commands.
1470:
1471: A file that is intended to be processed with @code{@@include} should not
1472: start with @samp{\input texinfo}, as that has already been done by the
1473: outer file, and the character @samp{\} has already been redefined to
1474: generate a backslash in the output.
1475:
1476: A file that is intended to be processed with @code{@@include} should not
1477: end with @code{@@bye}, since that would terminate @TeX{} processing immediately.
1478:
1479: @subsection Table of Contents
1480:
1481: The commands @code{@@chapter}, @code{@@section}, etc., supply the
1482: information to make up a table of contents, but they do not cause an actual
1483: table to be output. To do this, you must use the commands
1484: @code{@@contents} and @code{@@summarycontents}.@refill
1485:
1486: @code{@@contents}, which should be used on a line by itself, outputs (into
1487: a printed manual) a complete table of contents, based on the
1488: @code{@@chapter} and other sectioning commands already seen.@refill
1489:
1490: @code{@@summarycontents} generates a summary table of contents that lists
1491: only the chapters (and appendixes and unnumbered chapters); sections,
1492: subsections and subsubsections are omitted.
1493:
1494: You can use either one of these commands, or both. Each one automatically
1495: generates a chapter-like heading at the top of the page. Tables of
1496: contents should be generated at the very end of the manual, just before the
1497: @code{@@bye} command; they should follow any indices that are output, so
1498: that the indices will appear in the contents.
1499:
1500: @example
1501: @var{indices}@dots{}
1502: @@summarycontents
1503: @@contents
1504: @@bye
1505: @end example
1506:
1507: The commands @code{@@contents} and @code{@@summarycontents} are ignored when an
1508: Info file is being generated.
1509:
1510: @contents
1511: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.