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