diff options
Diffstat (limited to 'info/texinfo-1')
| -rw-r--r-- | info/texinfo-1 | 1283 |
1 files changed, 1283 insertions, 0 deletions
diff --git a/info/texinfo-1 b/info/texinfo-1 new file mode 100644 index 00000000000..1471ecc041b --- /dev/null +++ b/info/texinfo-1 @@ -0,0 +1,1283 @@ +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. + + |