![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to texinfo-1 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-1 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: Top, Next: License, Prev: (dir), Up: (dir)
29:
30: * Menu:
31:
32: * License:: Licensing information.
33: * Overview:: What is Texinfo?
34: * Texinfo Mode:: Special features in GNU Emacs.
35: * Beginning a File:: What to put at the beginning of a Texinfo file.
36: * Ending a File:: What to put at the end of a Texinfo file.
37: * Structuring:: How to make nodes and chapters.
38: * Quotations and Examples:: How to insert quotations and examples.
39: * Lists and Tables:: How to make lists and tables.
40: * Cross References:: How to make cross references.
41: * Formatting Paragraphs:: How to format paragraphs.
42: * Marking Text:: How to mark code, definitions, variables etc.
43: * Conditionals:: Putting text in only Info or the printed work.
44: * Printing Hardcopy:: How to print a hardcopy of the manual.
45: * Creating an Info File:: How to create an on-line Info file.
46: * Catching Mistakes:: How to find problems.
47:
48: Indices, nodes containing large menus
49:
50: * Command Index:: An item for each @-command.
51: * Concept Index:: An item for each concept.
52:
53: A detailed node listing
54:
55: Overview
56: * Info File:: Characteristics of the Info file.
57: * Printed Manual:: Characteristics of the printed manual.
58: * Conventions:: General syntactic conventions.
59: * Short Sample:: A short sample Texinfo file.
60:
61: Using Texinfo Mode
62: * Info on a Region:: Formatting a region for Info.
63: * Showing the Structure:: Showing the structure of a file.
64: * Inserting:: Inserting frequently used commands.
65:
66: Beginning a Texinfo File.
67: * First Line:: The first line of a Texinfo file.
68: * Start-of-Header:: Identifying the start of the header.
69: * Setfilename:: Specifying the name of the Info file.
70: * Settitle:: Specifying the title used by the headings.
71: * Setchapternewpage:: Starting chapters on odd numbered pages.
72: * Titlepage:: The title and copyright page.
73: * Center:: Centering a line.
74: * Copyright & Printed Permissions:: Ensuring free distributability.
75: * Top Node:: The master menu.
76: * License and Distribution:: Your are free to copy and distribute this.
77:
78: Ending a Texinfo File
79: * Contents:: Generating tables of contents.
80: * Indices:: Generating indices.
81: * Index Entries:: Defining the entries of an index.
82: * Combining Indices:: Putting two or more indices together.
83: * Printing Indices & Menus:: Printing an index and generating menus.
84:
85: Node and Chapter Structuring
86: * Chapter:: Creating a chapter.
87: * Unnumbered and Appendix:: Chapter-like parts.
88: * Section:: Creating sections
89: * Subsection:: Creating subsections.
90: * Subsubsection:: Creating subsubsections.
91:
92: * Node:: Creating nodes.
93: * Menu:: Creating menus.
94:
95:
96: Making quotations and examples
97: * Quotation:: Inserting long quotations.
98: * Example:: Inserting examples of code and the like.
99: * Display:: Inserting displayed text.
100:
101: Making lists and two column tables
102: * Itemize:: Creating itemized lists.
103: * Enumerate:: Creating enumerated lists.
104: * Table:: Creating two column tables.
105: * Itemx:: Putting an extra item in the
106: first column of a table.
107:
108: Making Cross References
109: * Xref:: Making a regular cross reference.
110: * Pxref:: Making a parenthetical cross reference.
111: * Inforef:: Making a cross reference to an Info file.
112:
113:
114: Formatting Paragraphs
115: * Refilling & Noindent:: Refilling paragraphs
116: and preventing indentation
117: * Refill:: Using the `@refill' command.
118: * Noindent:: Using the `@noindent' command.
119:
120:
121: Breaks, Blank Lines and Groups
122: * Line Breaks:: Inserting line breaks in TeX.
123: * Sp:: Inserting blank lines.
124: * Br:: Inserting paragraph breaks.
125: * W:: Preventing line breaks.
126: * Page:: Starting new pages.
127: * Group:: Holding text together on one page.
128: * Need:: Keeping text together.
129:
130: Marking Text Within a Paragraph
131: * Code:: A literal example of a piece of a program.
132: * Samp:: A literal example of a sequence of characters.
133: * File:: The name of a file.
134: * Kbd:: The names of keys or else characters you type.
135: * Key:: The conventional name for a key on a keyboard.
136: * Ctrl:: Indicates the ASCII control character.
137: * Var:: A variable.
138: * Dfn:: The introductory or defining use of a term.
139: * Cite:: The name of a book.
140:
141: Inserting Braces, `@' and Periods
142: * Braces Atsigns Periods:: Inserting braces, `@' and periods.
143: * Dots Bullets Tex:: Inserting dots, bullets and the TeX logo
144: * Emphasis:: Emphasizing text.
145:
146: Emphasizing Text
147: * Emph and Strong:: Emphasizing text.
148: * Fonts:: Selecting italic, bold or typewriter fonts.
149:
150: Creating an Info File
151: * Installing an Info File:: Putting the Info file in the
152: `info' directory.
153:
154: Catching Mistakes
155: * Debugging with Info:: Catching errors with info formatting.
156: * Using the Emacs Lisp Debugger:: Using the Emacs Lisp Debugger
157: * Debugging with Tex:: Catching errors with TeX formatting.
158: * Using texinfo-show-structure:: Using `texinfo-show-structure'
159: to catch mistakes.
160: * Using Occur:: Using `occur' to catch mistakes.
161: * Running Info-Validate:: Checking for unreferenced nodes.
162:
163: Finding badly referenced nodes
164: * Info-Validating a Large File:: Running `Info-validate'
165: on a large file.
166: * Splitting:: Splitting a file manually.
167:
168: Appendices
169: * Command Syntax:: Details about the syntax.
170: * Include Files:: Making one printed file out of
171: several Info files.
172: * TeX Input:: Where TeX finds its `\input' file.
173: * Sample Permissions:: You may copy GNU Software.
174: * Ifinfo Permissions:: What to put in the `ifinfo' section.
175: * Titlepage Permissions:: What to put in the `@titlepage' section.
176:
177:
178:
179: File: texinfo, Node: License, Next: Overview, Prev: Top, Up: Top
180:
181: Licensing Information
182: *********************
183:
184: The programs currently being distributed that relate to Texinfo
185: include two portions of GNU Emacs, plus two other separate programs
186: (`texindex' and `texinfo.tex'). These programs are "free"; this
187: means that everyone is free to use them and free to redistribute them
188: on a free basis. The Texinfo related programs are not in the public
189: domain; they are copyrighted and there are restrictions on their
190: distribution, but these restrictions are designed to permit
191: everything that a good cooperating citizen would want to do. What is
192: not allowed is to try to prevent others from further sharing any
193: version of these programs that they might get from you.
194:
195: Specifically, we want to make sure that you have the right to give
196: away copies of the programs that relate to Texinfo, that you receive
197: source code or else can get it if you want it, that you can change
198: these programs or use pieces of them in new free programs, and that
199: you know you can do these things.
200:
201: To make sure that everyone has such rights, we have to forbid you to
202: deprive anyone else of these rights. For example, if you distribute
203: copies of the Texinfo related programs, you must give the recipients
204: all the rights that you have. You must make sure that they, too,
205: receive or can get the source code. And you must tell them their
206: rights.
207:
208: Also, for our own protection, we must make certain that everyone
209: finds out that there is no warranty for the programs that relate to
210: Texinfo. If these programs are modified by someone else and passed
211: on, we want their recipients to know that what they have is not what
212: we distributed, so that any problems introduced by others will not
213: reflect on our reputation.
214:
215: The precise conditions of the licenses for the programs currently
216: being distributed that relate to Texinfo are found in the General
217: Public Licenses that accompany them. The programs that are part of
218: GNU Emacs are covered by the GNU Emacs copying terms (*note :
219: (emacs)License.), and other programs are covered by licenses that are
220: contained in their source files.
221:
222:
223:
224: File: texinfo, Node: Overview, Next: Texinfo Mode, Prev: License, Up: Top
225:
226: Overview of Texinfo
227: *******************
228:
229: Texinfo is a documentation system that uses a single source file for
230: both on-line help and a printed manual. This means that instead of
231: writing two different documents, one for the on-line help and the
232: other for the printed manual, only one document needs to be written.
233: When the system is revised, only one file has to be revised.
234:
235: Using Texinfo, you can create a document with the normal features of
236: a book such as chapters, sections, cross references and indices. The
237: chapters and sections of the printed manual can be made to correspond
238: to the nodes of the on-line help. The cross references and indices
239: can be used in both the on-line help and in the printed document.
240: Indices are generated semi-automatically. The ``GNU Emacs Manual''
241: is a good example of a Texinfo file.
242:
243: To make the printed manual, the Texinfo source file is processed by
244: the TeX typesetting program; the resulting DVI file can be typeset
245: and printed as a book. To make the on-line help, the Texinfo source
246: file is by processed the `M-x texinfo-format-buffer' command; the
247: resulting Info file is installed in the `info' directory.
248:
249: Since the Texinfo source file is used for a dual task--to create both
250: the on-line help and the printed manual--it must be written in a
251: special format that uses @-commands (words preceded by an `@') to
252: indicate chapters, sections, nodes, examples, index entries and the
253: like.
254:
255: Before writing a Texinfo source file, you should be familiar with the
256: on-line Info documentation reading program. (*note info: (info)Info,
257: for more information.) If you are writing a document that will be
258: both on-line and printed, you will need both Info and TeX.
259:
260: To make an Info file, you use the `M-x texinfo-format-buffer' command
261: in GNU Emacs.
262:
263: To make a printed manual, you need to use TeX, a powerful,
264: sophisticated typesetting program written by Donald Knuth. TeX is
265: freely distributable. It is written in a dialect of Pascal called WEB
266: and can be compiled either in Pascal or (by using a conversion
267: program that comes with the TeX distribution) in C. (For information
268: about getting TeX, *note : (emacs)TeX Mode.)
269:
270: When TeX processes a Texinfo source file, TeX makes use of a macro
271: definitions file called `texinfo.tex' that comes with the GNU Emacs
272: distribution in the `emacs/man' sources directory. (The first line
273: of every Texinfo file has a command that says `\input texinfo'; this
274: tells TeX to use the `texinfo.tex' file.)
275:
276: If the `texinfo.tex' file has not already been copied to the
277: directory which contains the other TeX macro definition files when
278: Emacs was installed, you will probably want to copy it to that
279: directory. Usually, this is the `/usr/lib/tex/macros' directory.
280: For more information, *note @TeX{} Input Initialization: TeX Input.
281:
282: Documentation for GNU utilities and libraries should be written in
283: Texinfo format.
284:
285: * Menu:
286:
287: * Info File:: Characteristics of the Info file.
288: * Printed Manual:: Characteristics of the Printed Manual.
289: * Conventions:: General Syntactic Conventions.
290: * Short Sample:: A short sample Texinfo file.
291:
292:
293:
294: File: texinfo, Node: Info File, Next: Printed Manual, Up: Overview
295:
296: Characteristics of the Info file
297: ================================
298:
299: A Texinfo file can be transformed into a printed manual and an
300: on-line Info file.
301:
302: An on-line Info file is a file formatted so that the Info
303: documentation reading program can operate on it. Info files are
304: divided into pieces called "nodes", each of which contains the
305: discussion of one topic. Each node has a name, and contains both
306: text for the user to read and pointers to other nodes, which are
307: identified by their names. The Info program displays one node at a
308: time, and provides commands with which the user can move to the other
309: nodes to which the current node points.
310:
311: *note info: (info)Info, for more information about using Info.
312:
313: Normally, most of the nodes are arranged in a tree which branches down.
314: Each node may have any number of child nodes that describe subtopics
315: of the node's topic. The names of these child nodes, if any, are
316: listed in a "menu" within the parent node; this allows certain Info
317: commands to be used to move to one of the child nodes. Each child
318: node records the parent node name, as its `Up' pointer. Thus, if a
319: node were at the logical level of a `chapter', its child nodes would
320: be `sections'; likewise, the child nodes of a section would be
321: subsections.
322:
323: The root of the tree is the top node of the file, through which users
324: enter the file from the Info directory. By convention, this node is
325: always called `Top'. This node normally contains just a brief
326: summary of the file's purpose, and a large menu through which the
327: rest of the file is reached.
328:
329: Generally you enter the Info file from the top; then you can either
330: traverse the file systematically by going from node to node or you
331: can search large menus that correspond to indices and go directly to
332: the node that has the information you want.
333:
334: If you want to read through an Info file in sequence, as if it were a
335: printed manual, you can get the whole file with the advanced Info
336: command `g *'. (*note info: (info)Expert.)
337:
338: All the children of any one parent are linked together in a
339: bidirectional chain of `Next' and `Previous' pointers. This means
340: that all the nodes that are logically parallel to sections within a
341: chapter are all linked together. Normally the order in this chain is
342: the same as the order of the children in the parent's menu. The last
343: child has no `Next' pointer, and the first child normally has the
344: parent as its `Previous' pointer (as well as its `Up' pointer, of
345: course).
346:
347: Structuring the nodes in a tree is a matter of convention, not a
348: requirement. In fact, the `Up', `Previous' and `Next' pointers of a
349: node can point to any other nodes, and the menu can contain any other
350: nodes. The structure of nodes can be any directed graph. But it is
351: usually more comprehensible to make it a tree. Info provides another
352: kind of pointer between nodes, called a reference, that can be
353: sprinkled through the text of a node. This is usually the best way
354: to represent links that do not fit the tree structure.
355:
356: Most often the nodes fall into a strict tree structure that
357: corresponds to the structure of chapters and sections in the printed
358: manual. But there are times when this is not right for the material
359: being discussed. Therefore, Texinfo uses separate commands to
360: specify the node structure of the Info file and the section structure
361: of the printed manual. Also, Texinfo requires that you specify menus
362: explicitly, rather than generate them automatically based on an
363: assumed tree structure.
364:
365:
366:
367: File: texinfo, Node: Printed Manual, Next: Conventions, Prev: Info File, Up: Top
368:
369: Characteristics of the Printed Manual
370: =====================================
371:
372: A Texinfo file can be formatted and typeset as a printed manual. The
373: printed manual will be the same as any other book; it will have a
374: title page, copyright page, table of contents, and preface as you
375: would expect, as well as chapters, numbered or unnumbered sections
376: and subsections, not to mention page headers, cross references and
377: indices.
378:
379: Texinfo can be used for writing a book without ever having the
380: intention of converting it into on-line help. Texinfo can be used
381: for writing a novel; and it can even be used to write a memo,
382: although this application is not recommended since electronic mail is
383: so much easier.
384:
385: Texinfo uses the formatting language called TeX for typesetting. A
386: file called `texinfo.tex' contains information (definitions or
387: "macros") that TeX uses when it typesets a Texinfo file. (The macros
388: tell TeX how to convert the Texinfo @-commands to TeX commands which
389: TeX can then process to create the typeset document.) `texinfo.tex'
390: contains the specifications for printing a document, either with 7
391: inch by 9.25 inch pages or with 8.5 inch by 11 inch pages. (This is
392: 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
393: parameters in `texinfo.tex' you can easily change the size of the
394: printed document. In addition, you can readily change the style in
395: which the printed document is formatted; for example, you can change
396: the sizes and fonts used, the amount of indentation for each
397: paragraph, the degree to which words are hyphenated, and the like.
398: By changing the specifications, you can make a book look dignified,
399: old and serious, or light-hearted, young and cheery.
400:
401: TeX is very powerful and has a great many features. Because a
402: Texinfo file must be able to present information both on a
403: character-only terminal in Info form and in a typeset book, the
404: commands that Texinfo supports are necessarily limited.
405:
406:
407:
408: File: texinfo, Node: Conventions, Next: Short Sample, Prev: Printed Manual, Up: Overview
409:
410: General Syntactic Conventions
411: =============================
412:
413: Texinfo files contain a strictly limited set of constructs. The
414: strict limits make it possible for Texinfo files to be understood
415: both by TeX and by the code which converts them into Info files.
416:
417: All ASCII printing characters except `@', `{' and `}' can appear in
418: body text in a Texinfo file and stand for themselves. `@' is the
419: escape character which introduces commands. `{' and `}' should be
420: used only to surround arguments to certain commands. `{' and `}'
421: appearing anywhere else will be treated by TeX as a grouping but
422: treated by the code that produces an Info file as themselves; this
423: inconsistency is undesirable, so don't let it occur. To put one of
424: these special characters into the document, put an `@' character in
425: front of it. For example, you would insert `@@', `@{', and `@}'.
426:
427: It is customary in TeX to use doubled single-quote characters to
428: begin and end quotations, ```' like these `'''. This convention
429: should be followed in Texinfo files. Also, three hyphens in a row,
430: `--', are used for a dash--like this. In TeX, a single or even a
431: double hyphen produces a dash that is shorter than you want.
432:
433: TeX ignores the line-breaks in the input text, except for blank
434: lines, which separate paragraphs. Info generally preserves the line
435: breaks that are present in the input file. Therefore, break the
436: lines in the Texinfo file the way you want them to appear in the
437: output Info file, and let TeX take care of itself.
438:
439: Since Info does not normally refill paragraphs when it processes
440: them, a line with @-commands in it will sometimes look bad after Info
441: has run on it. To cause Info to refill the paragraph after finishing
442: with the other processing, you need to put the command `@refill' at
443: the end of the paragraph. (*Note Refilling paragraphs and Preventing
444: indentation: Refilling & Noindent.)
445:
446: To prevent a paragraph from being indented in the printed manual, put
447: the command `@noindent' on a line by itself before the start of the
448: text that should not be indented.
449:
450: If you mark off a region of the Texinfo file with the `@iftex' and
451: `@end iftex' commands so that the region will appear only in the
452: printed copy, you can use TeX commands that cannot be used in the
453: Info file.
454:
455: In order to be made into a printed manual, a Texinfo file *must*
456: begin with lines that looks like
457:
458: \input texinfo @c -*-texinfo-*-
459: @setfilename INFO-FILE-NAME
460: @settitle NAME OF MANUAL
461:
462: The `\input texinfo' line tells TeX to use the `texinfo.tex' file.
463: This line is usually followed by a start-of-header line (not shown
464: here) and then by the `@setfilename INFO-FILE-NAME' and `@settitle
465: NAME OF MANUAL' lines. These two lines are needed to provide a name
466: for the Info file and to specify the name used on the left-hand page
467: headers of the printed manual.
468:
469: The two lines that contain the `@setfilename' and `@settitle'
470: commands usually are sandwiched between the start-of-header line and
471: the end-of-header line. (*Note Start-of-Header::, for more
472: information.) The start-of-header and end-of-header lines are needed
473: if you are going to run TeX or Info on just part of a file.
474:
475:
476:
477: File: texinfo, Node: Short Sample, Prev: Conventions, Up: Overview
478:
479: A Short Sample Texinfo File
480: ===========================
481:
482: A Texinfo file looks like the following, which is a complete but very
483: short Texinfo file. The `@comment' command introduces comments that
484: will not appear in either the Info file or the printed manual; they
485: are for the person who reads the Texinfo file.
486:
487: The first part of the file, from `\input texinfo' through to `@end
488: titlepage', looks more intimidating than it is. Most of the material
489: is standard boilerplate; when you write a manual, you just put in the
490: name of your own manual in this section.
491:
492: All the commands that tell TeX how to typeset the printed manual and
493: tell `texinfo-format-buffer' how to create an Info file are preceded
494: by `@'; thus, `@node' indicates a node and `@chapter' indicates the
495: start of a chapter.
496:
497: \input texinfo @c -*-texinfo-*-
498: @setfilename name-of-texinfo-file
499: @settitle Name of Manual
500: @setchapternewpage odd
501:
502: @ifinfo
503: @comment The following line inserts the copyright notice
504: @comment into the Info file.
505: Copyright @copyright{} 1988 Free Software Foundation, Inc.
506: @end ifinfo
507:
508: @comment The titlepage section does not appear in the Info file.
509: @titlepage
510: @sp 10
511: @comment The title is printed in a large font.
512: @center @titlefont{Sample Title}
513:
514: @comment The following two commands start the copyright page
515: @comment for the printed manual. This will not appear in the Info file.
516: @page
517: @vskip 0pt plus 1filll
518: Copyright @copyright{} year copyright-owner
519: @end titlepage
520:
521: @comment The Top node contains the master menu for the Info file.
522: @comment This appears only in the Info file, not the printed manual.
523:
524: @node Top, First Chapter, (dir), (dir)
525: @comment node-name, next, previous, up
526:
527: @menu
528: * First Chapter:: The first chapter is the
529: only chapter in this sample.
530: @end menu
531:
532: @node First Chapter, , Top, Top
533: @comment node-name, next, previous, up
534: @chapter First Chapter
535: @cindex Reference to First Chapter
536:
537: This is the contents of the first chapter.
538:
539: Here is a numbered list.
540:
541: @enumerate
542: @item
543: This is the first item.
544:
545: @item
546: This is the second item.
547: @end enumerate
548:
549: The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file
550: like this into an Info file; and @TeX{} typesets it for a printed
551: manual.
552:
553: @node Concept Index, , Previous Node, Top
554: @comment node-name, next, previous, up
555: @unnumbered Concept Index
556:
557: @printindex cp
558:
559: @contents
560: @bye
561:
562: Here is what the contents of the first chapter of the sample look like:
563:
564: This is the contents of the first chapter.
565:
566: Here is a numbered list.
567:
568: 1. This is the first item.
569:
570: 2. This is the second item.
571:
572: The `M-x texinfo-format-buffer' command transforms a Texinfo
573: file like this into an Info file; and TeX typesets it for a
574: printed manual.
575:
576:
577:
578: File: texinfo, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
579:
580: Using Texinfo Mode
581: ******************
582:
583: In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
584: This means that Emacs has commands and features especially designed
585: for working with Texinfo files. Like all other Emacs features, you
586: can customize or enhance these as you wish. In particular, the
587: keybindings are very easy to change. The keybindings described here
588: are the default or standard ones.
589:
590: The major features of Texinfo mode are:
591:
592: * Paragraph filling control.
593:
594: * A command to show the structure of the file.
595:
596: * Pre-defined keystroke commands to insert commonly used strings
597: of text.
598:
599: * Formatting a part of a file for Info, rather than the whole file.
600:
601: In general, in Texinfo mode, the GNU Emacs editing commands are like
602: those in text-mode. The major difference is that the paragraph
603: separation variable and syntax table are set up so expression
604: commands skip Texinfo bracket groups. This means, for example, that
605: the `M-q' (`fill-paragraph') command will refill a paragraph but not
606: the @-command on a line adjacent to it.
607:
608: By convention, the Texinfo file name shall end with the extension
609: `.texinfo' so that Emacs knows to use Texinfo mode for editing it.
610:
611: * Menu:
612:
613: * Info on a Region:: Formatting part of a file for Info.
614: * Showing the Structure:: Showing the structure of a file.
615: * Inserting:: Inserting frequently used commands.
616:
617:
618:
619: File: texinfo, Node: Info on a Region, Next: Showing the Structure, Prev: Texinfo Mode, Up: Texinfo Mode
620:
621: Formatting a Region for Info
622: ============================
623:
624: To see what part of a Texinfo file will look like after it has been
625: transformed into an Info file, use the command `C-c C-f'
626: (`texinfo-format-region'). This command formats the current region
627: of the Texinfo file for Info and writes it to a temporary buffer
628: called `*Info Region*'.
629:
630: For `texinfo-format-region' to work, the file *must* include a line
631: that has `@setfilename' in its header.
632:
633: The command is:
634:
635: `C-c C-f'
636: texinfo-format-region
637:
638:
639:
640: File: texinfo, Node: Showing the Structure, Next: Inserting, Prev: Info on a Region, Up: Texinfo Mode
641:
642: Showing the Structure of a File
643: ===============================
644:
645: You can show the structure of a Texinfo file by using the `C-c C-s'
646: command (`texinfo-show-structure'). This command shows the structure
647: of a Texinfo file by listing the lines with the @-commands for
648: `@node', `@chapter', `@section' and the like. These lines are
649: displayed in another window called the `*Occur*' window. In that
650: window, you can position the cursor over one of the lines and use the
651: `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
652: corresponding spot in the Texinfo file.
653:
654: The two commands are:
655:
656: `C-c C-s'
657: texinfo-show-structure
658:
659: `C-c C-c'
660: occur-mode-goto-occurrence
661:
662: Often, when you are working on a manual, you will be interested only
663: in the structure of the current chapter. In this case, you can mark
664: off the region of the buffer that you are interested in with the `C-x
665: n' (`narrow-to-region') command and `texinfo-show-structure' will
666: work on only that region. (To see the whole buffer again, use `C-x
667: w' (`widen').)
668:
669:
670:
671: File: texinfo, Node: Inserting, Prev: Showing the Structure, Up: Texinfo Mode
672:
673: Inserting Frequently Used Commands
674: ==================================
675:
676: Texinfo mode provides commands that insert various frequently used
677: @-commands into the buffer. You can use these commands to save
678: keystrokes. And you can insert balanced curly braces with the `M-{'
679: command, (`texinfo-insert-braces') and later use the `M-}' command
680: (`up-list') to move forward past the closing brace.
681:
682: The special commands are invoked by typing `C-c' twice and then the
683: first letter of the @-command.
684:
685: `C-c C-c c'
686: texinfo-insert-@code
687:
688: `C-c C-c d'
689: texinfo-insert-@dfn
690:
691: `C-c C-c e'
692: texinfo-insert-@end
693:
694: `C-c C-c i'
695: texinfo-insert-@item
696:
697: `C-c C-c n'
698: texinfo-insert-@node
699:
700: `C-c C-c s'
701: texinfo-insert-@samp
702:
703: `C-c C-c v'
704: texinfo-insert-@var
705:
706: `M-{'
707: texinfo-insert-braces
708:
709: `M-}'
710: up-list
711:
712: This list was generated by analyzing the frequency with which
713: commands were used in the ``GNU Emacs Manual'' and the ``GDB
714: Manual''. If you wish to add your own insert commands, you can bind
715: a keyboard macro to a key, use abbreviations or extend the code in
716: `texinfo.el'.
717:
718:
719:
720: File: texinfo, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
721:
722: Beginning a Texinfo File
723: ************************
724:
725: Various pieces of information have to be provided to Texinfo at the
726: beginning of a Texinfo file, such as the name of the file, the title
727: of the document and the like. Generally, the beginning of a Texinfo
728: file has four parts:
729:
730: 1. The header, marked by start-of-header and end-of-header lines,
731: that includes the commands for naming the Texinfo file and
732: telling TeX what definitions' file to use when processing the
733: file.
734:
735: 2. A section, marked by the `@ifinfo' and `@end ifinfo' commands,
736: that contains a short statement of what the file is about, the
737: copyright notice and copying permissions. This section appears
738: only in the Info file.
739:
740: 3. A section, marked by the `@titlepage' and `@end titlepage'
741: commands, that contains the title page, the copyright page and
742: copying permissions. This section appears only in the printed
743: manual.
744:
745: 4. The `Top' node that contains an extensive menu for the whole
746: Info file. The contents of this node only appear in the Info
747: file.
748:
749: If the Texinfo file has a section containing licensing information
750: and a warranty disclaimer, that section usually follows the `Top'
751: node. The licensing section will be followed by a preface or else by
752: the first chapter of the manual.
753:
754: Since the copyright notice and the copying permissions are in
755: sections that appear only in the Info file or only in the printed
756: manual, this information has to be repeated twice.
757:
758: The following sample shows what is needed.
759:
760: \input texinfo @c -*-texinfo-*-
761: @comment %**start of header (This is for running Texinfo on a region.)
762: @setfilename name-of-texinfo-file
763: @settitle Name of Manual
764: @setchapternewpage odd
765: @comment %**end of header (This is for running Texinfo on a region.)
766:
767: @ifinfo
768: This file documents ...
769:
770: Copyright @copyright{} year copyright-owner
771:
772: Permission is granted to ...
773: @end ifinfo
774:
775: @titlepage
776: @sp 10
777: @center @titlefont{Name of Manual When Printed}
778: @sp 2
779: @center Subtitle, If Any
780: @sp 2
781: @center Author
782:
783: @comment The following two commands start the copyright page.
784: @page
785: @vskip 0pt plus 1filll
786: Copyright @copyright{} year copyright-owner
787:
788: Published by ...
789:
790: Permission is granted to ...
791: @end titlepage
792:
793:
794: @node Top, Overview, (dir), (dir)
795:
796: @menu
797: * First Chapter:: The first chapter is usually an overview.
798: * Second Chapter:: ...
799: <many more menu items here>
800: @end menu
801:
802: @node First Chapter, Second Chapter, top, top
803: @comment node-name, next, previous, up
804: @chapter First Chapter
805: @cindex Reference to First Chapter
806:
807: * Menu:
808:
809: * Header:: Necessary first lines.
810: * Permissions for Info:: Copyright notice and copying permissions.
811: * Titlepage & Copyright Page:: Printed title and copyright pages.
812: * Top Node:: The top node and master menu.
813: * License and Distribution:: The importance of the license.
814:
815:
816:
817: File: texinfo, Node: Header, Next: Permissions for Info, Prev: Beginning a File, Up: Beginning a File
818:
819: The Texinfo File Header
820: =======================
821:
822: Texinfo files start with at least three lines that provide Info and
823: TeX with necessary information. If you want to run TeX on just a
824: part of the Texinfo File, you also have to mark these heading lines
825: with start-of-header and end-of-header lines.
826:
827: * Menu:
828:
829: * First Line:: The first line of a Texinfo file.
830: * Start-of-Header:: Identifying the start of the header.
831: * Setfilename:: Specifying the name of the Info file.
832: * Settitle:: Specifying the title used by the headings.
833: * Setchapternewpage:: Starting chapters on odd numbered pages.
834: * End-of-Header:: Identifying the end of the header.
835:
836:
837:
838: File: texinfo, Node: First Line, Next: Start-of-Header, Prev: Header, Up: Header
839:
840: The First Line of a Texinfo File
841: --------------------------------
842:
843: Every Texinfo file that is to be the top-level input to TeX must
844: begin with a line that looks like this:
845:
846: \input texinfo @c -*-texinfo-*-
847:
848: The line serves two functions:
849:
850: 1. When the file is processed by TeX, it loads the macros needed
851: for processing a Texinfo file. These are in a file called
852: `texinfo.tex' which is usually located in the
853: `/usr/lib/tex/macros' directory.
854:
855: 2. When the file is edited in GNU Emacs, it causes Texinfo mode to
856: be used.
857:
858: The `\input texinfo' line should be followed by the start-of-header
859: line. This makes it possible for the command for running TeX on a
860: part of the Texinfo file (`texinfo-hardcopy-region') to operate. The
861: reason for this is that the `texinfo-hardcopy-region' command will
862: look on the line preceding the start-of-header line for the `\input
863: texinfo' line.
864:
865:
866:
867: File: texinfo, Node: Start-of-Header, Next: Setfilename, Prev: First Line, Up: Header
868:
869: `start-of-header'
870: -----------------
871:
872: The start-of-header line should immediately follow the first line of
873: the Texinfo file.
874:
875: The `texinfo-hardcopy-region' command will look at the line preceding
876: the start-of-header line to find the `\input texinfo' line.
877:
878: Usually, the start-of-header line looks like this:
879:
880: @comment %**start of header (This is for running Texinfo on a region.)
881:
882: The reason for the odd string of characters (`%**') is so that the
883: `texinfo-hardcopy-region' command does not accidently find something
884: that it shouldn't when it is looking for the header.
885:
886: In the default configuration, the phrase `(This is for running
887: Texinfo on a region.)' is not needed and is just included to make it
888: easier for someone reading the Texinfo file.
889:
890: The start-of-header line and the end-of-header line are Texinfo mode
891: variables that you can change.
892:
893:
894:
895: File: texinfo, Node: Setfilename, Next: Settitle, Prev: Start-of-Header, Up: Header
896:
897: @setfilename
898: ------------
899:
900: In order to be made into an Info file, a Texinfo file must contain a
901: line that looks like this:
902:
903: @setfilename INFO-FILE-NAME
904:
905: This line specifies the name of the Info file to be generated. In
906: fact, there can be other things in the file before this line, but
907: they are ignored in the generation of an Info file. The
908: `@setfilename' line is ignored when a printed manual is generated.
909:
910:
911:
912: File: texinfo, Node: Settitle, Next: Setchapternewpage, Prev: Setfilename, Up: Header
913:
914: @settitle
915: ---------
916:
917: In order to be made into a printed manual file, a Texinfo file must
918: contain a line that specifies the title of the manual. Texinfo uses
919: this information during printing to put the title on every other page
920: as a heading; Texinfo puts the current chapter title on the other
921: pages. Texinfo can find the name of the chapter title from the
922: information provided by the `@chapter' command, but you must tell it
923: the manual title with `@settitle':
924:
925: @settitle TITLE
926:
927: This command, on a line by itself, causes TITLE to be used for the
928: headings. Usually, you will use the same words for the title on the
929: title page and for the title specified by this command for the
930: headings, but the two could be different. For example, the title on
931: the title page may be longer than the title specified by the
932: `settitle' command.
933:
934: The `@settitle' command should precede everything that generates
935: actual output.
936:
937:
938:
939: File: texinfo, Node: Setchapternewpage, Next: End-of-Header, Prev: Settitle, Up: Header
940:
941: @setchapternewpage
942: ------------------
943:
944: Conventionally, chapters start on the page on the right hand side of
945: a book; and the right hand page has an odd number. To make sure that
946: Texinfo does this, you can use the command `@setchapternewpage'. For
947: example, to cause each chapter to start on a fresh odd-numbered page:
948:
949: @setchapternewpage odd
950:
951: Page numbering is turned on by the `@end titlepage' command, so the
952: `@setchapternewpage' should come before it. Although it can occur
953: anywhere in the beginning of the file, it is most convenient to put
954: it in this location.
955:
956:
957:
958: File: texinfo, Node: End-of-Header, Prev: Setchapternewpage, Up: Header
959:
960: `end-of-header'
961: ---------------
962:
963: The end-of-header line should follow the line containing the
964: `@setchapternewpage' command.
965:
966: Usually, the end-of-header line looks like this:
967:
968: @comment %**end of header (This is for running Texinfo on a region.)
969:
970: In the default configuration, the phrase `(This is for running
971: Texinfo on a region.)' is not needed and is just included to make it
972: easier for someone reading the Texinfo file.
973:
974: The reason for the odd string of characters (`%**') is so that the
975: `texinfo-hardcopy-region' command does not accidently find something
976: that it shouldn't when it is looking for the header.
977:
978: The start-of-header line and the end-of-header line are Texinfo mode
979: variables that you can change.
980:
981:
982:
983: File: texinfo, Node: Permissions for Info, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File
984:
985: Copying Permissions for Info
986: ============================
987:
988: Since the title page and the copyright page appear only in the
989: printed copy of the manual, the same information has to inserted in a
990: section that appears only in the Info file. This section usually
991: contains a brief description of the contents of the Info file, a
992: copyright notice and copying permissions.
993:
994: The copyright notice should read:
995:
996: Copyright YEAR COPYRIGHT-OWNER
997:
998: and be put on a line by itself.
999:
1000: Standard text for the copyright permissions is contained in the
1001: appendix. *Note Ifinfo Permissions::, for the complete text.
1002:
1003:
1004:
1005: File: texinfo, Node: Titlepage & Copyright Page, Next: Top Node, Prev: Permissions for Info, Up: Beginning a File
1006:
1007: The Title and Copyright Pages
1008: =============================
1009:
1010: The title and copyright pages appear in the printed manual, but not
1011: in the Info file. Because of this, it is possible to use a couple of
1012: slightly obscure TeX typesetting commands that could not be used in
1013: an Info file. In addition, this part of the beginning of a Texinfo
1014: file contains the text of the copying permissions that will appear in
1015: the printed manual.
1016:
1017: * Menu:
1018:
1019: * Titlepage:: Creating a title page for the printed manual.
1020: * Center:: Centering a line.
1021: * Copyright & Printed Permissions:: Inserting the copyright notice
1022: and printed permissions.
1023:
1024:
1025:
1026: File: texinfo, Node: Titlepage, Next: Center, Prev: Setchapternewpage, Up: Titlepage & Copyright Page
1027:
1028: @titlepage
1029: ----------
1030:
1031: Start the material for the title page and following copyright page
1032: with `@titlepage' on a line by itself and end it with `@end
1033: titlepage' on a line by itself. The title page and copyright page
1034: material appears only in the printed manual, not in the Info file.
1035:
1036: Also, the `@end titlepage' command starts a new page and turns on
1037: page numbering (generation of headings). Therefore, all the material
1038: that you want to appear on unnumbered pages should be put between the
1039: `@titlepage' and `@end titlepage' commands. By using the `@page'
1040: command you can force a page break within the region delineated by
1041: the `@titlepage' and `@end titlepage' commands and create more than
1042: one unnumbered page. This is how the copyright page is produced.
1043:
1044: To select a large font suitable for the title itself, you can use the
1045: command `@titlefont'. For example:
1046:
1047: @center @titlefont{Texinfo}
1048:
1049: Also, you can use `@sp' commands to adjust vertical spacing. For
1050: example:
1051:
1052: @sp 2
1053:
1054: In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch
1055: manual.
1056:
1057:
1058:
1059: File: texinfo, Node: Center, Next: Titlepage, Prev: Copyright & Printed Permissions, Up: Titlepage & Copyright Page
1060:
1061: @center
1062: -------
1063:
1064: A line containing `@center TEXT' produces a line of output containing
1065: TEXT, centered between the margins.
1066:
1067:
1068:
1069: File: texinfo, Node: Copyright & Printed Permissions, Next: Center, Up: Titlepage & Copyright Page
1070:
1071: The Copyright Page and Printed Permissions
1072: ------------------------------------------
1073:
1074: By international treaty, the copyright notice for a book should
1075: either be on the title page or on the back of the title page. Other
1076: locations in a book are not official and do not provide copyright
1077: protection. The copyright notice should include the year followed by
1078: the name of the person or organization who has the copyright.
1079:
1080: When the copyright notice is on the back of the title page, the page
1081: is not numbered. Therefore, in Texinfo, the information on the
1082: copyright page should be within the region delineated by the
1083: `@titlepage' and `@end titlepage' commands.
1084:
1085: To cause a page break, the `@page' command is used. In the sample,
1086: the `@page' command is followed by the somewhat mysterious line that
1087: reads: `@vskip 0pt plus 1filll'. This is a line that uses TeX
1088: commands to push the copyright notice and the other text on the
1089: copyright page towards the bottom of the page. The `@vskip' command
1090: means to skip lines and put in white space. The `0pt plus 1filll'
1091: means to put in zero points of mandatory white space, and as much
1092: optional white space as needed. Note the use of three `l's in the
1093: word `filll'; this is the correct use in TeX.
1094:
1095: The `@copyright{}' command generates a `c' inside a circle. The
1096: copyright notice itself has the following legally defined sequence:
1097:
1098: Copyright (C) YEAR COPYRIGHT-OWNER
1099:
1100: It is customary to put information on how to get a manual after the
1101: copyright notice (the address of the Free Software Foundation, for
1102: example) and the permissions.
1103:
1104: Note that the permissions have to be repeated here as well as in the
1105: `ifinfo' section that immediately follows the header since this
1106: section appears only in the printed manual and the `ifinfo' section
1107: appears only in the Info file.
1108:
1109: Standard text for the permissions appears in the appendix. *Note
1110: Sample Permissions::.
1111:
1112:
1113:
1114: File: texinfo, Node: Top Node, Next: License and Distribution, Prev: Titlepage & Copyright Page, Up: Beginning a File
1115:
1116: The Top Node and Master Menu
1117: ============================
1118:
1119: The `Top' node contains an extensive, master menu for the whole Info
1120: file. The contents of this node appear only in the Info file.
1121: Nothing in this node should appear in the printed file. Since a node
1122: line by itself and a menu by itself are not printed, the contents of
1123: this node do not have to be within a region delineated by `@ifinfo'
1124: and `@end ifinfo' commands. However, any text within the node should
1125: be marked off in that manner. You may want to put a short summary
1126: before the master menu inside a region delineated by `@ifinfo' and
1127: `@end ifinfo' commands. Usually, the `Previous' and `Up' nodes refer
1128: to the top level directory of the whole Info system, with pointers to
1129: `(dir)'.
1130:
1131: Generally, the top menu is divided into parts.
1132:
1133: * The first part contains the major nodes in the Texinfo file: the
1134: nodes for the chapters, chapter-like sections and the major
1135: appendices.
1136:
1137: * The second part contains entries for the indices. In an Info
1138: file, it is very useful to have indices here at the beginning of
1139: the file in the top node rather than at the end, as in a printed
1140: book.
1141:
1142: * The third and subsequent parts contain a listing of the other,
1143: lower level nodes, often ordered by chapter. This way, an
1144: inquirer can go directly to a particular node if he or she is
1145: searching for specific information. (These nodes are not
1146: required; use them if you think they are a convenience.)
1147:
1148: Each section in the menu can be introduced a descriptive line. So
1149: long as the line does not begin with an asterisk, it will not be
1150: treated as a menu item. (*Note Making Menus: Menu, for more
1151: information.)
1152:
1153: For example, the Top node of this manual looks like this (but with
1154: many more entries):
1155:
1156: @node Top, Overview, (dir), (dir)
1157:
1158: @menu
1159: * Overview:: What is Texinfo?
1160: * Texinfo Mode:: Special features in GNU Emacs.
1161: ...
1162:
1163: Indices, nodes containing large menus
1164:
1165: * Command Index:: An item for each @-command.
1166: * Concept Index:: An item for each concept.
1167:
1168: A detailed node listing
1169:
1170: Overview
1171: * Info File:: Characteristics of the Info file.
1172: * Printed Manual:: Characteristics of the printed manual.
1173:
1174: Using Texinfo Mode
1175: * Info on a Region:: Formatting a region for Info.
1176: * Showing the Structure:: Showing the structure of a file.
1177: ...
1178: ...
1179:
1180:
1181:
1182: File: texinfo, Node: License and Distribution, Prev: Top Node, Up: Beginning a File
1183:
1184: Licensing and Distribution Information
1185: ======================================
1186:
1187: If the Texinfo file has a section containing the ``General Public
1188: License'' and the distribution information and a warranty disclaimer,
1189: this section usually follows the `Top' node. The licensing and
1190: distribution information and the disclaimer are followed by a preface
1191: or else by the first chapter of the manual.
1192:
1193: The licensing agreement is very important to Project GNU
1194: documentation and software. Without it, you may find that you can no
1195: longer get the software or its documentation. This sounds
1196: paradoxical, but the state of the world is such that documentation
1197: and software that does not have a ``restrictive'' license to make
1198: them freely distributable may be lost to the public. This has
1199: happened.
1200:
1201: For a good example of the text that could be used for the
1202: Distribution, General Public License and NO WARRANTY sections of your
1203: document, see the latest version of the ``GNU Emacs Manual''.
1204:
1205: Although a preface is not a required part of a Texinfo file, it is
1206: very helpful. Ideally, it should state clearly and concisely what
1207: the file is about and who would be interested in reading it. In
1208: general, the preface would follow the licensing and distribution
1209: information, although sometimes people put it earlier in the
1210: document. Usually, a preface is put in an `@unnumbered' section.
1211: (*Note Unnumbered and Appendix::.)
1212:
1213:
1214:
1215: File: texinfo, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top
1216:
1217: Ending a Texinfo File
1218: *********************
1219:
1220: The end of a Texinfo file should include the indices, the commands to
1221: generate detailed and summary tables of contents and the @-command
1222: that tells TeX that it has reached the end of the file.
1223:
1224: For example, a Texinfo file might be ended as follows:
1225:
1226: @node Concept Index, , Previous Node, Top
1227: @comment node-name, next, previous, up
1228: @unnumbered Concept Index
1229:
1230: @printindex cp
1231:
1232: @contents
1233: @bye
1234:
1235: The `@bye' command should be on a line by itself and every Texinfo
1236: file must end with such a line. This command terminates TeX
1237: processing and forces out unfinished pages.
1238:
1239: * Menu:
1240:
1241: * Contents:: Generating a table of contents
1242: * Indices:: Generating, sorting and printing indices
1243:
1244:
1245:
1246: File: texinfo, Node: Contents, Next: Indices, Up: Ending a File
1247:
1248: Generating a Table of Contents
1249: ==============================
1250:
1251: The commands `@chapter', `@section', etc., supply the information to
1252: make up a table of contents, but they do not cause an actual table to
1253: be generated. To do this, you must use the commands `@contents' and
1254: `@summarycontents'.
1255:
1256: `@contents'
1257: The table of contents command outputs (into a printed manual) a
1258: complete table of contents, based on the `@chapter',
1259: `@unnumbered' and other sectioning commands. This command
1260: should be used on a line by itself.
1261:
1262: `@summarycontents'
1263: The summary contents command generates a summary table of
1264: contents that lists only the chapters (and appendices and
1265: unnumbered chapters); sections, subsections and subsubsections
1266: are omitted. This command should be used on a line by itself.
1267: Only large manuals need a summary table of contents.
1268:
1269: You can use either one of these commands, or both. Each command
1270: automatically generates a chapter-like heading at the top of the page.
1271: Tables of contents should be generated at the very end of the manual,
1272: just before the `@bye' command; the tables of contents commands
1273: should follow any indices that are output, so that the indices will
1274: appear in the contents.
1275:
1276: INDICES...
1277: @summarycontents
1278: @contents
1279: @bye
1280:
1281: The commands `@contents' and `@summarycontents' are ignored when an
1282: Info file is being generated.
1283:
1284:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.