![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to texinfo-2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info|
Return to texinfo-2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info |
1.1 root 1: Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
2: input file texinfo.texinfo.
3:
4: This file documents Texinfo, a documentation system that uses a
5: single source file to produce both on-line help and a printed manual.
6:
7: This is edition 1.1 of the Texinfo documentation, and is for the
8: Texinfo that is distributed as part of Version 18 of GNU Emacs.
9:
10: Copyright (C) 1988 Free Software Foundation, Inc.
11:
12: Permission is granted to make and distribute verbatim copies of this
13: manual provided the copyright notice and this permission notice are
14: preserved on all copies.
15:
16: Permission is granted to copy and distribute modified versions of
17: this manual under the conditions for verbatim copying, provided that
18: the entire resulting derived work is distributed under the terms of a
19: permission notice identical to this one.
20:
21: Permission is granted to copy and distribute translations of this
22: manual into another language, under the above conditions for modified
23: versions, except that this permission notice may be stated in a
24: translation approved by the Foundation.
25:
26:
27:
28: File: texinfo, Node: Indices, Prev: Contents, Up: Ending a File
29:
30: Creating Indices
31: ================
32:
33: Using Texinfo, you can generate printed indices and Info file menus
34: without having to sort and collate entries manually. Texinfo will do
35: this for you automatically. Each index covers a certain kind of
36: entry (functions, or variables, or concepts, etc.) and lists all of
37: those entries in alphabetical order, together with information on how
38: to find the discussion of each entry. In a printed manual, this
39: information consists of page numbers. In an Info file, it consists
40: of a menu item leading to the first node referenced.
41:
42: When you are making index entries, it is good practice to think of
43: the different categories under which people may look for something.
44: Different people *do not* think of the same words when they look
45: something up. They think of different words. A helpful index will
46: have items indexed under all the different words that people may use.
47: For example, someone might think it obvious that the two letter names
48: for indices should be listed under ``Indices, two letter names'',
49: since the word ``Index'' is the general concept. But another reader
50: may remember the specific concept of two letter names and search for
51: the entry listed as ``Two letter names for indices''. A good index
52: will have both entries and will help both kinds of user.
53:
54: Like typesetting, the construction of an index is a highly skilled,
55: professional art, the subtleties of which are not appreciated until
56: you have to do it yourself.
57:
58: Normally, six indices are provided for:
59:
60: * A "program index" listing names of programs and leading to the
61: places where those programs are documented.
62:
63: * A "function index" listing functions (such as, entry points of
64: libraries).
65:
66: * A "variables index" listing variables (such as, external
67: variables of libraries).
68:
69: * A "data type index" listing data types (such as, structures
70: defined in header files).
71:
72: * A "keystroke index" listing keyboard commands.
73:
74: * A "concept index" listing concepts that are discussed.
75:
76: Not every manual needs all of these. This manual has two indices: a
77: concept index and an @-command index (that uses the function index
78: but is called a command index in the chapter heading). Two or more
79: indices can be combined into one using the `@synindex' command.
80: *Note Combining Indices::.
81:
82: * Menu:
83:
84: * Index Entries:: Defining the entries of an index
85: * Combining Indices::
86: * Printing Indices & Menus::
87:
88:
89:
90: File: texinfo, Node: Index Entries, Next: Combining Indices, Up: Indices
91:
92: Defining the Entries of an Index
93: --------------------------------
94:
95: The data to make an index comes from many individual commands
96: scattered throughout the Texinfo source file. Each command says to
97: add one entry to a particular index; after processing, it will give
98: the current page number or node name as the reference.
99:
100: `@cindex CONCEPT'
101: Make an entry in the concept index for CONCEPT, referring to the
102: current page or node.
103:
104: `@findex FUNCTION'
105: Make an entry in the function index for FUNCTION, referring to
106: the current page or node.
107:
108: `@vindex VARIABLE'
109: Make an entry in the variable index for VARIABLE, referring to
110: the current page or node.
111:
112: `@pindex PROGRAM'
113: Make an entry in the program index for PROGRAM, referring to the
114: current page or node.
115:
116: `@kindex KEY'
117: Make an entry in the key index for KEY, referring to the current
118: page or node.
119:
120: `@tindex DATA TYPE'
121: Make an entry in the data type index for DATA TYPE, referring to
122: the current page or node.
123:
124: If the same name is indexed on several pages, all the pages are
125: listed in the printed manual's index. However, *only* the *first*
126: node referenced will appear in the index of an Info file. This means
127: that it is best to write indices in which each entry will refer to
128: only one place in the Texinfo file. Fortunately, this constraint is
129: a feature rather than loss since it means that the index will be easy
130: to use. Otherwise, it can be easy to create an index which has many
131: pages listed for an entry and you don't know which one you need.
132:
133: You are not actually required to use indices for their canonical
134: purposes. For example, you might wish to index some C preprocessor
135: macros. You could put them in the function index along with actual
136: functions, just by writing `@findex' commands for them; then, when
137: you print the ``function index'', you could give it the title
138: `Function and Macro Index' and all will be consistent for the reader.
139: Or you could put the macros in with the data types by writing
140: `@tindex' commands for them, and give that index a suitable title so
141: the reader will understand.
142:
143:
144:
145: File: texinfo, Node: Combining Indices, Next: Printing Indices & Menus, Prev: Index Entries, Up: Indices
146:
147: Combining Indices
148: -----------------
149:
150: Sometimes you will want to combine two disparate indices such as
151: functions and variables, perhaps because you have few enough of one
152: of them that a separate index for them would look silly.
153:
154: You could put variables into the function index by writing `@findex'
155: commands for them instead of `@vindex' commands, and produce a
156: consistent manual by printing the function index with the title
157: `Function and Variable Index' and not printing the `Variable Index'
158: at all; but this is not a robust procedure. It works only as long as
159: your document is never included in part of or together with another
160: document that is designed to have a separate variable index; if you
161: did that, the variables from your document and those from the other
162: would not end up together.
163:
164: What you should do instead when you want functions and variables in
165: one index is to index the variables with `@vindex' as they should be,
166: but use the `@synindex' command to redirect these `@vindex' commands
167: to the function index. `@synindex' takes two arguments: the name of
168: an index to redirect, and the name of an index to redirect it to.
169: For this purpose, the indices are given two-letter names:
170:
171: `cp'
172: the concept index
173:
174: `vr'
175: the variable index
176:
177: `fn'
178: the function index
179:
180: `ky'
181: the key index
182:
183: `pg'
184: the program index
185:
186: `tp'
187: the data type index
188:
189: Thus, `@synindex vr fn' at the front of a Texinfo file will cause all
190: entries designated for the variable index to go to the function index
191: instead.
192:
193:
194:
195: File: texinfo, Node: Printing Indices & Menus, Prev: Combining Indices, Up: Indices
196:
197: Printing an Index and Generating Menus
198: --------------------------------------
199:
200: To print an index means to include it as part of a manual or Info file.
201: This does not happen automatically just because you use `@cindex' or
202: other index-entry generating commands in the Texinfo file; those just
203: cause the raw data for the index to be accumulated. To print an
204: index, you must include the `@printindex' command at the place in the
205: document where you want the index to appear. Also, for the case of
206: the printed manual, you must run a program called `texindex' to sort
207: the raw data to produce a sorted index file, which is what will
208: actually be used to print the index.
209:
210: The Texinfo command that is used to print indices is `@printindex'.
211: It takes the two-letter index name (*note Combining Indices::.) as an
212: argument without braces, and reads the corresponding sorted index
213: file and formats it appropriately into an index.
214:
215: The two-letter index names are:
216:
217: `cp'
218: the concept index.
219:
220: `vr'
221: the variable index.
222:
223: `fn'
224: the function index.
225:
226: `ky'
227: the key index.
228:
229: `pg'
230: the program index.
231:
232: `tp'
233: the data type index.
234:
235: `@printindex' does not generate a chapter heading for the index.
236: Consequently, you should precede the command with a suitable section
237: or chapter command (usually `@unnumbered') to supply the chapter
238: heading and put the index into the table of contents. And before
239: that, you will probably put a `@node' command. For example,
240:
241: @node Variables Index, Concept Index, Function Index, Top
242: @comment node-name, next, previous, up
243: @unnumbered Variable Index
244:
245: @printindex vr
246:
247: @node Concept Index, , Variables Index, Top
248: @comment node-name, next, previous, up
249: @unnumbered Concept Index
250:
251: @printindex cp
252:
253: @summarycontents
254: @contents
255: @bye
256:
257: In TeX, `@printindex' needs a sorted index file to work from. TeX
258: does not know how to do sorting; this is one of the main deficiencies
259: of TeX. You must invoke the program `texindex' to do so, giving it
260: the names of the raw index files to be sorted as arguments. You do
261: not have to run `texindex' on all of them; only the ones you are
262: going to print. (*Note Printing Hardcopy::, for more information.)
263:
264:
265:
266: File: texinfo, Node: Structuring, Next: Quotations and Examples, Prev: Ending a File, Up: Top
267:
268: Node and Chapter Structuring
269: ****************************
270:
271: The chapter structuring commands divide a document into a hierarchy
272: of chapters, sections, subsections and subsubsections. These
273: commands generate large headings.
274:
275: In a printed manual, the table of contents is based on the
276: information specified by the chapter structuring commands.
277:
278: Although the chapter structuring commands used for creating a printed
279: document are entirely different from the node commands for
280: structuring an Info file, you are likely to use the two kinds of
281: command together since the single Texinfo file is usually designed to
282: be read both as an Info file and as a printed manual. The only time
283: you are likely to use the chapter structuring commands without using
284: the node structuring commands is if you are writing a document that
285: will never be put into Info format, for example, a novel, a letter,
286: an article or a memorandum.
287:
288: It is unlikely that you will ever write a Texinfo file that is only
289: intended as an on-line Info file and not as a printable document.
290: However, Texinfo is flexible enough so that you can do this if you
291: wish.
292:
293: Although a Texinfo file can be structured in a variety of ways, it is
294: usually structured like a book with chapters, sections, subsections
295: and the like. This structure can also be visualized as a tree (or
296: rather as an upside down tree) with the root at the top and each
297: level corresponding to chapters or sections or whatnot. In Info
298: format, you reach the nodes on each level by using the the `Next' and
299: `Previous' pointers in the node line. For example, you go from one
300: chapter to the next or previous chapter by using the the pointers to
301: the next and previous chapters. In Info, you go the level above by
302: using an `Up' pointer and you go to the level below through a `Menu'.
303: In the printed manual, cross references are indicated by page and
304: section numbers; in the on-line file, cross references are specified
305: by inline menu items.
306:
307: Here is a diagram that shows a Texinfo file with three chapters;
308: each chapter has two sections.
309:
310: top
311: |
312: |
313: --------------------------------------------
314: | | |
315: | | |
316: Chapter 1 Chapter 2 Chapter 3
317: | | |
318: | | |
319: --------- --------- ---------
320: | | | | | |
321: Sect. 1.1 Sect. 1.2 Sect. 2.1 Sect. 2.2 Sect. 3.1 Sect. 3.2
322:
323:
324: In this structure, the node for Chapter 2 looks like this:
325:
326: @node Chapter 2, Chapter 3, Chapter 1, top
327: @comment node-name, next, previous, up
328:
329: To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2
330: that says:
331:
332: @menu
333: * Sect. 2.1:: Description of this section.
334: * Sect. 2.2::
335: @end menu
336:
337: This menu is located inside Chapter 2, after the beginning of the
338: chapter, just before Section 2.1.
339:
340: Note that a menu entry has three parts: the menu item name, the name
341: of the node and, optionally, a description of the item (in that
342: order). If the menu item name and the name of the node are the same,
343: you can put two colons after the item name, as is shown in the
344: example. (If the second part is different from the first, the first
345: part is terminated by a colon and the second part terminated by a
346: tab, newline, comma or period.) (*Note Menu::.)
347:
348: The node for Sect. 2.1 will look like this:
349:
350: @node Sect. 2.1, Sect. 2.2, , Chapter 2
351: @comment node-name, next, previous, up
352:
353: This node does not have a `Previous' node.
354:
355: Usually, an `@node' command and a chapter structuring command are
356: used in sequence, along with indexing commands. For example, the
357: node for the chapter on ending a file looks like this:
358:
359: @node Ending a File, Structuring, Beginning a File, Top
360: @comment node-name, next, previous, up
361: @chapter Ending a Texinfo File
362: @cindex Ending a Texinfo file
363: @cindex Texinfo file ending
364: @cindex File ending
365:
366: The chapter structuring commands fall into four groups that have the
367: characteristics of chapters, sections, subsections and subsubsections.
368: The groups are:
369:
370: `@chapter'
371: `@unnumbered'
372: `@appendix'
373: For chapters and chapter-like parts of a document.
374:
375: `@section'
376: `@unnumberedsec'
377: `@appendixsec'
378: For sections and section-like parts of a document.
379:
380: `@subsection'
381: `@unnumberedsubsec'
382: `@appendixsubsec'
383: For subsections and subsection-like parts of a document.
384:
385: `@subsubsection'
386: `@unnumberedsubsubsec'
387: `@appendixsubsubsec'
388: For subsubsections and subsubsection-like parts of a document.
389:
390: In the sections that follow, the chapter structuring commands are
391: described first and then the `@node' and `@menu' commands.
392:
393: * Menu:
394:
395: * Chapter::
396: * Unnumbered and Appendix::
397: * Section::
398: * Subsection::
399: * Subsubsection::
400: * Node::
401: * Menu::
402:
403:
404:
405: File: texinfo, Node: Chapter, Next: Unnumbered and Appendix, Up: Structuring
406:
407: @chapter
408: ========
409:
410: `@chapter' identifies a chapter in the document. It is followed by a
411: single argument which is the rest of the line, as in
412:
413: @chapter Node and Chapter Structuring
414:
415: In TeX, it creates a chapter in the document, specifying the chapter
416: title.
417:
418: In the Info file, `@chapter' causes its argument to appear on a line
419: by itself, with a line of asterisks inserted underneath. Thus, the
420: above example produces the following output:
421:
422: Node and Chapter Structuring
423: ****************************
424:
425:
426:
427: File: texinfo, Node: Unnumbered and Appendix, Next: Section, Prev: Chapter, Up: Structuring
428:
429: @unnumbered, @appendix
430: ======================
431:
432: These commands are equivalent to `@chapter' for Info file output.
433: (*Note Chapter::.) In a printed manual, they generate chapters that
434: are numbered differently in the table of contents. `@unnumbered'
435: chapters appear without chapter numbers of any kind, and `@appendix'
436: chapters are given a letter instead of a number.
437:
438:
439:
440: File: texinfo, Node: Section, Next: Subsection, Prev: Unnumbered and Appendix, Up: Structuring
441:
442: @section
443: ========
444:
445: `@section' is like `@chapter' except that in TeX it makes a section
446: rather than a chapter. (*Note Chapter::.) Sections go within
447: chapters. In the Info file, `@chapter' and `@section' differ only in
448: that `@section' underlines with `='. For example,
449:
450: This is a section
451: =================
452:
453: @unnumberedsec, @appendixsec
454: ============================
455:
456: Use these constructs for sections within chapters made by
457: `@unnumbered' or `@appendix'. (*Note Section::.)
458:
459:
460:
461: File: texinfo, Node: Subsection, Next: Subsubsection, Prev: Section, Up: Structuring
462:
463: @subsection
464: ===========
465:
466: Subsections are to sections as sections are to chapters. (*Note
467: Section::.) They are underlined with `-'. For example,
468:
469: This is a subsection
470: -------------------
471:
472: @unnumberedsubsec, @appendixsubsec
473: ==================================
474:
475: Use these constructs for subsections within sections within chapters
476: made by `@unnumberedsec' or `@appendixsec'. (*Note Subsection::.)
477:
478:
479:
480: File: texinfo, Node: Subsubsection, Next: Node, Prev: Subsection, Up: Structuring
481:
482: @subsubsection, @unnumberedsubsubsec, @appendixsubsubsec
483: ========================================================
484:
485: Subsubsections are to subsections as subsections are to sections.
486: (*Note Subsection::.) They are underlined with periods. The
487: equivalent commands for `@unnumberedsubsec' and `@appendixsubsec' are
488: `@unnumberedsubsubsec' and `@appendixsubsubsec'. For example,
489:
490: This is a subsubsection
491: .......................
492:
493:
494:
495: File: texinfo, Node: Node, Next: Menu, Prev: Subsubsection, Up: Structuring
496:
497: @node
498: =====
499:
500: `@node' defines the beginning of a new node in the Info output file
501: (*note info: (info)Top.). It is followed by four arguments,
502: separated by commas, that make up the rest of the line. Since it is
503: often hard to remember the order in which are arguments are listed,
504: `texinfo-mode' provides the `C-c C-c n' command
505: (`texinfo-insert-@node') which automatically inserts a comment line
506: listing the arguments. For example,
507:
508: @node Texinfo Mode, Beginning a File, Overview, Top
509: @comment node-name, next, previous, up
510:
511: defines a node named `Texinfo Mode', whose `Next' pointer is to node
512: `Beginning a File', whose `Previous' pointer is to node `Overview',
513: and whose `Up' pointer is to node `Top'. What this means is that
514: Texinfo changes `@node ARGS' into the special text string necessary
515: to separate Info nodes and to identify the node that is starting and
516: say what nodes it points to.
517:
518: The pointer names should be the names of nodes defined elsewhere.
519: For this example, nodes named `Beginning a File', `Overview' and
520: `Top' should be defined elsewhere in the file with other `@node'
521: commands. It does not matter whether they are before or after the
522: node that refers to them.
523:
524: Normally, a node's `Up' pointer should point at the node whose menu
525: mentions that node. The node's `Next' pointer should point at the
526: node that follows that node and its `Previous' pointer should point
527: at the node that precedes it in that menu.
528:
529: In TeX, `@node' is nearly ignored. It generates no text. Its only
530: function is to identify the name to use for cross-references to the
531: chapter or section which follows the `@node' command and which which
532: makes up the body of the node. (Cross references are made with
533: `@xref'. *Note Cross References::.)
534:
535: `@node' should be followed immediately by a chapter-structuring
536: command such as `@chapter', `@section', `@subsection' or
537: `@subsubsection'.
538:
539: The easiest way to write a node is to use the Texinfo mode keyboard
540: command `C-c C-c n' to insert `@node' and a comment line listing the
541: names of each of the pointers in their proper order. This way you
542: won't lose track of which arguments are for which pointers. The
543: template is especially useful if you are not familiar with Texinfo.
544: It is important to pick a suitable node name. Generally, these begin
545: with an uppercase letter as if the node name were a heading for a
546: chapter or section. Do not use any of the Texinfo @-commands in the
547: name; these commands confuse Info. The node name should be
548: informative. Unfortunately, long names will not fit onto the line,
549: which can be awkward. Sometimes it is better to use long but
550: informative names rather than short ones.
551:
552: Some people insert the names of the `Next', `Previous' and `Up'
553: pointers at the same time they insert the node's own name. This is
554: because it is easier to keep track of the node structure as you
555: create a document than it is to sort it out after you have dozens of
556: nodes. Others wait to insert the `Next', `Previous' and `Up'
557: pointers until they have a nearly final version of the document.
558: This is because they expect to change the organization of the
559: document while they write it and insert or delete sections and move
560: them around. The command `texinfo-show-structure' can be used to
561: find the `Next', `Previous' and `Up' pointers of a node. (See *Note
562: Using texinfo-show-structure::.)
563:
564: However you do it, it is best to name the node whenever you write the
565: section so you can easily make cross references to the section. A
566: large number of cross references are an especially important feature
567: of a good Info file.
568:
569: After you have inserted the node-line, you should immediately write
570: an @-command for the chapter or section and insert its name. Next,
571: (and this is important!), put in several index entries. Usually, you
572: will find at least two and often as many as four or five ways of
573: referring to the node in the index. Use them all. This will make it
574: much easier for people to find the node.
575:
576: The top node of the file, named `Top', should have as its parent the
577: name of a node in another file, where there is a menu that leads to
578: this file. Specify the file name in parentheses. If the file is to
579: be installed directly in the Info directory file, use `(dir)' as the
580: parent of the top node; this is short for `(dir)top', the node `top'
581: in the file `dir', which is the main menu of Info. For example,
582:
583: @node Top, Overview, (dir), (dir)
584: @comment node-name, next, previous, up
585:
586: For more information about installing an Info file in the `info'
587: directory, *note Installing an Info File::.
588:
589:
590:
591: File: texinfo, Node: Menu, Prev: Node, Up: Structuring
592:
593: @menu
594: =====
595:
596: Info file nodes can contain "menus" which point to other nodes. You
597: must type the menus in by hand, and surround them with lines
598: containing `@menu' and `@end menu'. In Info, the `@menu' line
599: changes into `* Menu:', which indicates the beginning of a menu to
600: the Info program. Otherwise, the contents are unchanged by Texinfo,
601: except for the processing of any other @-commands within. The entire
602: menu construct has no effect in the printed manual and will not
603: appear there.
604:
605: By convention, a menu is put at the end of a node. This way, it is
606: easy for someone using Info to find the menu, using the `M->'
607: (`end-of-buffer') command.
608:
609: In a menu, every line that begins with a `*' lists a single topic. A
610: line that does not start with a `*' will also appear in the menu and
611: can be used as a comment.
612:
613: A menu item has three parts:
614:
615: 1. The menu item name.
616:
617: 2. The name of the node.
618:
619: 3. A description of the item.
620:
621: Only the first part is required. This part is the name of the
622: topic--the name of the menu item that the user must give to the `m'
623: command to select this topic when using Info. The first part comes
624: right after the asterisk and a space, and is followed by a colon,
625: spaces and tabs, and then the name of the node which discusses that
626: topic. The name of the node is terminated by a tab, comma, newline
627: or period. If the node name and topic name are the same, rather than
628: give the name twice, put two colons after the name instead. For
629: example, `* Name::'. (You should do this whenever possible, since it
630: reduces visual clutter in the menu).
631:
632: If the second part is present, it may be terminated with a tab,
633: comma, or newline; or with a period.
634:
635: For example,
636:
637: @menu
638: A Section on Foo and Switches
639: * Foo:: The node named Foo tells you how to go fooing.
640: * Sw: Switches. Type @code{m Sw} to see node @code{Switches}
641: which describes the switches available here.
642: @end menu
643:
644: produces
645:
646: * menu:
647:
648: A Section on Foo and Switches
649: * Foo:: The node named foo tells you how to go fooing.
650: * Sw: Switches. Type `m Sw' to see node `Switches'
651: which describes the switches available here.
652:
653: In this example, the menu has two items. `Foo' is both a menu item
654: name and the name of the node referred to by that item. `Sw' is the
655: other menu item name, and it refers to the node named `Switches'.
656: Since no file name is specified with `Foo' or `Switches', they must
657: be the names of other nodes in the same Info file.
658:
659: Nodes in other Info files can be referred to by putting the file name
660: in parentheses at the beginning of the node name. For example,
661:
662: @menu
663: * Outlining: (emacs) Outline Mode. The major mode for editing outlines.
664: * Rebinding: (emacs) Rebinding. How to redefine the meaning of a key.
665: @end menu
666:
667: When this is done, the item has to have at least two parts: the first
668: part is the menu item name and the second part is the name of the node.
669:
670:
671:
672: File: texinfo, Node: Quotations and Examples, Next: Lists and Tables, Prev: Structuring, Up: Top
673:
674: Making Quotations and Examples
675: ******************************
676:
677: Quotations and examples are blocks of text, consisting of one or more
678: whole paragraphs that are set off from the bulk of the text and
679: treated differently. They are usually indented.
680:
681: In Texinfo, an insertion is always begun by writing an @-command on a
682: line by itself, and ended by writing an `@end' command that is also
683: on a line by itself. For instance, an "example" is a kind of
684: insertion that is begun with `@example' and ended with `@end example'.
685:
686: There are three commands for quotations and examples:
687:
688: `@quotation'
689: Used to indicated text that is quoted.
690:
691: `@example'
692: Used to illustrate code, commands and the like in a fixed width
693: font without filling.
694:
695: `@display'
696: Used for illustrative text.
697:
698: * Menu:
699:
700: * Quotation::
701: * Example::
702: * Display::
703:
704:
705:
706: File: texinfo, Node: Quotation, Next: Example, Up: Quotations and Examples
707:
708: @quotation
709: ==========
710:
711: `@quotation' is used to indicate text that is excerpted from another
712: (real or hypothetical) printed work. The inside of a quotation is
713: processed normally except that
714:
715: 1. The margins are narrower.
716:
717: 2. Paragraphs are not indented.
718:
719: 3. Interline spacing and interparagraph spacing are reduced.
720:
721: Thus, the input
722:
723: @quotation
724: This is
725: a foo.
726: @end quotation
727:
728: produces in the printed manual
729:
730: This is a foo.
731:
732: and in the Info file
733:
734: This is
735: a foo.
736:
737:
738:
739: File: texinfo, Node: Example, Next: Display, Prev: Quotation, Up: Quotations and Examples
740:
741: @example
742: ========
743:
744: `@example' is used to indicate an example that is not part of the
745: running text. In the printed manual, this is done by switching to a
746: fixed width font, turning off filling, and making extra spaces and
747: blank lines significant. In the Info file, an analogous result is
748: obtained by indenting each line with five extra spaces.
749:
750: `@example' should appear on a line by itself; this line will
751: disappear from the output. Mark the end of the example with a line
752: containing `@end example', which will likewise disappear. For example:
753:
754: @example
755: mv foo bar
756: @end example
757:
758: produces
759:
760: mv foo bar
761:
762: Since the lines containing `@example' and `@end example' will
763: disappear, you will want to put a blank line before the `@example'
764: and another blank line after the `@end example'. (Remember that
765: blank lines between the beginning `@example' and the ending `@end
766: example' will appear in the output.)
767:
768: Don't use tabs in lines of an example! TeX has trouble with tabs:
769: it treats them like single spaces, and that is not what they look like.
770:
771:
772:
773: File: texinfo, Node: Display, Prev: Example, Up: Quotations and Examples
774:
775: @display
776: ========
777:
778: `@display' is just like `@example' except that, in the printed
779: manual, `@display' does not select the fixed-width font. In fact, it
780: does not specify the font at all, so that the text appears in the
781: same font it would have appeared in without the `@display'.
782:
783:
784:
785: File: texinfo, Node: Lists and Tables, Next: Cross References, Prev: Quotations and Examples, Up: Top
786:
787: Making Lists and Tables
788: ***********************
789:
790: Texinfo has several ways of making lists and two-column tables.
791: Lists can be bulleted or numbered while two-column tables can
792: highlight the items in the first column.
793:
794: For example, this is an enumerated list:
795:
796: 1. This is a numbered item.
797:
798: 2. This is the second item in this list.
799:
800: 3. This is the third item on this list.
801:
802: Texinfo will automatically indent the text in lists or tables and
803: number an enumerated list. This last feature is useful if you are
804: reordering the list, since you do not have to renumber it yourself.
805:
806: Lists or tables are always begun by an @-command on a line by itself
807: and ended with an `@end' command on a line by itself. For example,
808: an enumerated list begins with the command `@enumerate' and ends with
809: the command `@end enumerate'; and an itemized list begins with the
810: command `@itemize' and ends with the command `@end itemize'.
811:
812: The elements of a list are begun with the `@item' command.
813:
814: Here is an itemized list of the different kinds of table and lists:
815:
816: * Itemized lists with or without bullets.
817:
818: * Numbered lists.
819:
820: * two-column tables with highlighting.
821:
822: * Menu:
823:
824: * Itemize::
825: * Enumerate::
826: * Table::
827:
828:
829:
830: File: texinfo, Node: Itemize, Next: Enumerate, Up: Lists and Tables
831:
832: @itemize
833: ========
834:
835: `@itemize' is used to produce sequences of indented paragraphs, with
836: a mark inside the left margin at the beginning of each paragraph.
837: The rest of the line that starts with `@itemize' should contain the
838: character or Texinfo commands to generate such a mark. Usually, it
839: is the @-command `@bullet'. Whatever mark you choose, ultimately, it
840: should result in a single character in the Texinfo file, or the
841: indentation will come out wrong. When you write the command, omit
842: the `{}' after the command if you use just one command and nothing
843: else.
844:
845: The text of the indented paragraphs themselves come after the
846: `@itemize', up to another line that says `@end itemize'.
847:
848: Before each paragraph for which a mark in the margin is desired,
849: place a line that says just `@item'. Don't put any other text on
850: this line.
851:
852: Info indents the lines in an itemized list by five columns, but it
853: does not fill them. This can produce lines in the Info file that are
854: too wide. You can either write shorter lines in the Texinfo file by
855: setting the fill column to five columns less than it is normally, or
856: else you can tell Info to refill the paragraphs by adding the
857: @-command `@refill' to the end of the paragraph. (*Note Refill::, for
858: more information about the use of the `@refill' command.)
859:
860: Usually, you should put a blank line before an `@item'. This puts a
861: blank like in the Info file. Except when the entries are very brief,
862: a blank line looks better.
863:
864: Here is an example of the use of `@itemize', followed by the output
865: it produces. Note that `@bullet' produces a `*' in Texinfo and a
866: round dot in TeX.
867:
868: @itemize @bullet
869: @item
870: Some text for foo.
871:
872: @item
873: Some text
874: for bar.
875: @end itemize
876:
877: produces
878:
879: * Some text for foo.
880:
881: * Some text for bar.
882:
883:
884:
885: File: texinfo, Node: Enumerate, Next: Table, Prev: Itemize, Up: Lists and Tables
886:
887: @enumerate
888: ==========
889:
890: `@enumerate' is like `@itemize' except that the marks in the left
891: margin contain successive integers starting with 1. (*Note
892: Itemize::.) Do not put any argument on the same line as `@enumerate'.
893:
894: @enumerate
895: @item
896: Some text for foo.
897: @item
898: Some text
899: for bar.
900: @end enumerate
901:
902: produces
903:
904: 1. Some text for foo.
905:
906: 2. Some text for bar.
907:
908: If you want, you can put a blank line between the entries in the list.
909: This often makes it easier to read the Info file. For example,
910:
911: @enumerate
912: @item
913: This is the first item.
914:
915: @item
916: This is the second item.
917: @end enumerate
918:
919: Info indents the lines of the enumerated list by five columns, but it
920: does not fill them. As a result, the lines in the Info file may be
921: too wide. To prevent this, you can either write shorter lines in the
922: Texinfo file file by setting the fill column to five columns less
923: than it is normally, or else you can tell Info to refill the
924: paragraphs by adding the @-command `@refill' to the end of the
925: paragraph. (*Note Refill::, for more information about the use of
926: the `@refill' command.)
927:
928:
929:
930: File: texinfo, Node: Table, Prev: Enumerate, Up: Lists and Tables
931:
932: @table
933: ======
934:
935: `@table' is similar to `@itemize', but allows you to specify a name
936: or heading line for each item. (*Note Itemize::.) The command is
937: used to produce two-column tables, and is especially useful for
938: glossaries and explanatory exhibits.
939:
940: You must follow each use of `@item' inside of `@table' with text to
941: serve as the heading line for that item. This text is put on the
942: same line as the `@item' command. Each heading line is put into the
943: first column of the table and the supporting text, which you put on
944: the line following the line beginning with `@item', goes into the
945: second column.
946:
947: Also, `@table' itself must be followed by an argument that is a
948: Texinfo command such as `@code', `@var', `@kbd' or `@asis'. Although
949: these commands are usually followed by arguments in braces, in this
950: case you use the command name without an argument. (`@item' supplies
951: the argument.) This command will be applied to the text that goes
952: into the first column of each item and determines how it will be
953: highlighted. For example, `@samp' will cause the text in the first
954: column to be highlighted as if it were acted on by an `@samp' command.
955:
956: `@asis' is a command that does nothing; in that case, each item will
957: come out without highlighting, unless that particular piece of text
958: contains @-commands for highlighting.
959:
960: (Various other command names might work with `@table'. However, only
961: commands that normally take arguments in braces may be used.)
962:
963: Usually, you should put a blank line before an `@item'. This puts a
964: blank like in the Info file. Except when the entries are very brief,
965: a blank line looks better.
966:
967: The following table, for example, highlights the text in the first
968: column as if each item were acted on by an `@samp' command:
969:
970: @table @samp
971: @item foo
972: This is the text for
973: @samp{foo}.
974:
975: @item bar
976: Text for @samp{bar}.
977: @end table
978:
979: produces
980:
981: `foo'
982: This is the text for `foo'.
983:
984: `bar'
985: Text for `bar'.
986:
987: Info indents the lines of text in the second column, but does not
988: fill them. As a result, the lines in the Info file may be too wide.
989: To prevent this, cause Info to refill the paragraphs after processing
990: by adding the @-command `@refill' to the end of the paragraph. (*Note
991: Refill::, for more information about the use of the `@refill' command.)
992:
993: If you want to list two or more named items with a single block of
994: text, use the `@itemx' command.
995:
996: * Menu:
997:
998: * Itemx::
999:
1000:
1001:
1002: File: texinfo, Node: Itemx, Prev: Table, Up: Table
1003:
1004: @itemx
1005: ------
1006:
1007: `@itemx' is used inside a `@table' when you have two or more named
1008: items for the same block of text. Use `@itemx' for all but the first
1009: of the items. It works exactly like `@item' except that it does not
1010: generate extra vertical space above the item text. For example,
1011:
1012: @table @code
1013: @item upcase
1014: @itemx downcase
1015: These two functions accept a character or a string as argument,
1016: and return the corresponding upper case (lower case) character
1017: or string. @refill
1018: @end table
1019:
1020: produces
1021:
1022: `upcase'
1023: `downcase'
1024: These two functions accept a character or a string as
1025: argument, and return the corresponding upper case (lower
1026: case) character or string.
1027:
1028: A more complicated example of the use of `@itemx' comes from the
1029: chapter on structuring commands. Here is how the list showing how
1030: the chapter structuring commands fall into four groups was constructed.
1031: (*Note Chapter Structuring Commands: Structuring.)
1032:
1033: @table @code
1034: @item @@chapter
1035: @itemx @@unnumbered
1036: @itemx @@appendix
1037: For chapters and chapter-like parts of a document.
1038:
1039: @item @@section
1040: @itemx @@unnumberedsec
1041: @itemx @@appendixsec
1042: For sections and section-like parts of a document.
1043:
1044: @item @@subsection
1045: @itemx @@unnumberedsubsec
1046: @itemx @@appendixsubsec
1047: For subsections and subsection-like parts of a document.
1048:
1049: @item @@subsubsection
1050: @itemx @@unnumberedsubsubsec
1051: @itemx @@appendixsubsubsec
1052: For subsubsections and similar parts of a document.
1053: @end table
1054:
1055: and this is what the resulting table looks like:
1056:
1057: `@chapter'
1058: `@unnumbered'
1059: `@appendix'
1060: For chapters and chapter-like parts of a document.
1061:
1062: `@section'
1063: `@unnumberedsec'
1064: `@appendixsec'
1065: For sections and section-like parts of a document.
1066:
1067: `@subsection'
1068: `@unnumberedsubsec'
1069: `@appendixsubsec'
1070: For subsections and subsection-like parts of a document.
1071:
1072: `@subsubsection'
1073: `@unnumberedsubsubsec'
1074: `@appendixsubsubsec'
1075: For subsubsections and similar parts of a document.
1076:
1077: Also, either column of a table can be empty.
1078:
1079:
1080:
1081: File: texinfo, Node: Cross References, Next: Formatting Paragraphs, Prev: Lists and Tables, Up: Top
1082:
1083: Making Cross References
1084: ***********************
1085:
1086: Cross references are used to refer the reader to other parts of the
1087: same or different Texinfo files. In Texinfo, "nodes" are the points
1088: to which cross-references can refer.
1089:
1090: In general, a document should be designed so that it can be read
1091: sequentially. People soon tire of flipping back and forth to find
1092: information that should be presented to them as they need it.
1093: However, there will be information (often too detailed for whatever
1094: the current context may be) that is related to whatever is presented
1095: and to which reference should be made. More important, in an on-line
1096: help system or in a reference manual, readers do *not* read
1097: everything in sequence from beginning to end. Instead, they look up
1098: what they need. For this reason, such creations should contain many
1099: cross references to help the reader find other information that he or
1100: she may not have read.
1101:
1102: Although nodes are not a fundamental concept in a printed manual,
1103: they still serve to define a cross-reference point and the variants
1104: of `@xref' still serve to make references. Thus, if you are writing
1105: a manual that will only be printed, and will not be used on-line, you
1106: continue to use the `@node' command for when you make cross references.
1107:
1108: There are several kinds of cross reference command.
1109:
1110: `@xref'
1111: Used to start a sentence in the printed manual saying, `See ...'
1112: or an entry in the Info file saying `*note ...'.
1113:
1114: `@pxref'
1115: Used to make a reference that starts with a lowercase `see'
1116: and is usually contained within parentheses.
1117:
1118: `@inforef'
1119: Used to make a reference to an Info file for which there is no
1120: printed manual.
1121:
1122: * Menu:
1123:
1124: * Xref::
1125: * Pxref::
1126: * Inforef::
1127:
1128:
1129:
1130: File: texinfo, Node: Xref, Next: Pxref, Prev: Cross References, Up: Cross References
1131:
1132: @xref
1133: =====
1134:
1135: `@xref' generates a cross-reference. In Texinfo, it turns into an
1136: Info cross-reference which the Info `f' command can use to go
1137: directly to another node. In TeX, it turns into a sentence of the form
1138:
1139: See section SECTION [TOPIC], page PAGE
1140:
1141: but does not generate a period to end it.
1142:
1143: `@xref' must refer to an Info node created by `@node', by the node's
1144: name.
1145:
1146: `@xref' is followed by an argument inside braces; but actually the
1147: text inside the braces is treated as several arguments, separated by
1148: commas. Whitespace after these commas is ignored. A period or comma
1149: *must* follow the closing brace of an `@xref'. It is required to
1150: terminate the cross reference. This period or comma will appear in
1151: the output, both in the Info file and in the printed manual.
1152:
1153: The simplest form of `@xref' takes one argument, the name of another
1154: node in the same Info file. Here we show the input text, followed by
1155: a blank line and then the output text for Info files and the output
1156: text for printed manuals.
1157:
1158: @xref{node-name}, for more info.
1159:
1160: *note node-name::, for more info.
1161:
1162: See section NNN [node-name], page PPP, for more info.
1163:
1164: With two arguments, the second one is used as the name of the Info
1165: cross-reference, while the first argument is still the node that the
1166: cross-reference points to:
1167:
1168: @xref{node-name, name-for-note}, for more info.
1169:
1170: *note name-for-note: node-name, for more info.
1171:
1172: See section NNN [node-name], page PPP, for more info.
1173:
1174: A third argument replaces the node name when it actually appears in
1175: the TeX output. It should state the topic discussed by the section
1176: being referenced. Often, you will want to use initial uppercase
1177: letters so it will be easier to read when the reference is printed.
1178: Use a third argument when the node name is unsuitable because of
1179: syntax, grammar or diction.
1180:
1181: @xref{node-name, name-for-note, Topic Description}, for more info.
1182:
1183: *note name-for-note: node-name, for more info.
1184:
1185: See section NNN [Topic Description], page PPP, for more info.
1186:
1187: If a third argument is given and the second one is empty, then the
1188: third argument serves both purposes:
1189:
1190: @xref{node-name, , Topic Description}, for more info.
1191:
1192: *note Topic Description: node-name, for more info.
1193:
1194: See section NNN [Topic Description], page PPP, for more info.
1195:
1196: A fourth argument specifies the name of the Info file in which the
1197: referenced node is located, assuming it is not the one in which the
1198: reference appears. `@xref' with only four arguments is used when the
1199: reference is not within one Info file, but is within a single printed
1200: manual--when multiple Texinfo files are incorporated into the same
1201: TeX run but make separate Info files. (This is seldom the case and
1202: usually you will use five arguments if you are making a reference
1203: that is outside the current Info file.)
1204:
1205: @xref{node-name, name-for-note, Topic, info-file-name},
1206: for more info.
1207:
1208: *note name-for-note: (info-file-name) node-name, for more info.
1209:
1210: See section NNN [Topic], page PPP, for more info.
1211:
1212: A fifth argument is used when you are making a reference to another
1213: Info file which is also part of another printed manual. Write the
1214: title of the manual in this slot. Since a different manual is made
1215: during a different TeX run, the printed reference will not have a
1216: page number.
1217:
1218: Whenever you refer to another manual, use this version of `@xref'
1219: with five arguments.
1220:
1221: @xref{node-name, name-for-note, Topic, info-file-name, A Printed Manual},
1222: for more info.
1223:
1224: *note name-for-note: (info-file-name) node-name, for more info.
1225:
1226: See section Topic of A Printed Manual, for more info.
1227:
1228: The name of the printed manual will be typeset in italics.
1229:
1230: Often, you will leave out the second argument when you use the long
1231: version of `@xref'. In this case, the third argument, the topic
1232: description, will replace the node name:
1233:
1234: @xref{node-name, , Topic Description, info-file-name, A Printed Manual},
1235: for more info.
1236:
1237: *note Topic Description: (info-file-name) node-name, for more info.
1238:
1239: See section Topic Description of A Printed Manual, for more info.
1240:
1241:
1242:
1243: File: texinfo, Node: Pxref, Next: Inforef, Prev: Xref, Up: Cross References
1244:
1245: @pxref
1246: ======
1247:
1248: `@pxref' is nearly the same as `@xref'; it differs in only two ways:
1249:
1250: 1. The output starts with lower case `see' rather than `See'.
1251:
1252: 2. A period is generated automatically in the Info file output to
1253: end the Info cross-reference, but no period is generated for the
1254: printed manual.
1255:
1256: The purpose of `@pxref' is to be used inside parentheses as part of
1257: another sentence. In the printed manual, no period is needed after
1258: the cross reference text itself (within the parentheses), but a
1259: period is needed after the cross reference text in the Info file
1260: because only thus can Info recognize the end of the cross-reference.
1261: `@pxref' spares you the need to use complicated methods to put a
1262: period into one form of the output and not the other.
1263:
1264: `@pxref' can be used with up to five arguments just like `@xref'.
1265: (*Note Xref::.)
1266:
1267:
1268:
1269: File: texinfo, Node: Inforef, Prev: Pxref, Up: Cross References
1270:
1271: @inforef
1272: ========
1273:
1274: `@inforef' is used for cross-references to Info files for which there
1275: are no printed manuals. Even in a printed manual, `@inforef'
1276: generates a reference directing the user to look in an Info file.
1277: `@inforef' takes exactly three arguments. The syntax is
1278: `@inforef{NODE, NAME, FILE}'.
1279:
1280: @inforef{node-name, name-for-note, info-file-name}, for more information.
1281:
1282: *note name-for-note: (info-file-name) node-name, for more information.
1283:
1284: See Info file `info-file-name', node `node-name', for more
1285: information.
1286:
1287:
1288:
1289: File: texinfo, Node: Formatting Paragraphs, Next: Marking Text, Prev: Cross References, Up: Top
1290:
1291: Formatting Paragraphs
1292: *********************
1293:
1294: Usually, a Texinfo file will be processed both by TeX and by the `M-x
1295: texinfo-format-buffer' command. Consequently, you must make sure
1296: that text will come out looking right both in the printed manual and
1297: in the on-line help.
1298:
1299: For example, unless told otherwise, `M-x texinfo-format-buffer' will
1300: not refill a paragraph after processing it although TeX will. This
1301: means that a paragraph with numerous or large @-commands may not look
1302: properly filled after processing by Info. The @-commands are removed
1303: from the text but the lines are not refilled so some are much shorter
1304: than they were. To cause the `M-x texinfo-format-buffer' command to
1305: refill such a paragraph, put `@refill' at the end of the paragraph.
1306:
1307: TeX may also format a document improperly. For example, page breaks
1308: may occur in the ``wrong place''; to control this, text can be held
1309: together by a group command that keeps the text within the group from
1310: being split across two pages.
1311:
1312: * Menu:
1313:
1314: * Refilling & Noindent:: Refilling paragraphs & preventing indentation
1315: * Breaks Blank-Lines Groups:: Line and paragraph breaks, blank lines, grouping
1316:
1317:
1318:
1319: File: texinfo, Node: Refilling & Noindent, Next: Breaks Blank-Lines Groups, Prev: Formatting Paragraphs, Up: Formatting Paragraphs
1320:
1321: Refilling Paragraphs and Preventing Indentation
1322: ===============================================
1323:
1324: The `@refill' and `@noindent' commands are used just after or just
1325: before paragraphs which, after processing by either Info or TeX,
1326: might look bad. The `@refill' command refills a paragraph in the
1327: Info file after all the other processing has been done. In the
1328: printed manual, the `@noindent' command prevents a piece of text that
1329: is a continuation of the preceding paragraph from being indented as
1330: if it were a new paragraph.
1331:
1332: * Menu:
1333:
1334: * Refill:: Refilling an info paragraph after other processing.
1335: * Noindent:: Preventing paragraph indentation in continuation text.
1336:
1337:
1338:
1339: File: texinfo, Node: Refill, Next: Noindent, Prev: Refilling & Noindent, Up: Refilling & Noindent
1340:
1341: @refill
1342: -------
1343:
1344: If a paragraph contains sizable @-constructs, it may look badly
1345: filled after `texinfo-format-buffer' is through with it.
1346:
1347: Put `@refill' at the end of the paragraph to tell
1348: `texinfo-format-buffer' to refill the paragraph after finishing all
1349: other processing on it. `@refill' has no effect on TeX, which always
1350: fills everything that ought to be filled. For example,
1351:
1352: To use @code{foo}, pass @samp{xx%$} and @var{flag} and type @kbd{x}
1353: after running @code{make-foo}.@refill
1354:
1355: produces (in the Info file)
1356:
1357: To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
1358:
1359: whereas without the `@refill' it would produce
1360:
1361: To use `foo', pass `xx%$' and FLAG and type `x'
1362: after running `make-foo'.
1363:
1364: with the line broken at the same place as in the Texinfo input file.
1365:
1366: Do not put a space before `@refill'; otherwise the command might be
1367: put at the beginning of the line when you refill the paragraph in the
1368: Texinfo file with `M-q' (`fill-paragraph'). If this were to happen,
1369: the `@refill' command might fail to work
1370:
1371:
1372:
1373: File: texinfo, Node: Noindent, Prev: Refill, Up: Refilling & Noindent
1374:
1375: @noindent
1376: ---------
1377:
1378: If you have text following an `@example' or other similar ``special
1379: paragraph'' that reads as a continuation of the text before the
1380: `@example', it is good to prevent this text from being indented as a
1381: new paragraph. To accomplish this, put `@noindent' on a line by
1382: itself before the start of the text that should not be indented. For
1383: example,
1384:
1385: @example
1386: This is an example
1387: @end example
1388:
1389: @noindent
1390: This line will not be indented.
1391:
1392: produces
1393:
1394: This is an example
1395:
1396: This line will not be indented.
1397:
1398: To adjust the number of blank lines properly in the Info file output,
1399: remember that the line containing `@noindent' does not generate a
1400: blank line, and neither does the `@end example' line.
1401:
1402: In the Texinfo source file for this documentation, each of the lines
1403: that says `produces' is preceded by a line containing `@noindent'.
1404:
1405:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.