OpenStep 4.2

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

/ OpenStep 4.2 / Openstep-4.2-Intel-User.iso / usr / lib / emacs / info / texinfo-1 < prev next >

Wrap

Text File | 1991-01-10 | 49KB | 1,284 lines

Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from input file texinfo.texinfo. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line help and a printed manual. This is edition 1.1 of the Texinfo documentation, and is for the Texinfo that is distributed as part of Version 18 of GNU Emacs. Copyright (C) 1988 Free Software Foundation, Inc. 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: Top, Next: License, Prev: (dir), Up: (dir) * Menu: * License:: Licensing information. * Overview:: What is Texinfo? * Texinfo Mode:: Special features in GNU Emacs. * Beginning a File:: What to put at the beginning of a Texinfo file. * Ending a File:: What to put at the end of a Texinfo file. * Structuring:: How to make nodes and chapters. * Quotations and Examples:: How to insert quotations and examples. * Lists and Tables:: How to make lists and tables. * Cross References:: How to make cross references. * Formatting Paragraphs:: How to format paragraphs. * Marking Text:: How to mark code, definitions, variables etc. * Conditionals:: Putting text in only Info or the printed work. * Printing Hardcopy:: How to print a hardcopy of the manual. * Creating an Info File:: How to create an on-line Info file. * Catching Mistakes:: How to find problems. Indices, nodes containing large menus * Command Index:: An item for each @-command. * Concept Index:: An item for each concept. A detailed node listing Overview * Info File:: Characteristics of the Info file. * Printed Manual:: Characteristics of the printed manual. * Conventions:: General syntactic conventions. * Short Sample:: A short sample Texinfo file. Using Texinfo Mode * Info on a Region:: Formatting a region for Info. * Showing the Structure:: Showing the structure of a file. * Inserting:: Inserting frequently used commands. Beginning a Texinfo File. * First Line:: The first line of a Texinfo file. * Start-of-Header:: Identifying the start of the header. * Setfilename:: Specifying the name of the Info file. * Settitle:: Specifying the title used by the headings. * Setchapternewpage:: Starting chapters on odd numbered pages. * Titlepage:: The title and copyright page. * Center:: Centering a line. * Copyright & Printed Permissions:: Ensuring free distributability. * Top Node:: The master menu. * License and Distribution:: Your are free to copy and distribute this. Ending a Texinfo File * Contents:: Generating tables of contents. * Indices:: Generating indices. * Index Entries:: Defining the entries of an index. * Combining Indices:: Putting two or more indices together. * Printing Indices & Menus:: Printing an index and generating menus. Node and Chapter Structuring * Chapter:: Creating a chapter. * Unnumbered and Appendix:: Chapter-like parts. * Section:: Creating sections * Subsection:: Creating subsections. * Subsubsection:: Creating subsubsections. * Node:: Creating nodes. * Menu:: Creating menus. Making quotations and examples * Quotation:: Inserting long quotations. * Example:: Inserting examples of code and the like. * Display:: Inserting displayed text. Making lists and two column tables * Itemize:: Creating itemized lists. * Enumerate:: Creating enumerated lists. * Table:: Creating two column tables. * Itemx:: Putting an extra item in the first column of a table. Making Cross References * Xref:: Making a regular cross reference. * Pxref:: Making a parenthetical cross reference. * Inforef:: Making a cross reference to an Info file. Formatting Paragraphs * Refilling & Noindent:: Refilling paragraphs and preventing indentation * Refill:: Using the `@refill' command. * Noindent:: Using the `@noindent' command. Breaks, Blank Lines and Groups * Line Breaks:: Inserting line breaks in TeX. * Sp:: Inserting blank lines. * Br:: Inserting paragraph breaks. * W:: Preventing line breaks. * Page:: Starting new pages. * Group:: Holding text together on one page. * Need:: Keeping text together. Marking Text Within a Paragraph * Code:: A literal example of a piece of a program. * Samp:: A literal example of a sequence of characters. * File:: The name of a file. * Kbd:: The names of keys or else characters you type. * Key:: The conventional name for a key on a keyboard. * Ctrl:: Indicates the ASCII control character. * Var:: A variable. * Dfn:: The introductory or defining use of a term. * Cite:: The name of a book. Inserting Braces, `@' and Periods * Braces Atsigns Periods:: Inserting braces, `@' and periods. * Dots Bullets Tex:: Inserting dots, bullets and the TeX logo * Emphasis:: Emphasizing text. Emphasizing Text * Emph and Strong:: Emphasizing text. * Fonts:: Selecting italic, bold or typewriter fonts. Creating an Info File * Installing an Info File:: Putting the Info file in the `info' directory. Catching Mistakes * Debugging with Info:: Catching errors with info formatting. * Using the Emacs Lisp Debugger:: Using the Emacs Lisp Debugger * Debugging with Tex:: Catching errors with TeX formatting. * Using texinfo-show-structure:: Using `texinfo-show-structure' to catch mistakes. * Using Occur:: Using `occur' to catch mistakes. * Running Info-Validate:: Checking for unreferenced nodes. Finding badly referenced nodes * Info-Validating a Large File:: Running `Info-validate' on a large file. * Splitting:: Splitting a file manually. Appendices * Command Syntax:: Details about the syntax. * Include Files:: Making one printed file out of several Info files. * TeX Input:: Where TeX finds its `\input' file. * Sample Permissions:: You may copy GNU Software. * Ifinfo Permissions:: What to put in the `ifinfo' section. * Titlepage Permissions:: What to put in the `@titlepage' section. File: texinfo, Node: License, Next: Overview, Prev: Top, Up: Top Licensing Information ********************* The programs currently being distributed that relate to Texinfo include two portions of GNU Emacs, plus two other separate programs (`texindex' and `texinfo.tex'). These programs are "free"; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you. Specifically, we want to make sure that you have the right to give away copies of the programs that relate to Texinfo, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the Texinfo related programs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to Texinfo. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public Licenses that accompany them. The programs that are part of GNU Emacs are covered by the GNU Emacs copying terms (*note : (emacs)License.), and other programs are covered by licenses that are contained in their source files. File: texinfo, Node: Overview, Next: Texinfo Mode, Prev: License, Up: Top Overview of Texinfo ******************* Texinfo is a documentation system that uses a single source file for both on-line help and a printed manual. This means that instead of writing two different documents, one for the on-line help and the other for the printed manual, only one document needs to be written. When the system is revised, only one file has to be revised. Using Texinfo, you can create a document with the normal features of a book such as chapters, sections, cross references and indices. The chapters and sections of the printed manual can be made to correspond to the nodes of the on-line help. The cross references and indices can be used in both the on-line help and in the printed document. Indices are generated semi-automatically. The ``GNU Emacs Manual'' is a good example of a Texinfo file. To make the printed manual, the Texinfo source file is processed by the TeX typesetting program; the resulting DVI file can be typeset and printed as a book. To make the on-line help, the Texinfo source file is by processed the `M-x texinfo-format-buffer' command; the resulting Info file is installed in the `info' directory. Since the Texinfo source file is used for a dual task--to create both the on-line help and the printed manual--it must be written in a special format that uses @-commands (words preceded by an `@') to indicate chapters, sections, nodes, examples, index entries and the like. Before writing a Texinfo source file, you should be familiar with the on-line Info documentation reading program. (*note info: (info)Info, for more information.) If you are writing a document that will be both on-line and printed, you will need both Info and TeX. To make an Info file, you use the `M-x texinfo-format-buffer' command in GNU Emacs. To make a printed manual, you need to use TeX, a powerful, sophisticated typesetting program written by Donald Knuth. TeX is freely distributable. It is written in a dialect of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the TeX distribution) in C. (For information about getting TeX, *note : (emacs)TeX Mode.) When TeX processes a Texinfo source file, TeX makes use of a macro definitions file called `texinfo.tex' that comes with the GNU Emacs distribution in the `emacs/man' sources directory. (The first line of every Texinfo file has a command that says `\input texinfo'; this tells TeX to use the `texinfo.tex' file.) If the `texinfo.tex' file has not already been copied to the directory which contains the other TeX macro definition files when Emacs was installed, you will probably want to copy it to that directory. Usually, this is the `/usr/lib/tex/macros' directory. For more information, *note @TeX{} Input Initialization: TeX Input. Documentation for GNU utilities and libraries should be written in Texinfo format. * Menu: * Info File:: Characteristics of the Info file. * Printed Manual:: Characteristics of the Printed Manual. * Conventions:: General Syntactic Conventions. * Short Sample:: A short sample Texinfo file. File: texinfo, Node: Info File, Next: Printed Manual, Up: Overview Characteristics of the Info file ================================ A Texinfo file can be transformed into a printed manual and an on-line Info file. An on-line Info file is a file formatted so that the Info documentation reading program can operate on it. Info files are divided into pieces called "nodes", each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to the other nodes to which the current node points. *note info: (info)Info, for more information about using Info. Normally, most of the nodes are arranged in a tree which branches down. Each node may have any number of child nodes that describe subtopics of the node's topic. The names of these child nodes, if any, are listed in a "menu" within the parent node; this allows certain Info commands to be used to move to one of the child nodes. Each child node records the parent node name, as its `Up' pointer. Thus, if a node were at the logical level of a `chapter', its child nodes would be `sections'; likewise, the child nodes of a section would be subsections. The root of the tree is the top node of the file, through which users enter the file from the Info directory. By convention, this node is always called `Top'. This node normally contains just a brief summary of the file's purpose, and a large menu through which the rest of the file is reached. Generally you enter the Info file from the top; then you can either traverse the file systematically by going from node to node or you can search large menus that correspond to indices and go directly to the node that has the information you want. If you want to read through an Info file in sequence, as if it were a printed manual, you can get the whole file with the advanced Info command `g *'. (*note info: (info)Expert.) All the children of any one parent are linked together in a bidirectional chain of `Next' and `Previous' pointers. This means that all the nodes that are logically parallel to sections within a chapter are all linked together. Normally the order in this chain is the same as the order of the children in the parent's menu. The last child has no `Next' pointer, and the first child normally has the parent as its `Previous' pointer (as well as its `Up' pointer, of course). Structuring the nodes in a tree is a matter of convention, not a requirement. In fact, the `Up', `Previous' and `Next' pointers of a node can point to any other nodes, and the menu can contain any other nodes. The structure of nodes can be any directed graph. But it is usually more comprehensible to make it a tree. Info provides another kind of pointer between nodes, called a reference, that can be sprinkled through the text of a node. This is usually the best way to represent links that do not fit the tree structure. Most often the nodes fall into a strict tree structure that corresponds to the structure of chapters and sections in the printed manual. But there are times when this is not right for the material being discussed. Therefore, Texinfo uses separate commands to specify the node structure of the Info file and the section structure of the printed manual. Also, Texinfo requires that you specify menus explicitly, rather than generate them automatically based on an assumed tree structure. File: texinfo, Node: Printed Manual, Next: Conventions, Prev: Info File, Up: Top Characteristics of the Printed Manual ===================================== A Texinfo file can be formatted and typeset as a printed manual. The printed manual will be the same as any other book; it will have a title page, copyright page, table of contents, and preface as you would expect, as well as chapters, numbered or unnumbered sections and subsections, not to mention page headers, cross references and indices. Texinfo can be used for writing a book without ever having the intention of converting it into on-line help. Texinfo can be used for writing a novel; and it can even be used to write a memo, although this application is not recommended since electronic mail is so much easier. Texinfo uses the formatting language called TeX for typesetting. A file called `texinfo.tex' contains information (definitions or "macros") that TeX uses when it typesets a Texinfo file. (The macros tell TeX how to convert the Texinfo @-commands to TeX commands which TeX can then process to create the typeset document.) `texinfo.tex' contains the specifications for printing a document, either with 7 inch by 9.25 inch pages or with 8.5 inch by 11 inch pages. (This is 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the parameters in `texinfo.tex' you can easily change the size of the printed document. In addition, you can readily change the style in which the printed document is formatted; for example, you can change the sizes and fonts used, the amount of indentation for each paragraph, the degree to which words are hyphenated, and the like. By changing the specifications, you can make a book look dignified, old and serious, or light-hearted, young and cheery. TeX is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the commands that Texinfo supports are necessarily limited. File: texinfo, Node: Conventions, Next: Short Sample, Prev: Printed Manual, Up: Overview General Syntactic Conventions ============================= Texinfo files contain a strictly limited set of constructs. The strict limits make it possible for Texinfo files to be understood both by TeX and by the code which converts them into Info files. All ASCII printing characters except `@', `{' and `}' can appear in body text in a Texinfo file and stand for themselves. `@' is the escape character which introduces commands. `{' and `}' should be used only to surround arguments to certain commands. `{' and `}' appearing anywhere else will be treated by TeX as a grouping but treated by the code that produces an Info file as themselves; this inconsistency is undesirable, so don't let it occur. To put one of these special characters into the document, put an `@' character in front of it. For example, you would insert `@@', `@{', and `@}'. It is customary in TeX to use doubled single-quote characters to begin and end quotations, `"' like these `"'. This convention should be followed in Texinfo files. Also, three hyphens in a row, `--', are used for a dash--like this. In TeX, a single or even a double hyphen produces a dash that is shorter than you want. TeX ignores the line-breaks in the input text, except for blank lines, which separate paragraphs. Info generally preserves the line breaks that are present in the input file. Therefore, break the lines in the Texinfo file the way you want them to appear in the output Info file, and let TeX take care of itself. Since Info does not normally refill paragraphs when it processes them, a line with @-commands in it will sometimes look bad after Info has run on it. To cause Info to refill the paragraph after finishing with the other processing, you need to put the command `@refill' at the end of the paragraph. (*Note Refilling paragraphs and Preventing indentation: Refilling & Noindent.) To prevent a paragraph from being indented in the printed manual, put the command `@noindent' on a line by itself before the start of the text that should not be indented. If you mark off a region of the Texinfo file with the `@iftex' and `@end iftex' commands so that the region will appear only in the printed copy, you can use TeX commands that cannot be used in the Info file. In order to be made into a printed manual, a Texinfo file *must* begin with lines that looks like \input texinfo @c -*-texinfo-*- @setfilename INFO-FILE-NAME @settitle NAME OF MANUAL The `\input texinfo' line tells TeX to use the `texinfo.tex' file. This line is usually followed by a start-of-header line (not shown here) and then by the `@setfilename INFO-FILE-NAME' and `@settitle NAME OF MANUAL' lines. These two lines are needed to provide a name for the Info file and to specify the name used on the left-hand page headers of the printed manual. The two lines that contain the `@setfilename' and `@settitle' commands usually are sandwiched between the start-of-header line and the end-of-header line. (*Note Start-of-Header::, for more information.) The start-of-header and end-of-header lines are needed if you are going to run TeX or Info on just part of a file. File: texinfo, Node: Short Sample, Prev: Conventions, Up: Overview A Short Sample Texinfo File =========================== A Texinfo file looks like the following, which is a complete but very short Texinfo file. The `@comment' command introduces comments that will not appear in either the Info file or the printed manual; they are for the person who reads the Texinfo file. The first part of the file, from `\input texinfo' through to `@end titlepage', looks more intimidating than it is. Most of the material is standard boilerplate; when you write a manual, you just put in the name of your own manual in this section. All the commands that tell TeX how to typeset the printed manual and tell `texinfo-format-buffer' how to create an Info file are preceded by `@'; thus, `@node' indicates a node and `@chapter' indicates the start of a chapter. \input texinfo @c -*-texinfo-*- @setfilename name-of-texinfo-file @settitle Name of Manual @setchapternewpage odd @ifinfo @comment The following line inserts the copyright notice @comment into the Info file. Copyright @copyright{} 1988 Free Software Foundation, Inc. @end ifinfo @comment The titlepage section does not appear in the Info file. @titlepage @sp 10 @comment The title is printed in a large font. @center @titlefont{Sample Title} @comment The following two commands start the copyright page @comment for the printed manual. This will not appear in the Info file. @page @vskip 0pt plus 1filll Copyright @copyright{} year copyright-owner @end titlepage @comment The Top node contains the master menu for the Info file. @comment This appears only in the Info file, not the printed manual. @node Top, First Chapter, (dir), (dir) @comment node-name, next, previous, up @menu * First Chapter:: The first chapter is the only chapter in this sample. @end menu @node First Chapter, , Top, Top @comment node-name, next, previous, up @chapter First Chapter @cindex Reference to First Chapter This is the contents of the first chapter. Here is a numbered list. @enumerate @item This is the first item. @item This is the second item. @end enumerate The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file like this into an Info file; and @TeX{} typesets it for a printed manual. @node Concept Index, , Previous Node, Top @comment node-name, next, previous, up @unnumbered Concept Index @printindex cp @contents @bye Here is what the contents of the first chapter of the sample look like: This is the contents of the first chapter. Here is a numbered list. 1. This is the first item. 2. This is the second item. The `M-x texinfo-format-buffer' command transforms a Texinfo file like this into an Info file; and TeX typesets it for a printed manual. File: texinfo, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top Using Texinfo Mode ****************** In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files. This means that Emacs has commands and features especially designed for working with Texinfo files. Like all other Emacs features, you can customize or enhance these as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones. The major features of Texinfo mode are: * Paragraph filling control. * A command to show the structure of the file. * Pre-defined keystroke commands to insert commonly used strings of text. * Formatting a part of a file for Info, rather than the whole file. In general, in Texinfo mode, the GNU Emacs editing commands are like those in text-mode. The major difference is that the paragraph separation variable and syntax table are set up so expression commands skip Texinfo bracket groups. This means, for example, that the `M-q' (`fill-paragraph') command will refill a paragraph but not the @-command on a line adjacent to it. By convention, the Texinfo file name shall end with the extension `.texinfo' so that Emacs knows to use Texinfo mode for editing it. * Menu: * Info on a Region:: Formatting part of a file for Info. * Showing the Structure:: Showing the structure of a file. * Inserting:: Inserting frequently used commands. File: texinfo, Node: Info on a Region, Next: Showing the Structure, Prev: Texinfo Mode, Up: Texinfo Mode Formatting a Region for Info ============================ To see what part of a Texinfo file will look like after it has been transformed into an Info file, use the command `C-c C-f' (`texinfo-format-region'). This command formats the current region of the Texinfo file for Info and writes it to a temporary buffer called `*Info Region*'. For `texinfo-format-region' to work, the file *must* include a line that has `@setfilename' in its header. The command is: `C-c C-f' texinfo-format-region File: texinfo, Node: Showing the Structure, Next: Inserting, Prev: Info on a Region, Up: Texinfo Mode Showing the Structure of a File =============================== You can show the structure of a Texinfo file by using the `C-c C-s' command (`texinfo-show-structure'). This command shows the structure of a Texinfo file by listing the lines with the @-commands for `@node', `@chapter', `@section' and the like. These lines are displayed in another window called the `*Occur*' window. In that 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. The two commands are: `C-c C-s' texinfo-show-structure `C-c C-c' occur-mode-goto-occurrence Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in with the `C-x n' (`narrow-to-region') command and `texinfo-show-structure' will work on only that region. (To see the whole buffer again, use `C-x w' (`widen').) File: texinfo, Node: Inserting, Prev: Showing the Structure, Up: Texinfo Mode Inserting Frequently Used Commands ================================== Texinfo mode provides commands that insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes. And you can insert balanced curly braces with the `M-{' command, (`texinfo-insert-braces') and later use the `M-}' command (`up-list') to move forward past the closing brace. The special commands are invoked by typing `C-c' twice and then the first letter of the @-command. `C-c C-c c' texinfo-insert-@code `C-c C-c d' texinfo-insert-@dfn `C-c C-c e' texinfo-insert-@end `C-c C-c i' texinfo-insert-@item `C-c C-c n' texinfo-insert-@node `C-c C-c s' texinfo-insert-@samp `C-c C-c v' texinfo-insert-@var `M-{' texinfo-insert-braces `M-}' up-list This list was generated by analyzing the frequency with which commands were used in the ``GNU Emacs Manual'' and the ``GDB Manual''. If you wish to add your own insert commands, you can bind a keyboard macro to a key, use abbreviations or extend the code in `texinfo.el'. File: texinfo, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top Beginning a Texinfo File ************************ Various pieces of information have to be provided to Texinfo at the beginning of a Texinfo file, such as the name of the file, the title of the document and the like. Generally, the beginning of a Texinfo file has four parts: 1. The header, marked by start-of-header and end-of-header lines, that includes the commands for naming the Texinfo file and telling TeX what definitions' file to use when processing the file. 2. A section, marked by the `@ifinfo' and `@end ifinfo' commands, that contains a short statement of what the file is about, the copyright notice and copying permissions. This section appears only in the Info file. 3. A section, marked by the `@titlepage' and `@end titlepage' commands, that contains the title page, the copyright page and copying permissions. This section appears only in the printed manual. 4. The `Top' node that contains an extensive menu for the whole Info file. The contents of this node only appear in the Info file. If the Texinfo file has a section containing licensing information and a warranty disclaimer, that section usually follows the `Top' node. The licensing section will be followed by a preface or else by the first chapter of the manual. Since the copyright notice and the copying permissions are in sections that appear only in the Info file or only in the printed manual, this information has to be repeated twice. The following sample shows what is needed. \input texinfo @c -*-texinfo-*- @comment %**start of header (This is for running Texinfo on a region.) @setfilename name-of-texinfo-file @settitle Name of Manual @setchapternewpage odd @comment %**end of header (This is for running Texinfo on a region.) @ifinfo This file documents ... Copyright @copyright{} year copyright-owner Permission is granted to ... @end ifinfo @titlepage @sp 10 @center @titlefont{Name of Manual When Printed} @sp 2 @center Subtitle, If Any @sp 2 @center Author @comment The following two commands start the copyright page. @page @vskip 0pt plus 1filll Copyright @copyright{} year copyright-owner Published by ... Permission is granted to ... @end titlepage @node Top, Overview, (dir), (dir) @menu * First Chapter:: The first chapter is usually an overview. * Second Chapter:: ... <many more menu items here> @end menu @node First Chapter, Second Chapter, top, top @comment node-name, next, previous, up @chapter First Chapter @cindex Reference to First Chapter * Menu: * Header:: Necessary first lines. * Permissions for Info:: Copyright notice and copying permissions. * Titlepage & Copyright Page:: Printed title and copyright pages. * Top Node:: The top node and master menu. * License and Distribution:: The importance of the license. File: texinfo, Node: Header, Next: Permissions for Info, Prev: Beginning a File, Up: Beginning a File The Texinfo File Header ======================= Texinfo files start with at least three lines that provide Info and TeX with necessary information. If you want to run TeX on just a part of the Texinfo File, you also have to mark these heading lines with start-of-header and end-of-header lines. * Menu: * First Line:: The first line of a Texinfo file. * Start-of-Header:: Identifying the start of the header. * Setfilename:: Specifying the name of the Info file. * Settitle:: Specifying the title used by the headings. * Setchapternewpage:: Starting chapters on odd numbered pages. * End-of-Header:: Identifying the end of the header. File: texinfo, Node: First Line, Next: Start-of-Header, Prev: Header, Up: Header The First Line of a Texinfo File -------------------------------- Every Texinfo file that is to be the top-level input to TeX must begin with a line that looks like this: \input texinfo @c -*-texinfo-*- The line serves two functions: 1. When the file is processed by TeX, it loads the macros needed for processing a Texinfo file. These are in a file called `texinfo.tex' which is usually located in the `/usr/lib/tex/macros' directory. 2. When the file is edited in GNU Emacs, it causes Texinfo mode to be used. The `\input texinfo' line should be followed by the start-of-header line. This makes it possible for the command for running TeX on a part of the Texinfo file (`texinfo-hardcopy-region') to operate. The reason for this is that the `texinfo-hardcopy-region' command will look on the line preceding the start-of-header line for the `\input texinfo' line. File: texinfo, Node: Start-of-Header, Next: Setfilename, Prev: First Line, Up: Header `start-of-header' ----------------- The start-of-header line should immediately follow the first line of the Texinfo file. The `texinfo-hardcopy-region' command will look at the line preceding the start-of-header line to find the `\input texinfo' line. Usually, the start-of-header line looks like this: @comment %**start of header (This is for running Texinfo on a region.) The reason for the odd string of characters (`%**') is so that the `texinfo-hardcopy-region' command does not accidently find something that it shouldn't when it is looking for the header. In the default configuration, the phrase `(This is for running Texinfo on a region.)' is not needed and is just included to make it easier for someone reading the Texinfo file. The start-of-header line and the end-of-header line are Texinfo mode variables that you can change. File: texinfo, Node: Setfilename, Next: Settitle, Prev: Start-of-Header, Up: Header @setfilename ------------ In order to be made into an Info file, a Texinfo file must contain a line that looks like this: @setfilename INFO-FILE-NAME This line specifies the name of the Info file to be generated. In fact, there can be other things in the file before this line, but they are ignored in the generation of an Info file. The `@setfilename' line is ignored when a printed manual is generated. File: texinfo, Node: Settitle, Next: Setchapternewpage, Prev: Setfilename, Up: Header @settitle --------- In order to be made into a printed manual file, a Texinfo file must contain a line that specifies the title of the manual. Texinfo uses this information during printing to put the title on every other page as a heading; Texinfo puts the current chapter title on the other pages. Texinfo can find the name of the chapter title from the information provided by the `@chapter' command, but you must tell it the manual title with `@settitle': @settitle TITLE This command, on a line by itself, causes TITLE to be used for the headings. Usually, you will use the same words for the title on the title page and for the title specified by this command for the headings, but the two could be different. For example, the title on the title page may be longer than the title specified by the `settitle' command. The `@settitle' command should precede everything that generates actual output. File: texinfo, Node: Setchapternewpage, Next: End-of-Header, Prev: Settitle, Up: Header @setchapternewpage ------------------ Conventionally, chapters start on the page on the right hand side of a book; and the right hand page has an odd number. To make sure that Texinfo does this, you can use the command `@setchapternewpage'. For example, to cause each chapter to start on a fresh odd-numbered page: @setchapternewpage odd Page numbering is turned on by the `@end titlepage' command, so the `@setchapternewpage' should come before it. Although it can occur anywhere in the beginning of the file, it is most convenient to put it in this location. File: texinfo, Node: End-of-Header, Prev: Setchapternewpage, Up: Header `end-of-header' --------------- The end-of-header line should follow the line containing the `@setchapternewpage' command. Usually, the end-of-header line looks like this: @comment %**end of header (This is for running Texinfo on a region.) In the default configuration, the phrase `(This is for running Texinfo on a region.)' is not needed and is just included to make it easier for someone reading the Texinfo file. The reason for the odd string of characters (`%**') is so that the `texinfo-hardcopy-region' command does not accidently find something that it shouldn't when it is looking for the header. The start-of-header line and the end-of-header line are Texinfo mode variables that you can change. File: texinfo, Node: Permissions for Info, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File Copying Permissions for Info ============================ Since the title page and the copyright page appear only in the printed copy of the manual, the same information has to inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice and copying permissions. The copyright notice should read: Copyright YEAR COPYRIGHT-OWNER and be put on a line by itself. Standard text for the copyright permissions is contained in the appendix. *Note Ifinfo Permissions::, for the complete text. File: texinfo, Node: Titlepage & Copyright Page, Next: Top Node, Prev: Permissions for Info, Up: Beginning a File The Title and Copyright Pages ============================= The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use a couple of slightly obscure TeX typesetting commands that could not be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual. * Menu: * Titlepage:: Creating a title page for the printed manual. * Center:: Centering a line. * Copyright & Printed Permissions:: Inserting the copyright notice and printed permissions. File: texinfo, Node: Titlepage, Next: Center, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page @titlepage ---------- Start the material for the title page and following copyright page with `@titlepage' on a line by itself and end it with `@end titlepage' on a line by itself. The title page and copyright page material appears only in the printed manual, not in the Info file. Also, the `@end titlepage' command starts a new page and turns on page numbering (generation of headings). Therefore, all the material that you want to appear on unnumbered pages should be put between the `@titlepage' and `@end titlepage' commands. By using the `@page' command you can force a page break within the region delineated by the `@titlepage' and `@end titlepage' commands and create more than one unnumbered page. This is how the copyright page is produced. To select a large font suitable for the title itself, you can use the command `@titlefont'. For example: @center @titlefont{Texinfo} Also, you can use `@sp' commands to adjust vertical spacing. For example: @sp 2 In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch manual. File: texinfo, Node: Center, Next: Copyright & Printed Permissions, Prev: Titlepage, Up: Titlepage & Copyright Page @center ------- A line containing `@center TEXT' produces a line of output containing TEXT, centered between the margins. File: texinfo, Node: Copyright & Printed Permissions, Prev: Center, Up: Titlepage & Copyright Page The Copyright Page and Printed Permissions ------------------------------------------ By international treaty, the copyright notice for a book should either be on the title page or on the back of the title page. Other locations in a book are not official and do not provide copyright protection. The copyright notice should include the year followed by the name of the person or organization who has the copyright. When the copyright notice is on the back of the title page, the page is not numbered. Therefore, in Texinfo, the information on the copyright page should be within the region delineated by the `@titlepage' and `@end titlepage' commands. To cause a page break, the `@page' command is used. In the sample, the `@page' command is followed by the somewhat mysterious line that reads: `@vskip 0pt plus 1filll'. This is a line that uses TeX commands to push the copyright notice and the other text on the copyright page towards the bottom of the page. The `@vskip' command means to skip lines and put in white space. The `0pt plus 1filll' means to put in zero points of mandatory white space, and as much optional white space as needed. Note the use of three `l's in the word `filll'; this is the correct use in TeX. The `@copyright{}' command generates a `c' inside a circle. The copyright notice itself has the following legally defined sequence: Copyright (C) YEAR COPYRIGHT-OWNER It is customary to put information on how to get a manual after the copyright notice (the address of the Free Software Foundation, for example) and the permissions. Note that the permissions have to be repeated here as well as in the `ifinfo' section that immediately follows the header since this section appears only in the printed manual and the `ifinfo' section appears only in the Info file. Standard text for the permissions appears in the appendix. *Note Sample Permissions::. File: texinfo, Node: Top Node, Next: License and Distribution, Prev: Titlepage & Copyright Page, Up: Beginning a File The Top Node and Master Menu ============================ The `Top' node contains an extensive, master menu for the whole Info file. The contents of this node appear only in the Info file. Nothing in this node should appear in the printed file. Since a node line by itself and a menu by itself are not printed, the contents of this node do not have to be within a region delineated by `@ifinfo' and `@end ifinfo' commands. However, any text within the node should be marked off in that manner. You may want to put a short summary before the master menu inside a region delineated by `@ifinfo' and `@end ifinfo' commands. Usually, the `Previous' and `Up' nodes refer to the top level directory of the whole Info system, with pointers to `(dir)'. Generally, the top menu is divided into parts. * The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections and the major appendices. * The second part contains entries for the indices. In an Info file, it is very useful to have indices here at the beginning of the file in the top node rather than at the end, as in a printed book. * The third and subsequent parts contain a listing of the other, lower level nodes, often ordered by chapter. This way, an inquirer can go directly to a particular node if he or she is searching for specific information. (These nodes are not required; use them if you think they are a convenience.) Each section in the menu can be introduced a descriptive line. So long as the line does not begin with an asterisk, it will not be treated as a menu item. (*Note Making Menus: Menu, for more information.) For example, the Top node of this manual looks like this (but with many more entries): @node Top, Overview, (dir), (dir) @menu * Overview:: What is Texinfo? * Texinfo Mode:: Special features in GNU Emacs. ... Indices, nodes containing large menus * Command Index:: An item for each @-command. * Concept Index:: An item for each concept. A detailed node listing Overview * Info File:: Characteristics of the Info file. * Printed Manual:: Characteristics of the printed manual. Using Texinfo Mode * Info on a Region:: Formatting a region for Info. * Showing the Structure:: Showing the structure of a file. ... ... File: texinfo, Node: License and Distribution, Prev: Top Node, Up: Beginning a File Licensing and Distribution Information ====================================== If the Texinfo file has a section containing the "General Public License" and the distribution information and a warranty disclaimer, this section usually follows the `Top' node. The licensing and distribution information and the disclaimer are followed by a preface or else by the first chapter of the manual. The licensing agreement is very important to Project GNU documentation and software. Without it, you may find that you can no longer get the software or its documentation. This sounds paradoxical, but the state of the world is such that documentation and software that does not have a "restrictive" license to make them freely distributable may be lost to the public. This has happened. For a good example of the text that could be used for the Distribution, General Public License and NO WARRANTY sections of your document, see the latest version of the ``GNU Emacs Manual''. Although a preface is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, the preface would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, a preface is put in an `@unnumbered' section. (*Note Unnumbered and Appendix::.) File: texinfo, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top Ending a Texinfo File ********************* The end of a Texinfo file should include the indices, the commands to generate detailed and summary tables of contents and the @-command that tells TeX that it has reached the end of the file. For example, a Texinfo file might be ended as follows: @node Concept Index, , Previous Node, Top @comment node-name, next, previous, up @unnumbered Concept Index @printindex cp @contents @bye The `@bye' command should be on a line by itself and every Texinfo file must end with such a line. This command terminates TeX processing and forces out unfinished pages. * Menu: * Contents:: Generating a table of contents * Indices:: Generating, sorting and printing indices File: texinfo, Node: Contents, Next: Indices, Up: Ending a File Generating a Table of Contents ============================== The commands `@chapter', `@section', etc., supply the information to make up a table of contents, but they do not cause an actual table to be generated. To do this, you must use the commands `@contents' and `@summarycontents'. `@contents' The table of contents command outputs (into a printed manual) a complete table of contents, based on the `@chapter', `@unnumbered' and other sectioning commands. This command should be used on a line by itself. `@summarycontents' The summary contents command generates a summary table of contents that lists only the chapters (and appendices and unnumbered chapters); sections, subsections and subsubsections are omitted. This command should be used on a line by itself. Only large manuals need a summary table of contents. You can use either one of these commands, or both. Each command automatically generates a chapter-like heading at the top of the page. Tables of contents should be generated at the very end of the manual, just before the `@bye' command; the tables of contents commands should follow any indices that are output, so that the indices will appear in the contents. INDICES... @summarycontents @contents @bye The commands `@contents' and `@summarycontents' are ignored when an Info file is being generated.