diff options
Diffstat (limited to 'gnu/usr.bin/texinfo/info-files/texi.info-3')
| -rw-r--r-- | gnu/usr.bin/texinfo/info-files/texi.info-3 | 1262 |
1 files changed, 0 insertions, 1262 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-3 b/gnu/usr.bin/texinfo/info-files/texi.info-3 deleted file mode 100644 index 1058a1a..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-3 +++ /dev/null @@ -1,1262 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Free Software Foundation. - - -File: texi.info, Node: titlepage, Next: titlefont center sp, 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 `@end titlepage' command starts a new page and turns on page -numbering. (*Note Page Headings: Headings, for details about how to -generate of page headings.) 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 thereby create more than one unnumbered page. -This is how the copyright page is produced. (The `@titlepage' command -might perhaps have been better named the `@titleandadditionalpages' -command, but that would have been rather long!) - - When you write a manual about a computer program, you should write -the version of the program to which the manual applies on the title -page. If the manual changes more frequently than the program or is -independent of it, you should also include an edition number(1) for the -manual. This helps readers keep track of which manual is for which -version of the program. (The `Top' node should also contain this -information; see *Note `@top': makeinfo top.) - - Texinfo provides two methods for creating a title page. One method -uses the `@titlefont', `@sp', and `@center' commands to generate a -title page in which the words on the page are centered. - - The second method uses the `@title', `@subtitle', and `@author' -commands to create a title page with black rules under the title and -author lines and the subtitle text set flush to the right hand side of -the page. With this method, you do not specify any of the actual -formatting of the title page. You specify the text you want, and -Texinfo does the formatting. You may use either method. - - ---------- Footnotes ---------- - - (1) We have found that it is helpful to refer to versions of -manuals as `editions' and versions of programs as `versions'; -otherwise, we find we are liable to confuse each other in conversation -by referring to both the documentation and the software with the same -words. - - -File: texi.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page - -`@titlefont', `@center', and `@sp' ----------------------------------- - - You can use the `@titlefont', `@sp', and `@center' commands to -create a title page for a printed document. (This is the first of the -two methods for creating a title page in Texinfo.) - - Use the `@titlefont' command to select a large font suitable for the -title itself. - - For example: - - @titlefont{Texinfo} - - Use the `@center' command at the beginning of a line to center the -remaining text on that line. Thus, - - @center @titlefont{Texinfo} - -centers the title, which in this example is "Texinfo" printed in the -title font. - - Use the `@sp' command to insert vertical space. For example: - - @sp 2 - -This inserts two blank lines on the printed page. (*Note `@sp': sp, -for more information about the `@sp' command.) - - A template for this method looks like this: - - @titlepage - @sp 10 - @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED} - @sp 2 - @center SUBTITLE-IF-ANY - @sp 2 - @center AUTHOR - ... - @end titlepage - - The spacing of the example fits an 8 1/2 by 11 inch manual. - - -File: texi.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page - -`@title', `@subtitle', and `@author' ------------------------------------- - - You can use the `@title', `@subtitle', and `@author' commands to -create a title page in which the vertical and horizontal spacing is -done for you automatically. This contrasts with the method described in -the previous section, in which the `@sp' command is needed to adjust -vertical spacing. - - Write the `@title', `@subtitle', or `@author' commands at the -beginning of a line followed by the title, subtitle, or author. - - The `@title' command produces a line in which the title is set flush -to the left-hand side of the page in a larger than normal font. The -title is underlined with a black rule. - - The `@subtitle' command sets subtitles in a normal-sized font flush -to the right-hand side of the page. - - The `@author' command sets the names of the author or authors in a -middle-sized font flush to the left-hand side of the page on a line -near the bottom of the title page. The names are underlined with a -black rule that is thinner than the rule that underlines the title. -(The black rule only occurs if the `@author' command line is followed -by an `@page' command line.) - - There are two ways to use the `@author' command: you can write the -name or names on the remaining part of the line that starts with an -`@author' command: - - @author by Jane Smith and John Doe - -or you can write the names one above each other by using two (or more) -`@author' commands: - - @author Jane Smith - @author John Doe - -(Only the bottom name is underlined with a black rule.) - - A template for this method looks like this: - - @titlepage - @title NAME-OF-MANUAL-WHEN-PRINTED - @subtitle SUBTITLE-IF-ANY - @subtitle SECOND-SUBTITLE - @author AUTHOR - @page - ... - @end titlepage - -Contrast this form with the form of a title page written using the -`@sp', `@center', and `@titlefont' commands: - - @titlepage - @sp 10 - @center @titlefont{Name of Manual When Printed} - @sp 2 - @center Subtitle, If Any - @sp 1 - @center Second subtitle - @sp 2 - @center Author - @page - ... - @end titlepage - - -File: texi.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page - -Copyright Page and Permissions ------------------------------- - - By international treaty, the copyright notice for a book should be -either on the title page or on the back of the title page. The -copyright notice should include the year followed by the name of the -organization or person who owns the copyright. - - When the copyright notice is on the back of the title page, that page -is customarily not numbered. Therefore, in Texinfo, the information on -the copyright page should be within `@titlepage' and `@end titlepage' -commands. - - Use the `@page' command to cause a page break. To push the -copyright notice and the other text on the copyright page towards the -bottom of the page, you can write a somewhat mysterious line after the -`@page' command that reads like this: - - @vskip 0pt plus 1filll - -This is a TeX command that is not supported by the Info formatting -commands. The `@vskip' command inserts whitespace. The `0pt plus -1filll' means to put in zero points of mandatory whitespace, and as -much optional whitespace as needed to push the following text to the -bottom of the page. Note the use of three `l's in the word `filll'; -this is the correct usage in TeX. - - In a printed manual, the `@copyright{}' command generates a `c' -inside a circle. (In Info, it generates `(C)'.) 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, followed by the copying permissions for the manual. - - Note that permissions must be given here as well as in the summary -segment within `@ifinfo' and `@end ifinfo' that immediately follows the -header since this text appears only in the printed manual and the -`ifinfo' text appears only in the Info file. - - *Note Sample Permissions::, for the standard text. - - -File: texi.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page - -Heading Generation ------------------- - - An `@end titlepage' command on a line by itself not only marks the -end of the title and copyright pages, but also causes TeX to start -generating page headings and page numbers. - - To repeat what is said elsewhere, Texinfo has two standard page -heading formats, one for documents which are printed on one side of -each sheet of paper (single-sided printing), and the other for -documents which are printed on both sides of each sheet (double-sided -printing). (*Note `@setchapternewpage': setchapternewpage.) You can -specify these formats in different ways: - - * The conventional way is to write an `@setchapternewpage' command - before the title page commands, and then have the `@end titlepage' - command start generating page headings in the manner desired. - (*Note `@setchapternewpage': setchapternewpage.) - - * Alternatively, you can use the `@headings' command to prevent page - headings from being generated or to start them for either single or - double-sided printing. (Write an `@headings' command immediately - after the `@end titlepage' command. *Note The `@headings' - Command: headings on off, for more information.) - - * Or, you may specify your own page heading and footing format. - *Note Page Headings: Headings, for detailed information about page - headings and footings. - - Most documents are formatted with the standard single-sided or -double-sided format, using `@setchapternewpage odd' for double-sided -printing and no `@setchapternewpage' command for single-sided printing. - - -File: texi.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page - -The `@headings' Command ------------------------ - - The `@headings' command is rarely used. It specifies what kind of -page headings and footings to print on each page. Usually, this is -controlled by the `@setchapternewpage' command. You need the -`@headings' command only if the `@setchapternewpage' command does not -do what you want, or if you want to turn off pre-defined page headings -prior to defining your own. Write an `@headings' command immediately -after the `@end titlepage' command. - - There are four ways to use the `@headings' command: - -`@headings off' - Turn off printing of page headings. - -`@headings single' - Turn on page headings appropriate for single-sided printing. - -`@headings double' -`@headings on' - Turn on page headings appropriate for double-sided printing. The - two commands, `@headings on' and `@headings double', are - synonymous. - - For example, suppose you write `@setchapternewpage off' before the -`@titlepage' command to tell TeX to start a new chapter on the same -page as the end of the last chapter. This command also causes TeX to -typeset page headers for single-sided printing. To cause TeX to -typeset for double sided printing, write `@headings double' after the -`@end titlepage' command. - - You can stop TeX from generating any page headings at all by writing -`@headings off' on a line of its own immediately after the line -containing the `@end titlepage' command, like this: - - @end titlepage - @headings off - -The `@headings off' command overrides the `@end titlepage' command, -which would otherwise cause TeX to print page headings. - - You can also specify your own style of page heading and footing. -*Note Page Headings: Headings, for more information. - - -File: texi.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File - -The `Top' Node and Master Menu -============================== - - The `Top' node is the node from which you enter an Info file. - - A `Top' node should contain a brief description of the Info file and -an extensive, master menu for the whole Info file. This helps the -reader understand what the Info file is about. Also, you should write -the version number of the program to which the Info file applies; or, -at least, the edition number. - - The contents of the `Top' node should appear only in the Info file; -none of it should appear in printed output, so enclose it between -`@ifinfo' and `@end ifinfo' commands. (TeX does not print either an -`@node' line or a menu; they appear only in Info; strictly speaking, -you are not required to enclose these parts between `@ifinfo' and `@end -ifinfo', but it is simplest to do so. *Note Conditionally Visible -Text: Conditionals.) - -* Menu: - -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. - - -File: texi.info, Node: Title of Top Node, Next: Master Menu Parts, Up: The Top Node - -`Top' Node Title ----------------- - - Sometimes, you will want to place an `@top' sectioning command line -containing the title of the document immediately after the `@node Top' -line (*note The `@top' Sectioning Command: makeinfo top command., for -more information). - - For example, the beginning of the Top node of this manual contains an -`@top' sectioning command, a short description, and edition and version -information. It looks like this: - - ... - @end titlepage - - @ifinfo - @node Top, Copying, (dir), (dir) - @top Texinfo - - Texinfo is a documentation system... - - This is edition... - ... - @end ifinfo - - @menu - * Copying:: Texinfo is freely - redistributable. - * Overview:: What is Texinfo? - ... - @end menu - - In a `Top' node, the `Previous', and `Up' nodes usually refer to the -top level directory of the whole Info system, which is called `(dir)'. -The `Next' node refers to the first node that follows the main or master -menu, which is usually the copying permissions, introduction, or first -chapter. - - -File: texi.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node - -Parts of a Master Menu ----------------------- - - A "master menu" is a detailed main menu listing all the nodes in a -file. - - A master menu is enclosed in `@menu' and `@end menu' commands and -does not appear in the printed document. - - Generally, a master 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 appendices. - - * The second part contains nodes for the indices. - - * The third and subsequent parts contain a listing of the other, - lower level nodes, often ordered by chapter. This way, rather - than go through an intermediary menu, an inquirer can go directly - to a particular node when searching for specific information. - These menu items are not required; add them if you think they are a - convenience. - - Each section in the menu can be introduced by a descriptive line. So -long as the line does not begin with an asterisk, it will not be -treated as a menu entry. (*Note Writing a Menu::, for more -information.) - - For example, the master menu for this manual looks like the following -(but has many more entries): - - @menu - * Copying:: Texinfo is freely - redistributable. - * Overview:: What is Texinfo? - * Texinfo Mode:: Special features in GNU Emacs. - ... - ... - * Command and Variable Index:: - An entry for each @-command. - * Concept Index:: An entry for each concept. - - --- The Detailed Node Listing --- - - Overview of Texinfo - - * Info Files:: What is an Info file? - * Printed Manuals:: Characteristics of - a printed manual. - ... - ... - - Using Texinfo Mode - - * Info on a Region:: Formatting part of a file - for Info. - ... - ... - @end menu - - -File: texi.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File - -Software Copying Permissions -============================ - - If the Texinfo file has a section containing the "General Public -License" and the distribution information and a warranty disclaimer for -the software that is documented, this section usually follows the `Top' -node. The General Public License is very important to Project GNU -software. It ensures that you and others will continue to have a right -to use and share the software. - - The copying and distribution information and the disclaimer are -followed by an introduction or else by the first chapter of the manual. - - Although an introduction 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, an introduction would follow the licensing and distribution -information, although sometimes people put it earlier in the document. -Usually, an introduction is put in an `@unnumbered' section. (*Note -The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.) - - -File: texi.info, 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 commands that create -indices and generate detailed and summary tables of contents. And it -must include the `@bye' command that marks the last line processed by -TeX. - - For example: - - @node Concept Index, , Variables Index, Top - @c node-name, next, previous, up - @unnumbered Concept Index - - @printindex cp - - @contents - @bye - -* Menu: - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. - - -File: texi.info, Node: Printing Indices & Menus, Next: Contents, Up: Ending a File - -Index Menus and Printing an Index -================================= - - To print an index means to include it as part of a manual or Info -file. This does not happen automatically just because you use -`@cindex' or other index-entry generating commands in the Texinfo file; -those just cause the raw data for the index to be accumulated. To -generate an index, you must include the `@printindex' command at the -place in the document where you want the index to appear. Also, as -part of the process of creating a printed manual, you must run a -program called `texindex' (*note Format/Print Hardcopy::.) to sort the -raw data to produce a sorted index file. The sorted index file is what -is actually used to print the index. - - Texinfo offers six different types of predefined index: the concept -index, the function index, the variables index, the keystroke index, the -program index, and the data type index (*note Predefined Indices::.). -Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', -and `tp'. You may merge indices, or put them into separate sections -(*note Combining Indices::.); or you may define your own indices (*note -Defining New Indices: New Indices.). - - The `@printindex' command takes a two-letter index name, reads the -corresponding sorted index file and formats it appropriately into an -index. - - The `@printindex' command does not generate a chapter heading for -the index. Consequently, you should precede the `@printindex' command -with a suitable section or chapter command (usually `@unnumbered') to -supply the chapter heading and put the index into the table of -contents. Precede the `@unnumbered' command with an `@node' line. - - For example: - - @node Variable Index, Concept Index, Function Index, Top - @comment node-name, next, previous, up - @unnumbered Variable Index - - @printindex vr - - @node Concept Index, , Variable Index, Top - @comment node-name, next, previous, up - @unnumbered Concept Index - - @printindex cp - - @summarycontents - @contents - @bye - -(Readers often prefer that the concept index come last in a book, since -that makes it easiest to find.) - - -File: texi.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File - -Generating a Table of Contents -============================== - - The `@chapter', `@section', and other structuring commands supply -the information to make up a table of contents, but they do not cause -an actual table to appear in the manual. To do this, you must use the -`@contents' and `@summarycontents' commands: - -`@contents' - Generate a table of contents in a printed manual, including all - chapters, sections, subsections, etc., as well as appendices and - unnumbered chapters. (Headings generated by the `@heading' series - of commands do not appear in the table of contents.) The - `@contents' command should be written on a line by itself. - -`@shortcontents' -`@summarycontents' - (`@summarycontents' is a synonym for `@shortcontents'; the two - commands are exactly the same.) - - Generate a short or summary table of contents that lists only the - chapters (and appendices and unnumbered chapters). Omit sections, - subsections and subsubsections. Only a long manual needs a short - table of contents in addition to the full table of contents. - - Write the `@shortcontents' command on a line by itself right - *before* the `@contents' command. - - The table of contents commands automatically generate a chapter-like -heading at the top of the first table of contents page. Write the table -of contents commands at the very end of a Texinfo file, just before the -`@bye' command, following any index sections--anything in the Texinfo -file after the table of contents commands will be omitted from the -table of contents. - - When you print a manual with a table of contents, the table of -contents are printed last and numbered with roman numerals. You need -to place those pages in their proper place, after the title page, -yourself. (This is the only collating you need to do for a printed -manual. The table of contents is printed last because it is generated -after the rest of the manual is typeset.) - - Here is an example of where to write table of contents commands: - - INDICES... - @shortcontents - @contents - @bye - - Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the `@contents' and `@shortcontents' -commands. - - -File: texi.info, Node: File End, Prev: Contents, Up: Ending a File - -`@bye' File Ending -================== - - An `@bye' command terminates TeX or Info formatting. None of the -formatting commands see any of the file following `@bye'. The `@bye' -command should be on a line by itself. - - If you wish, you may follow the `@bye' line with notes. These notes -will not be formatted and will not appear in either Info or a printed -manual; it is as if text after `@bye' were within `@ignore' ... `@end -ignore'. Also, you may follow the `@bye' line with a local variables -list. *Note Using Local Variables and the Compile Command: -Compile-Command, for more information. - - -File: texi.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top - -Chapter Structuring -******************* - - The "chapter structuring" commands divide a document into a -hierarchy of chapters, sections, subsections, and subsubsections. -These commands generate large headings; they also provide information -for the table of contents of a printed manual (*note Generating a Table -of Contents: Contents.). - - The chapter structuring commands do not create an Info node -structure, so normally you should put an `@node' command immediately -before each chapter structuring command (*note Nodes::.). The only -time you are likely to use the chapter structuring commands without -using the node structuring commands is if you are writing a document -that contains no cross references and will never be transformed into -Info format. - - It is unlikely that you will ever write a Texinfo file that is -intended only as an Info file and not as a printable document. If you -do, you might still use chapter structuring commands to create a -heading at the top of each node--but you don't need to. - -* Menu: - -* Tree Structuring:: A manual is like an upside down tree ... -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The `@top' command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. - - -File: texi.info, Node: Tree Structuring, Next: Structuring Command Types, Up: Structuring - -Tree Structure of Sections -========================== - - A Texinfo file is usually structured like a book with chapters, -sections, subsections, and the like. This structure can be visualized -as a tree (or rather as an upside-down tree) with the root at the top -and the levels corresponding to chapters, sections, subsection, and -subsubsections. - - Here is a diagram that shows a Texinfo file with three chapters, -each of which has two sections. - - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | - Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - - In a Texinfo file that has this structure, the beginning of Chapter 2 -looks like this: - - @node Chapter 2, Chapter 3, Chapter 1, top - @chapter Chapter 2 - - The chapter structuring commands are described in the sections that -follow; the `@node' and `@menu' commands are described in following -chapters. (*Note Nodes::, and see *Note Menus::.) - - -File: texi.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring - -Types of Structuring Command -============================ - - The chapter structuring commands fall into four groups or series, -each of which contains structuring commands corresponding to the -hierarchical levels of chapters, sections, subsections, and -subsubsections. - - The four groups are the `@chapter' series, the `@unnumbered' series, -the `@appendix' series, and the `@heading' series. - - Each command produces titles that have a different appearance on the -printed page or Info file; only some of the commands produce titles -that are listed in the table of contents of a printed book or manual. - - * The `@chapter' and `@appendix' series of commands produce numbered - or lettered entries both in the body of a printed work and in its - table of contents. - - * The `@unnumbered' series of commands produce unnumbered entries - both in the body of a printed work and in its table of contents. - The `@top' command, which has a special use, is a member of this - series (*note `@top': makeinfo top.). - - * The `@heading' series of commands produce unnumbered headings that - do not appear in a table of contents. The heading commands never - start a new page. - - * The `@majorheading' command produces results similar to using the - `@chapheading' command but generates a larger vertical whitespace - before the heading. - - * When an `@setchapternewpage' command says to do so, the - `@chapter', `@unnumbered', and `@appendix' commands start new - pages in the printed manual; the `@heading' commands do not. - - Here are the four groups of chapter structuring commands: - - No new pages - Numbered Unnumbered Lettered and numbered Unnumbered - In contents In contents In contents Not in contents - - @top @majorheading - @chapter @unnumbered @appendix @chapheading - @section @unnumberedsec @appendixsec @heading - @subsection @unnumberedsubsec @appendixsubsec @subheading - @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading - - -File: texi.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring - -`@top' -====== - - The `@top' command is a special sectioning command that you use only -after an `@node Top' line at the beginning of a Texinfo file. The -`@top' command tells the `makeinfo' formatter which node is the `Top' -node. It has the same typesetting effect as `@unnumbered' (*note -`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed -information, see *Note The `@top' Command: makeinfo top command. - - -File: texi.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring - -`@chapter' -========== - - `@chapter' identifies a chapter in the document. Write the command -at the beginning of a line and follow it on the same line by the title -of the chapter. - - For example, this chapter in this manual is entitled "Chapter -Structuring"; the `@chapter' line looks like this: - - @chapter Chapter Structuring - - In TeX, the `@chapter' command creates a chapter in the document, -specifying the chapter title. The chapter is numbered automatically. - - In Info, the `@chapter' command causes the title to appear on a line -by itself, with a line of asterisks inserted underneath. Thus, in -Info, the above example produces the following output: - - Chapter Structuring - ******************* - - -File: texi.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring - -`@unnumbered', `@appendix' -========================== - - Use the `@unnumbered' command to create a chapter that appears in a -printed manual without chapter numbers of any kind. Use the -`@appendix' command to create an appendix in a printed manual that is -labelled by letter instead of by number. - - For Info file output, the `@unnumbered' and `@appendix' commands are -equivalent to `@chapter': the title is printed on a line by itself with -a line of asterisks underneath. (*Note `@chapter': chapter.) - - To create an appendix or an unnumbered chapter, write an `@appendix' -or `@unnumbered' command at the beginning of a line and follow it on -the same line by the title, as you would if you were creating a chapter. - - -File: texi.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring - -`@majorheading', `@chapheading' -=============================== - - The `@majorheading' and `@chapheading' commands put chapter-like -headings in the body of a document. - - However, neither command causes TeX to produce a numbered heading or -an entry in the table of contents; and neither command causes TeX to -start a new page in a printed manual. - - In TeX, an `@majorheading' command generates a larger vertical -whitespace before the heading than an `@chapheading' command but is -otherwise the same. - - In Info, the `@majorheading' and `@chapheading' commands are -equivalent to `@chapter': the title is printed on a line by itself with -a line of asterisks underneath. (*Note `@chapter': chapter.) - - -File: texi.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring - -`@section' -========== - - In a printed manual, an `@section' command identifies a numbered -section within a chapter. The section title appears in the table of -contents. In Info, an `@section' command provides a title for a -segment of text, underlined with `='. - - This section is headed with an `@section' command and looks like -this in the Texinfo file: - - @section @code{@@section} - - To create a section, write the `@section' command at the beginning -of a line and follow it on the same line by the section title. - - Thus, - - @section This is a section - -produces - - This is a section - ================= - -in Info. - - -File: texi.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring - -`@unnumberedsec', `@appendixsec', `@heading' -============================================ - - The `@unnumberedsec', `@appendixsec', and `@heading' commands are, -respectively, the unnumbered, appendix-like, and heading-like -equivalents of the `@section' command. (*Note `@section': section.) - -`@unnumberedsec' - The `@unnumberedsec' command may be used within an unnumbered - chapter or within a regular chapter or appendix to provide an - unnumbered section. - -`@appendixsec' -`@appendixsection' - `@appendixsection' is a longer spelling of the `@appendixsec' - command; the two are synonymous. - - Conventionally, the `@appendixsec' or `@appendixsection' command - is used only within appendices. - -`@heading' - You may use the `@heading' command anywhere you wish for a - section-style heading that will not appear in the table of - contents. - - -File: texi.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring - -The `@subsection' Command -========================= - - Subsections are to sections as sections are to chapters. (*Note -`@section': section.) In Info, subsection titles are underlined with -`-'. For example, - - @subsection This is a subsection - -produces - - This is a subsection - -------------------- - - In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep. - - -File: texi.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring - -The `@subsection'-like Commands -=============================== - - The `@unnumberedsubsec', `@appendixsubsec', and `@subheading' -commands are, respectively, the unnumbered, appendix-like, and -heading-like equivalents of the `@subsection' command. (*Note -`@subsection': subsection.) - - In Info, the `@subsection'-like commands generate a title underlined -with hyphens. In a printed manual, an `@subheading' command produces a -heading like that of a subsection except that it is not numbered and -does not appear in the table of contents. Similarly, an -`@unnumberedsubsec' command produces an unnumbered heading like that of -a subsection and an `@appendixsubsec' command produces a -subsection-like heading labelled with a letter and numbers; both of -these commands produce headings that appear in the table of contents. - - -File: texi.info, Node: subsubsection, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring - -The `subsub' Commands -===================== - - The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are: - -`@subsubsection' - Subsubsections are to subsections as subsections are to sections. - (*Note `@subsection': subsection.) In a printed manual, - subsubsection titles appear in the table of contents and are - numbered four levels deep. - -`@unnumberedsubsubsec' - Unnumbered subsubsection titles appear in the table of contents of - a printed manual, but lack numbers. Otherwise, unnumbered - subsubsections are the same as subsubsections. In Info, unnumbered - subsubsections look exactly like ordinary subsubsections. - -`@appendixsubsubsec' - Conventionally, appendix commands are used only for appendices and - are lettered and numbered appropriately in a printed manual. They - also appear in the table of contents. In Info, appendix - subsubsections look exactly like ordinary subsubsections. - -`@subsubheading' - The `@subsubheading' command may be used anywhere that you need a - small heading that will not appear in the table of contents. In - Info, subsubheadings look exactly like ordinary subsubsection - headings. - - In Info, `subsub' titles are underlined with periods. For example, - - @subsubsection This is a subsubsection - -produces - - This is a subsubsection - ....................... - - -File: texi.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top - -Nodes -***** - - "Nodes" are the primary segments of a Texinfo file. They do not -themselves impose a hierarchic or any other kind of structure on a file. -Nodes contain "node pointers" that name other nodes, and can contain -"menus" which are lists of nodes. In Info, the movement commands can -carry you to a pointed-to node or to a node listed in a menu. Node -pointers and menus provide structure for Info files just as chapters, -sections, subsections, and the like, provide structure for printed -books. - -* Menu: - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'. - - -File: texi.info, Node: Two Paths, Next: Node Menu Illustration, Up: Nodes - -Two Paths -========= - - The node and menu commands and the chapter structuring commands are -independent of each other: - - * In Info, node and menu commands provide structure. The chapter - structuring commands generate headings with different kinds of - underlining--asterisks for chapters, hyphens for sections, and so - on; they do nothing else. - - * In TeX, the chapter structuring commands generate chapter and - section numbers and tables of contents. The node and menu - commands provide information for cross references; they do nothing - else. - - You can use node pointers and menus to structure an Info file any way -you want; and you can write a Texinfo file so that its Info output has a -different structure than its printed output. However, most Texinfo -files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is not -convenient to do otherwise. - - Generally, printed output is structured in a tree-like hierarchy in -which the chapters are the major limbs from which the sections branch -out. Similarly, node pointers and menus are organized to create a -matching structure in the Info output. - - -File: texi.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes - -Node and Menu Illustration -========================== - - Here is a copy of the diagram shown earlier that illustrates a -Texinfo file with three chapters, each of which contains two sections. - - Note that the "root" is at the top of the diagram and the "leaves" -are at the bottom. This is how such a diagram is drawn conventionally; -it illustrates an upside-down tree. For this reason, the root node is -called the `Top' node, and `Up' node pointers carry you closer to the -root. - - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | - Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - - Write the beginning of the node for Chapter 2 like this: - - @node Chapter 2, Chapter 3, Chapter 1, top - @comment node-name, next, previous, up - -This `@node' line says that the name of this node is "Chapter 2", the -name of the `Next' node is "Chapter 3", the name of the `Previous' node -is "Chapter 1", and the name of the `Up' node is "Top". - - *Please Note:* `Next' refers to the next node at the same - hierarchical level in the manual, not necessarily to the next node - within the Texinfo file. In the Texinfo file, the subsequent node - may be at a lower level--a section-level node may follow a - chapter-level node, and a subsection-level node may follow a - section-level node. `Next' and `Previous' refer to nodes at the - *same* hierarchical level. (The `Top' node contains the exception - to this rule. Since the `Top' node is the only node at that - level, `Next' refers to the first following node, which is almost - always a chapter or chapter-level node.) - - To go to Sections 2.1 and 2.2 using Info, you need a menu inside -Chapter 2. (*Note Menus::.) You would write the menu just before the -beginning of Section 2.1, like this: - - @menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: - @end menu - - Write the node for Sect. 2.1 like this: - - @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 - @comment node-name, next, previous, up - - In Info format, the `Next' and `Previous' pointers of a node usually -lead to other nodes at the same level--from chapter to chapter or from -section to section (sometimes, as shown, the `Previous' pointer points -up); an `Up' pointer usually leads to a node at the level above (closer -to the `Top' node); and a `Menu' leads to nodes at a level below (closer -to `leaves'). (A cross reference can point to a node at any level; see -*Note Cross References::.) - - Usually, an `@node' command and a chapter structuring command are -used in sequence, along with indexing commands. (You may follow the -`@node' line with a comment line that reminds you which pointer is -which.) - - Here is the beginning of the chapter in this manual called "Ending a -Texinfo File". This shows an `@node' line followed by a comment line, -an `@chapter' line, and then by indexing lines. - - @node Ending a File, Structuring, Beginning a File, Top - @comment node-name, next, previous, up - @chapter Ending a Texinfo File - @cindex Ending a Texinfo file - @cindex Texinfo file ending - @cindex File ending - - -File: texi.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes - -The `@node' Command -=================== - - A "node" is a segment of text that begins at an `@node' command and -continues until the next `@node' command. The definition of node is -different from that for chapter or section. A chapter may contain -sections and a section may contain subsections; but a node cannot -contain subnodes; the text of a node continues only until the next -`@node' command in the file. A node usually contains only one chapter -structuring command, the one that follows the `@node' line. On the -other hand, in printed output nodes are used only for cross references, -so a chapter or section may contain any number of nodes. Indeed, a -chapter usually contains several nodes, one for each section, -subsection, and subsubsection. - - To create a node, write an `@node' command at the beginning of a -line, and follow it with four arguments, separated by commas, on the -rest of the same line. These arguments are the name of the node, and -the names of the `Next', `Previous', and `Up' pointers, in that order. -You may insert spaces before each pointer if you wish; the spaces are -ignored. You must write the name of the node, and the names of the -`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, -the formatters fail. (*note info: (info)Top, for more information -about nodes in Info.) - - Usually, you write one of the chapter-structuring command lines -immediately after an `@node' line--for example, an `@section' or -`@subsection' line. (*Note Types of Structuring Command: Structuring -Command Types.) - - *Please note:* The GNU Emacs Texinfo mode updating commands work - only with Texinfo files in which `@node' lines are followed by - chapter structuring lines. *Note Updating Requirements::. - - TeX uses `@node' lines to identify the names to use for cross -references. For this reason, you must write `@node' lines in a Texinfo -file that you intend to format for printing, even if you do not intend -to format it for Info. (Cross references, such as the one at the end -of this sentence, are made with `@xref' and its related commands; see -*Note Cross References::.) - -* Menu: - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an `@node' line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the `@top' command. -* Top Node Summary:: Write a brief description for readers. - - -File: texi.info, Node: Node Names, Next: Writing a Node, Up: node - -Choosing Node and Pointer Names -------------------------------- - - The name of a node identifies the node. The pointers enable you to -reach other nodes and consist of the names of those nodes. - - Normally, a node's `Up' pointer contains the name of the node whose -menu mentions that node. The node's `Next' pointer contains the name -of the node that follows that node in that menu and its `Previous' -pointer contains the name of the node that precedes it in that menu. -When a node's `Previous' node is the same as its `Up' node, both node -pointers name the same node. - - Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the `dir' file, which contains -the main menu for all of Info. - - The `Top' node itself contains the main or master menu for the -manual. Also, it is helpful to include a brief description of the -manual in the `Top' node. *Note First Node::, for information on how -to write the first node of a Texinfo file. - - -File: texi.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node - -How to Write an `@node' Line ----------------------------- - - The easiest way to write an `@node' line is to write `@node' at the -beginning of a line and then the name of the node, like this: - - @node NODE-NAME - - If you are using GNU Emacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or you -can leave the pointers out of the Texinfo file and let `makeinfo' -insert node pointers into the Info file it creates. (*Note Texinfo -Mode::, and *Note makeinfo Pointer Creation::.) - - Alternatively, you can insert the `Next', `Previous', and `Up' -pointers yourself. If you do this, you may find it helpful to use the -Texinfo mode keyboard command `C-c C-c n'. This command inserts -`@node' and a comment line listing the names of the pointers in their -proper order. The comment line helps you keep track of which arguments -are for which pointers. This comment line is especially useful if you -are not familiar with Texinfo. - - The template for a node line with `Next', `Previous', and `Up' -pointers looks like this: - - @node NODE-NAME, NEXT, PREVIOUS, UP - - If you wish, you can ignore `@node' lines altogether in your first -draft and then use the `texinfo-insert-node-lines' command to create -`@node' lines for you. However, we do not recommend this practice. It -is better to name the node itself at the same time that you write a -segment so you can easily make cross references. A large number of -cross references are an especially important feature of a good Info -file. - - After you have inserted an `@node' line, you should immediately -write an @-command for the chapter or section and insert its name. -Next (and this is important!), put in several index entries. Usually, -you will find at least two and often as many as four or five ways of -referring to the node in the index. Use them all. This will make it -much easier for people to find the node. - - -File: texi.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node - -`@node' Line Tips ------------------ - - Here are three suggestions: - - * Try to pick node names that are informative but short. - - In the Info file, the file name, node name, and pointer names are - all inserted on one line, which may run into the right edge of the - window. (This does not cause a problem with Info, but is ugly.) - - * Try to pick node names that differ from each other near the - beginnings of their names. This way, it is easy to use automatic - name completion in Info. - - * By convention, node names are capitalized just as they would be for - section or chapter titles--initial and significant words are - capitalized; others are not. - |
