OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / texinfo.i09 < prev next >

Wrap

GNU Info File | 1993-06-12 | 50.4 KB | 1,222 lines

This is Info file texinfo, produced by Makeinfo-1.47 from the input file texinfo2.tex. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line information and a printed manual. Copyright (C) 1988, 1990, 1991, 1992 Free Software Foundation, Inc. This is the second edition of the Texinfo documentation, and is consistent with version 2 of `texinfo.tex'. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: texinfo, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions Titlepage Copying Permissions ============================= In the `@titlepage' section of the Texinfo file, the standard Free Software Foundation copying permission notice follows the copyright notice and publishing information. The standard phrasing is as follows: Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Distribution'' and ``General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the sections entitled ``Distribution'' and ``General Public License'' may be included in a translation approved by the author instead of in the original English. File: texinfo, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top Include Files ************* When TeX or an Info formatting command sees an `@include' command in a Texinfo file, it processes the contents of the file named by the command and incorporates them into the DVI or Info file being created. Index entries from the included file are incorporated into the indices of the output file. Include files let you keep a single large document as a collection of conveniently small parts. * Menu: * Using Include Files:: How to use the `@include' command. * texinfo-multiple-files-update:: How to create and update nodes and menus when using included files. * Include File Requirements:: What `texinfo-multiple-files-update' expects. * Sample Include File:: A sample outer file with included files within it; and a sample included file. * Include Files Evolution:: How use of the `@include' command has changed over time. File: texinfo, Node: Using Include Files, Next: texinfo-multiple-files-update, Up: Include Files How to Use Include Files ======================== To include another file within a Texinfo file, write the `@include' command at the beginning of a line and follow it on the same line by the name of a file to be included. For example: @include buffers.texi An included file should simply be a segment of text that you expect to be included as is into the overall or "outer" Texinfo file; it should not contain the standard beginning and end parts of a Texinfo file. In particular, you should not start an included file with a line saying `\input texinfo'; if you do, that phrase is inserted into the output file as is. Likewise, you should not end an included file with an `@bye' command; that command will stop TeX processing immediately. In the past, you were required to write an `@setfilename' line at the beginning of an included file, but no longer. Now, it does not matter whether you write such a line. If an `@setfilename' line exists in an included file, it is ignored. Conventionally, an included file begins with an `@node' line that is followed by an `@chapter' line. Each included file is one chapter. This makes it easy to use the regular node and menu creating and updating commands to create the node pointers and menus within the included file. However, the simple Emacs node and menu creating and updating commands do not work with multiple Texinfo files. Thus you cannot use these commands to fill in the `Next', `Previous', and `Up' pointers of the `@node' line that begins the included file. Also, you cannot use the regular commands to create a master menu for the whole file. Either you must insert the menus and the `Next', `Previous', and `Up' pointers by hand, or you must use the GNU Emacs Texinfo mode command, `texinfo-multiple-files-update', that is designed for `@include' files. File: texinfo, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files `texinfo-multiple-files-update' =============================== GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update' command. This command creates or updates `Next', `Previous', and `Up' pointers of included files as well as those in the outer or overall Texinfo file, and it creates or updates a main menu in the outer file. Depending whether you call it with optional arguments, the command updates only the pointers in the first `@node' line of the included files or all of them: `M-x texinfo-multiple-files-update' Called without any arguments: - Create or update the `Next', `Previous', and `Up' pointers of the first `@node' line in each file included in an outer or overall Texinfo file. - Create or update the `Top' level node pointers of the outer or overall file. - Create or update a main menu in the outer file. `C-u M-x texinfo-multiple-files-update' Called with `C-u' as a prefix argument: - Create or update pointers in the first `@node' line in each included file. - Create or update the `Top' level node pointers of the outer file. - Create and insert a master menu in the outer file. The master menu is made from all the menus in all the included files. `C-u 8 M-x texinfo-multiple-files-update' Called with a numeric prefix argument, such as `C-u 8': - Create or update *all* the `Next', `Previous', and `Up' pointers of all the included files. - Create or update *all* the menus of all the included files. - Create or update the `Top' level node pointers of the outer or overall file. - And then create a master menu in the outer file. This is similar to invoking `texinfo-master-menu' with an argument when you are working with just one file. Note the use of the prefix argument in interactive use: with a regular prefix argument, just `C-u', the `texinfo-multiple-files-update' command inserts a master menu; with a numeric prefix argument, such as `C-u 8', the command updates *every* pointer and menu in *all* the files and then inserts a master menu. File: texinfo, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files Include File Requirements ========================= If you plan to use the `texinfo-multiple-files-update' command, the outer Texinfo file that lists included files within it should contain nothing but the beginning and end parts of a Texinfo file, and a number of `@include' commands listing the included files. It should not even include indices, which should be listed in an included file of their own. Moreover, each of the included files must contain exactly one highest level node (conventionally, `@chapter' or equivalent), and this node must be the first node in the included file. Furthermore, each of these highest level nodes in each included file must be at the same hierarchical level in the file structure. Usually, each is an `@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally, each included file contains one, and only one, chapter or equivalent-level node. The outer file should contain only *one* node, the `Top' node. It should *not* contain any nodes besides the single `Top' node. The `texinfo-multiple-files-update' command will not process them. File: texinfo, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files Sample File with `@include' =========================== Here is an example of a complete outer Texinfo file with `@include' files within it before running `texinfo-multiple-files-update', which would insert a main or master menu: \input texinfo @c -*-texinfo-*- @setfilename include-example.info @settitle Include Example @setchapternewpage odd @titlepage @sp 12 @center @titlefont{Include Example} @sp 2 @center by Whom Ever @page @vskip 0pt plus 1filll Copyright @copyright{} 1990 Free Software Foundation, Inc. @end titlepage @ifinfo @node Top, First, (dir), (dir) @top Master Menu @end ifinfo @include foo.texinfo @include bar.texinfo @include concept-index.texinfo @summarycontents @contents @bye An included file, such as `foo.texinfo', might look like this: @node First, Second, , Top @chapter First Chapter Contents of first chapter ... The full contents of `concept-index.texinfo' might be as simple as this: @node Concept Index, , Second, Top @unnumbered Concept Index @printindex cp The outer Texinfo source file for `The GNU Emacs Lisp Reference Manual' is named `elisp.texi'. This outer file contains a master menu with 417 entries and a list of 41 `@include' files. File: texinfo, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files Evolution of Include Files ========================== When Info was first created, it was customary to create many small Info files on one subject. Each Info file was formatted from its own Texinfo source file. This custom meant that Emacs did not need to make a large buffer to hold the whole of a large Info file when someone wanted information; instead, Emacs allocated just enough memory for the small Info file that contained the particular information sought. This way, Emacs could avoid wasting memory. References from one file to another were made by referring to the file name as well as the node name. (*Note Referring to Other Info Files: Other Info Files. Also, see *Note `@xref' with Four and Five Arguments: Four and Five Arguments.) Include files were designed primarily as a way to create a single, large printed manual out of several smaller Info files. In a printed manual, all the references were within the same document, so TeX could automatically determine the references' page numbers. The Info formatting commands used include files only for creating joint indices; each of the individual Texinfo files had to be formatted for Info individually. (Each, therefore, required its own `@setfilename' line.) However, because large Info files are now split automatically, it is no longer necessary to keep them small. Nowadays, multiple Texinfo files are used mostly for large documents, such as `The GNU Emacs Lisp Reference Manual', and for projects in which several different people write different sections of a document simultaneously. In addition, the Info formatting commands have been extended to work with the `@include' command so as to create a single large Info file that is split into smaller files if necessary. This means that you can write menus and cross references without naming the different Texinfo files. File: texinfo, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top Page Headings ************* Most printed manuals contain headings along the top of every page except the title and copyright pages. Some manuals also contain footings. (Headings and footings have no meaning to Info, which is not paginated.) * Menu: * Headings Introduced:: Conventions for using page headings. * Heading Format:: Standard page heading formats. * Heading Choice:: How to specify the type of page heading. * Custom Headings:: How to create your own headings and footings. File: texinfo, Node: Headings Introduced, Next: Heading Format, Up: Headings Headings Introduced =================== Texinfo provides standard page heading formats for manuals that are printed on one side of each sheet of paper and for manuals that are printed on both sides of the paper. Usually, you will use one or other of these formats, but you can specify your own format, if you wish. In addition, you can specify whether chapters should begin on a new page, or merely continue the same page as the previous chapter; and if chapters begin on new pages, you can specify whether they must be odd-numbered pages. By convention, a book is printed on both sides of each sheet of paper. When you open a book, the right-hand page is odd-numbered, and chapters begin on right-hand pages--a preceding left-hand page is left blank if necessary. Reports, however, are often printed on just one side of paper, and chapters begin on a fresh page immediately following the end of the preceding chapter. In short or informal reports, chapters often do not begin on a new page at all, but are separated from the preceding text by a small amount of whitespace. The `@setchapternewpage' command controls whether chapters begin on new pages, and whether one of the standard heading formats is used. In addition, Texinfo has several heading and footing commands that you can use to generate your own heading and footing formats. In Texinfo, headings and footings are single lines at the tops and bottoms of pages; you cannot create multiline headings or footings. Each header or footer line is divided into three parts: a left part, a middle part, and a right part. Any part, or a whole line, may be left blank. Text for the left part of a header or footer line is set flushleft; text for the middle part is centered; and, text for the right part is set flushright. File: texinfo, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings Standard Heading Formats ======================== Texinfo provides two standard heading formats, one for manuals printed on one side of each sheet of paper, and the other for manuals printed on both sides of the paper. By default, nothing is specified for the footing of a Texinfo file, so the footing remains blank. The standard format for single-sided printing consists of a header line in which the left-hand part contains the name of the chapter, the central part is blank, and the right-hand part contains the page number. The single-sided page looks like this: _______________________ | | | chapter page number | | | | Start of text ... | | ... | | | The standard format for two-sided printing depends on whether the page number is even or odd. By convention, even-numbered pages are on the left- and odd-numbered pages are on the right. (TeX will adjust the widths of the left- and right-hand margins. Usually, widths are correct, but during double-sided printing, it is wise to check that pages will bind properly--sometimes a printer will produce output in which the even-numbered pages have a larger right-hand margin than the odd-numbered pages.) In the standard double-sided format, the left part of the left-hand (even-numbered) page contains the page number, the central part is blank, and the right part contains the title (specified by the `@settitle' command). The left part of the right-hand (odd-numbered) page contains the name of the chapter, the central part is blank, and the right part contains the page number. The two pages, side by side as in an open book, look like this: _______________________ _______________________ | | | | | page number title | | chapter page number | | | | | | Start of text ... | | More text ... | | ... | | ... | | | | | The chapter name is preceded by the word `Chapter', the chapter number and a colon. This makes it easier to keep track of where you are in the manual. File: texinfo, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings Specifying the Type of Heading ============================== TeX does not begin to generate page headings for a standard Texinfo file until it reaches the `@end titlepage' command. Thus, the title and copyright pages are not numbered. The `@end titlepage' command causes TeX to begin to generate page headings according to a standard format specified by the `@setchapternewpage' command that precedes the `@titlepage' section. There are four possibilities: No `@setchapternewpage' command Cause TeX to specify the single-sided heading format, with chapters on new pages. This is the same as `@setchapternewpage on'. `@setchapternewpage on' Specify the single-sided heading format, with chapters on new pages. `@setchapternewpage off' Cause TeX to start a new chapter on the same page as the last page of the preceding chapter, after skipping some vertical whitespace. Also cause TeX to typeset for single-sided printing. (You can override the headers format with the `@headings double' command; see *Note The `@headings' Command: headings on off.) `@setchapternewpage odd' Specify the double-sided heading format, with chapters on new pages. Texinfo lacks an `@setchapternewpage even' command. File: texinfo, Node: Custom Headings, Prev: Heading Choice, Up: Headings How to Make Your Own Headings ============================= You can use the standard headings provided with Texinfo or specify your own. Texinfo provides six commands for specifying headings and footings. The `@everyheading' command and `@everyfooting' command generate page headers and footers that are the same for both even- and odd-numbered pages. The `@evenheading' command and `@evenfooting' command generate headers and footers for even-numbered (left-hand) pages; and the `@oddheading' command and `@oddfooting' command generate headers and footers for odd-numbered (right-hand) pages. Write custom heading specifications in the Texinfo file immediately after the `@end titlepage' command. Enclose your specifications between `@iftex' and `@end iftex' commands since the `texinfo-format-buffer' command may not recognize them. Also, you must cancel the predefined heading commands with the `@headings off' command before defining your own specifications. Here is how to tell TeX to place the chapter name at the left, the page number in the center, and the date at the right of every header for both even- and odd-numbered pages: @iftex @headings off @everyheading @thischapter @| @thispage @| @today{} @end iftex You need to divide the left part from the central part and the central part from the right had part by inserting `@|' between parts. Otherwise, the specification command will not be able to tell where the text for one part ends and the next part begins. Each part can contain text or @-commands. The text is printed as if the part were within an ordinary paragraph in the body of the page. The @-commands replace themselves with the page number, date, chapter name, or whatever. Here are the six heading and footing commands: `@everyheading LEFT @| CENTER @| RIGHT' `@everyfooting LEFT @| CENTER @| RIGHT' The `every' commands specify the format for both even- and odd-numbered pages. These commands are for documents that are printed on one side of each sheet of paper, or for documents in which you want symmetrical headers or footers. `@evenheading LEFT @| CENTER @| RIGHT' `@oddheading LEFT @| CENTER @| RIGHT' `@evenfooting LEFT @| CENTER @| RIGHT' `@oddfooting LEFT @| CENTER @| RIGHT' The `even' and `odd' commands specify the format for even-numbered pages and odd-numbered pages. These commands are for books and manuals that are printed on both sides of each sheet of paper. Use the `@this...' series of @-commands to provide the names of chapters and sections and the page number. You can use the `@this...' commands in the left, center, or right portions of headers and footers, or anywhere else in a Texinfo file so long as they are between `@iftex' and `@end iftex' commands. Here are the `@this...' commands: `@thispage' Expands to the current page number. `@thischaptername' Expands to the name of the current chapter. `@thischapter' Expands to the number and name of the current chapter, in the format `Chapter 1: Title'. `@thistitle' Expands to the name of the document, as specified by the `@settitle' command. `@thisfile' For `@include' files only: expands to the name of the current `@include' file. If the current Texinfo source file is not an `@include' file, this command has no effect. This command does *not* provide the name of the current Texinfo source file unless it is an `@include' file. (*Note Include Files::, for more information about `@include' files.) You can also use the `@today{}' command, which expands to the current date, in `1 Jan 1900' format. Other @-commands and text are printed in a header or footer just as if they were in the body of a page. It is useful to incorporate text, particularly when you are writing drafts: @iftex @headings off @everyheading @emph{Draft!} @| @thispage @| @thischapter @everyfooting @| @| Version: 0.27: @today{} @end iftex Beware of overlong titles: they may overlap another part of the header or footer and blot it out. File: texinfo, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top Formatting Mistakes ******************* Besides mistakes in the content of your documentation, there are two kinds of mistake you can make with Texinfo: you can make mistakes with @-commands, and you can make mistakes with the structure of the nodes and chapters. Emacs has two tools for catching the @-command mistakes and two for catching structuring mistakes. For finding problems with @-commands, you can run TeX or a region formatting command on the region that has a problem; indeed, you can run these commands on each region as you write it. For finding problems with the structure of nodes and chapters, you can use `C-c C-s' (`texinfo-show-structure') and the related `occur' command and you can use the `M-x Info-validate' command. * Menu: * makeinfo preferred:: `makeinfo' finds errors. * Debugging with Info:: How to catch errors with Info formatting. * Debugging with TeX:: How to catch errors with TeX formatting. * Using texinfo-show-structure:: How to use `texinfo-show-structure'. * Using occur:: How to list all lines containing a pattern. * Running Info-Validate:: How to find badly referenced nodes. File: texinfo, Node: makeinfo preferred, Next: Debugging with Info, Up: Catching Mistakes `makeinfo' Find Errors ====================== The `makeinfo' program does an excellent job of catching errors and reporting them--far better than `texinfo-format-region' or `texinfo-format-buffer'. In addition, the various functions for automatically creating and updating node pointers and menus remove many opportunities for human error. If you can, use the updating commands to create and insert pointers and menus. These prevent many errors. Then use `makeinfo' (or its Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer') to format your file and check for other errors. This is the best way to work with Texinfo. But if you cannot use `makeinfo', or your problem is very puzzling, then you may want to use the tools described in this appendix. File: texinfo, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo preferred, Up: Catching Mistakes Catching Errors with Info Formatting ==================================== After you have written part of a Texinfo file, you can use the `texinfo-format-region' or the `makeinfo-region' command to see whether the region formats properly. Most likely, however, you are reading this section because for some reason you cannot use the `makeinfo-region' command; therefore, the rest of this section presumes that you are using `texinfo-format-region'. If you have made a mistake with an @-command, `texinfo-format-region' will stop processing at or after the error and display an error message. To see where in the buffer the error occurred, switch to the `*Info Region*' buffer; the cursor will be in a position that is after the location of the error. Also, the text will not be formatted after the place where the error occurred (or more precisely, where it was detected). For example, if you accidentally end a menu with the command `@end menus' with an `s' on the end, instead of with `@end menu', you will see an error message that says: @end menus is not handled by texinfo The cursor will stop at the point in the buffer where the error occurs, or not long after it. The buffer will look like this: ---------- Buffer: *Info Region* ---------- * Menu: * Using texinfo-show-structure:: How to use `texinfo-show-structure' to catch mistakes. * Running Info-Validate:: How to check for unreferenced nodes. @end menus -!- ---------- Buffer: *Info Region* ---------- The `texinfo-format-region' command sometimes provides slightly odd error messages. For example, the following cross reference fails to format: (@xref{Catching Mistakes, for more info.) In this case, `texinfo-format-region' detects the missing closing brace but displays a message that says `Unbalanced parentheses' rather than `Unbalanced braces'. This is because the formatting command looks for mismatches between braces as if they were parentheses. Sometimes `texinfo-format-region' fails to detect mistakes. For example, in the following, the closing brace is swapped with the closing parenthesis: (@xref{Catching Mistakes), for more info.} Formatting produces: (*Note for more info.: Catching Mistakes) The only way for you to detect this error is to realize that the reference should have looked like this: (*Note Catching Mistakes::, for more info.) Incidentally, if you are reading this node in Info and type `f RET' (`Info-follow-reference'), you will generate an error message that says: No such node: "Catching Mistakes) The only way ... This is because Info perceives the example of the error as the first cross reference in this node and if you type a RET immediately after typing the Info `f' command, Info will attempt to go to the referenced node. If you type `f catch TAB RET', Info will complete the node name of the correctly written example and take you to the `Catching Mistakes' node. (If you try this, you can return from the `Catching Mistakes' node by typing `l' (`Info-last').) File: texinfo, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes Catching Errors with TeX Formatting =================================== You can also catch mistakes when you format a file with TeX. Usually, you will want to do this after you have run `texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same file, because `texinfo-format-buffer' sometimes displays error messages that make more sense than TeX. (*Note Debugging with Info::, for more information.) For example, TeX was run on a Texinfo file, part of which is shown here: ---------- Buffer: texinfo.texi ---------- name of the texinfo file as an extension. The @samp{??} are `wildcards' that cause the shell to substitute all the raw index files. (@xref{sorting indices, for more information about sorting indices.)@refill ---------- Buffer: texinfo.texi ---------- (The cross reference lacks a closing brace.) TeX produced the following output, after which it stopped: ---------- Buffer: *texinfo-tex-shell* ---------- Runaway argument? {sorting indices, for more information about sorting indices.) @refill @ETC. ! Paragraph ended before @xref was complete. <to be read again> @par l.27 ? ---------- Buffer: *texinfo-tex-shell* ---------- In this case, TeX produced an accurate and understandable error message: Paragraph ended before @xref was complete. `@par' is an internal TeX command of no relevance to Texinfo. `l.27' means that TeX detected the problem on line 27 of the Texinfo file. The `?' is the prompt TeX uses in this circumstance. Unfortunately, TeX is not always so helpful, and sometimes you must truly be a Sherlock Holmes to discover what went wrong. In any case, if you run into a problem like this, you can do one of three things. 1. You can tell TeX to continue running and ignore just this error by typing RET at the `?' prompt. 2. You can tell TeX to continue running and to ignore all errors as best it can by typing `r RET' at the `?' prompt. This is often the best thing to do. However, beware: the one error may produce a cascade of additional error messages as its consequences are felt through the rest of the file. (To stop TeX when it is producing such an avalanche of error messages, type `C-d' (or `C-c C-d', if you running a shell inside Emacs.)) 3. You can tell TeX to stop this run by typing `x RET' at the `?' prompt. Please note that if you are running TeX inside Emacs, you need to switch to the shell buffer and line at which TeX offers the `?' prompt. Sometimes TeX will format a file without producing error messages even though there is a problem. This usually occurs if a command is not ended but TeX is able to continue processing anyhow. For example, if you fail to end an itemized list with the `@end itemize' command, TeX will write a DVI file that you can print out. The only error message that TeX will give you is the somewhat mysterious comment that (@end occurred inside a group at level 1) However, if you print the DVI file, you will find that the text of the file that follows the itemized list is entirely indented as if it were part of the last item in the itemized list. The error message is the way TeX says that it expected to find an `@end' command somewhere in the file; but that it could not determine where it was needed. Another source of notoriously hard-to-find errors is a missing `@end group' command. If you ever are stumped by incomprehensible errors, look for a missing `@end group' command first. If the Texinfo file lacks header lines, TeX may stop in the beginning of its run and display output that looks like the following. The `*' indicates that TeX is waiting for input. This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 87.10.25) (test.texinfo [1]) * In this case, simply type `\end RET' after the asterisk. Then write the header lines in the Texinfo file and run the TeX command again. (Note the use of the backslash, `\'. TeX uses `\' instead of `@'; and in this circumstance, you are working directly with TeX not with Texinfo.) File: texinfo, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes Using `texinfo-show-structure' ============================== It is not always easy to keep track of the nodes, chapters, sections, and subsections of a Texinfo file. This is especially true if you are revising or adding to a Texinfo file that someone else has written. In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command lists all the lines that begin with the @-commands that specify the structure: `@chapter', `@section', `@appendix', and so on. With an argument (`C-u' as prefix argument, if interactive), the command also shows the `@node' lines. The `texinfo-show-structure' command is bound to `C-c C-s' in Texinfo mode, by default. The lines are displayed in a buffer called the `*Occur*' buffer. For example, when `texinfo-show-structure' was run on an earlier version of this appendix, it produced the following: Lines matching "^@\$chapter \\|sect\\|sub\\|unnum\\|major\\| heading \\|appendix\$" in buffer texinfo.texi. 4:@appendix Formatting Mistakes 52:@appendixsec Catching Errors with Info Formatting 222:@appendixsec Catching Errors with @TeX{} Formatting 338:@appendixsec Using @code{texinfo-show-structure} 407:@appendixsubsec Using @code{occur} 444:@appendixsec Finding Badly Referenced Nodes 513:@appendixsubsec Running @code{Info-validate} 573:@appendixsubsec Splitting a File Manually This says that lines 4, 52, and 222 of `texinfo.texi' begin with the `@appendix', `@appendixsec', and `@appendixsec' commands respectively. If you move your cursor into the `*Occur*' window, you can position the cursor over one of the lines and use the `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the corresponding spot in the Texinfo file. *Note Using Occur: (emacs)Other Repeating Search, for more information about `occur-mode-goto-occurrence'. The first line in the `*Occur*' window describes the "regular expression" specified by TEXINFO-HEADING-PATTERN. This regular expression is the pattern that `texinfo-show-structure' looks for. *Note Using Regular Expressions: (emacs)Regexps, for more information. When you invoke the `texinfo-show-structure' command, Emacs will display the structure of the whole buffer. If you want to see the structure of just a part of the buffer, of one chapter, for example, use the `C-x n' (`narrow-to-region') command to mark the region. (*Note Narrowing: (emacs)Narrowing.) This is how the example used above was generated. (To see the whole buffer again, use `C-x w' (`widen').) If you call `texinfo-show-structure' with a prefix argument by typing `C-u C-c C-s', it will list lines beginning with `@node' as well as the lines beginning with the @-sign commands for `@chapter', `@section', and the like. You can remind yourself of the structure of a Texinfo file by looking at the list in the `*Occur*' window; and if you have mis-named a node or left out a section, you can correct the mistake. File: texinfo, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes Using `occur' ============= Sometimes the `texinfo-show-structure' command produces too much information. Perhaps you want to remind yourself of the overall structure of a Texinfo file, and are overwhelmed by the detailed list produced by `texinfo-show-structure'. In this case, you can use the `occur' command directly. To do this, type `M-x occur' and then, when prompted, type a "regexp", a regular expression for the pattern you want to match. (*Note Regular Expressions: ( emacs)Regexps.) The `occur' command works from the current location of the cursor in the buffer to the end of the buffer. If you want to run `occur' on the whole buffer, place the cursor at the beginning of the buffer. For example, to see all the lines that contain the word `@chapter' in them, just type `@chapter'. This will produce a list of the chapters. It will also list all the sentences with `@chapter' in the middle of the line. If you want to see only those lines that start with the word `@chapter', type `^@chapter' when prompted by `occur'. If you want to see all the lines that end with a word or phrase, end the last word with a `$'; for example, `catching mistakes$'. This can be helpful when you want to see all the nodes that are part of the same chapter or section and therefore have the same `Up' pointer. *Note Using Occur: (emacs)Other Repeating Search, for more information. File: texinfo, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes Finding Badly Referenced Nodes ============================== You can use the `Info-validate' command to check whether any of the `Next', `Previous', `Up' or other node pointers fail to point to a node. This command checks that every node pointer points to an existing node. The `Info-validate' command works only on Info files, not on Texinfo files. The `makeinfo' program validates pointers automatically, so you do not need to use the `Info-validate' command if you are using `makeinfo'. You only may need to use `Info-validate' if you are unable to run `makeinfo' and instead must create an Info file using `texinfo-format-region' or `texinfo-format-buffer', or if you write an Info file from scratch. * Menu: * Using Info-validate:: How to run `Info-validate'. * Unsplit:: How to create an unsplit file. * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. File: texinfo, Node: Using Info-validate, Next: Unsplit, Up: Running Info-Validate Running `Info-validate' ----------------------- To use `Info-validate', visit the Info file you wish to check and type: M-x Info-validate (Note that the `Info-validate' command requires an upper case `I'. You may also need to create a tag table before running `Info-validate'. *Note Tagifying::.) If your file is valid, you will receive a message that says "File appears valid". However, if you have a pointer that does not point to a node, error messages will be displayed in a buffer called `*problems in info file*'. For example, `Info-validate' was run on a test file that contained only the first node of this manual. One of the messages said: In node "Overview", invalid Next: Texinfo Mode This meant that the node called `Overview' had a `Next' pointer that did not point to anything (which was true in this case, since the test file had only one node in it). Now suppose we add a node named `Texinfo Mode' to our test case but we do not specify a `Previous' for this node. Then we will get the following error message: In node "Texinfo Mode", should have Previous: Overview This is because every `Next' pointer should be matched by a `Previous' (in the node where the `Next' points) which points back. `Info-validate' also checks that all menu entries and cross references point to actual nodes. Note that `Info-validate' requires a tag table and does not work with files that have been split. (The `texinfo-format-buffer' command automatically splits files larger than 100,000 bytes.) In order to use `Info-validate' on a large file, you must run `texinfo-format-buffer' with an argument so that it does not split the Info file; and you must create a tag table for the unsplit file. File: texinfo, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate Creating an Unsplit File ------------------------ You can run `Info-validate' only on a single Info file that has a tag table. The command will not work on the indirect subfiles that are generated when a master file is split. If you have a large file (longer than 70,000 bytes or so), you need to run the `texinfo-format-buffer' or `makeinfo-buffer' command in such a way that it does not create indirect subfiles. You will also need to create a tag table for the Info file. After you have done this, you can run `Info-validate' and look for badly referenced nodes. The first step is to create an unsplit Info file. To prevent `texinfo-format-buffer' from splitting a Texinfo file into smaller Info files, give a prefix to the `M-x texinfo-format-buffer' command: C-u M-x texinfo-format-buffer or else C-u C-c C-e C-b When you do this, Texinfo will not split the file and will not create a tag table for it. File: texinfo, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate Tagifying a File ---------------- After creating an unsplit Info file, you must create a tag table for it. Visit the Info file you wish to tagify and type: M-x Info-tagify (Note the upper case I in `Info-tagify'.) This creates an Info file with a tag table that you can validate. The third step is to validate the Info file: M-x Info-validate (Note the upper case I in `Info-validate'.) In brief, the steps are: C-u M-x texinfo-format-buffer M-x Info-tagify M-x Info-validate After you have validated the node structure, you can rerun `texinfo-format-buffer' in the normal way so it will construct a tag table and split the file automatically, or you can make the tag table and split the file manually. File: texinfo, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate Splitting a File Manually ------------------------- You should split a large file or else let the `texinfo-format-buffer' or `makeinfo-buffer' command do it for you automatically. (Generally you will let one of the formatting commands do this job for you. *Note Create an Info File::.) The split-off files are called the indirect subfiles. Info files are split to save memory. With smaller files, Emacs does not have make such a large buffer to hold the information. If an Info file has more than 30 nodes, you should also make a tag table for it. *Note Using Info-validate::, for information about creating a tag table. (Again, tag tables are usually created automatically by the formatting command; you only need to create a tag table yourself if you are doing the job manually. Most likely, you will do this for a large, unsplit file on which you have run `Info-validate'.) Visit the Info file you wish to tagify and split and type the two commands: M-x Info-tagify M-x Info-split (Note that the `I' in `Info' is upper case.) When you use the `Info-split' command, the buffer is modified into a (small) Info file which lists the indirect subfiles. This file should be saved in place of the original visited file. The indirect subfiles are written in the same directory the original file is in, with names generated by appending `-' and a number to the original file name. The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles. File: texinfo, Node: Refilling Paragraphs, Next: Command Syntax, Prev: Catching Mistakes, Up: Top Refilling Paragraphs ******************** The `@refill' command refills and, optionally, indents the first line of a paragraph.(1) The `@refill' command is no longer important, but we describe it here because you once needed it. You will see it in many old Texinfo files. Without refilling, paragraphs containing long @-constructs may look bad after formatting because the formatter removes @-commands and shortens some lines more than others. In the past, neither the `texinfo-format-region' command nor the `texinfo-format-buffer' command refilled paragraphs automatically. The `@refill' command had to be written at the end of every paragraph to cause these formatters to fill them. (Both TeX and `makeinfo' have always refilled paragraphs automatically.) Now, all the Info formatters automatically fill and indent those paragraphs that need to be filled and indented. The `@refill' command causes `texinfo-format-region' and `texinfo-format-buffer' to refill a paragraph in the Info file *after* all the other processing has been done. For this reason, you can not use `@refill' with a paragraph containing either `@*' or `@w{ ... }' since the refilling action will override those two commands. The `texinfo-format-region' and `texinfo-format-buffer' commands now automatically append `@refill' to the end of each paragraph that should be filled. They do not append `@refill' to the ends of paragraphs that contain `@*' or `@w{ ...}' and therefore do not refill or indent them. ---------- Footnotes ---------- (1) Perhaps the command should have been called the `@refillandindent' command, but `@refill' is shorter and the name was chosen before indenting was possible. File: texinfo, Node: Command Syntax, Next: Obtaining TeX, Prev: Refilling Paragraphs, Up: Top @-Command Syntax **************** The character `@' is used to start special Texinfo commands. (It has the same meaning that `\' has in PlainTeX.) Texinfo has four types of @-command: 1. Non-alphabetic commands. These commands consist of an @ followed by a punctuation mark or other character that is not part of the alphabet. Non-alphabetic commands are almost always part of the text within a paragraph, and never take any argument. The two characters (@ and the other one) are complete in themselves; none is followed by braces. The non-alphabetic commands are: `@.', `@:', `@*', `@@', `@{', and `@}'. 2. Alphabetic commands that do not require arguments. These commands start with @ followed by a word followed by left- and right-hand braces. These commands insert special symbols in the document; they do not require arguments. For example, `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and `@bullet{}' => `*'. 3. Alphabetic commands that require arguments within braces. These commands start with @ followed by a letter or a word, followed by an argument within braces. For example, the command `@dfn' indicates the introductory or defining use of a term; it is used as follows: `In Texinfo, @@-commands are @dfn{mark-up} commands.' 4. Alphabetic commands that occupy an entire line. These commands occupy an entire line. The line starts with @, followed by the name of the command (a word); for example, `@center' or `@cindex'. If no argument is needed, the word is followed by the end of the line. If there is an argument, it is separated from the command name by a space. Braces are not used. Thus, the alphabetic commands fall into classes that have different argument syntaxes. You cannot tell to which class a command belongs by the appearance of its name, but you can tell by the command's meaning: if the command stands for a glyph, it is in class 2 and does not require an argument; if it makes sense to use the command together with other text as part of a paragraph, the command is in class 3 and must be followed by an argument in braces; otherwise, it is in class 4 and uses the rest of the line as its argument. The purpose of having a different syntax for commands of classes 3 and 4 is to make Texinfo files easier to read, and also to help the GNU Emacs paragraph and filling commands work properly. There is only one exception to this rule: the command `@refill', which is always used at the end of a paragraph immediately following the final period or other punctuation character. `@refill' takes no argument and does *not* require braces. `@refill' never confuses the Emacs paragraph commands because it cannot appear at the beginning of a line. File: texinfo, Node: Obtaining TeX, Next: New Features, Prev: Command Syntax, Up: Top How to Obtain TeX ***************** TeX is freely redistributable. You can obtain TeX for Unix systems from the University of Washington for a distribution fee. To order a full distribution, send $200.00 for a 1/2-inch 9-track 1600 bpi (`tar' or `cpio') tape reel, or $210.00 for a 1/4-inch 4-track QIC-24 (`tar' or `cpio') cartridge, to: Northwest Computing Support Center DR-10, Thomson Hall 35 University of Washington Seattle, Washington 98195 Please make checks payable to the University of Washington. Prepaid orders are preferred but purchase orders are acceptable; however, purchase orders carry an extra charge of $10.00, to pay for processing. Overseas sites: please add to the base cost $20.00 for shipment via air parcel post, or $30.00 for shipment via courier. Please check with the Northwest Computing Support Center at the University of Washington for current prices and formats: telephone: (206) 543-6259 email: elisabet@max.u.washington.edu File: texinfo, Node: New Features, Next: Command and Variable Index, Prev: Obtaining TeX, Up: Top Second Edition Features *********************** The second edition of the Texinfo manual describes more than 20 new Texinfo mode commands and more than 50 previously undocumented Texinfo @-commands. This edition is more than twice the length of the first edition. Here is a brief description of the new commands. * Menu: * New Texinfo Mode Commands:: The updating commands are especially useful. * New Commands:: Many newly described @-commands.