diff options
Diffstat (limited to 'info/texinfo-2')
-rw-r--r-- | info/texinfo-2 | 1405 |
1 files changed, 1405 insertions, 0 deletions
diff --git a/info/texinfo-2 b/info/texinfo-2 new file mode 100644 index 00000000000..865e03dc371 --- /dev/null +++ b/info/texinfo-2 @@ -0,0 +1,1405 @@ +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: Indices, Prev: Contents, Up: Ending a File + +Creating Indices +================ + +Using Texinfo, you can generate printed indices and Info file menus +without having to sort and collate entries manually. Texinfo will do +this for you automatically. Each index covers a certain kind of +entry (functions, or variables, or concepts, etc.) and lists all of +those entries in alphabetical order, together with information on how +to find the discussion of each entry. In a printed manual, this +information consists of page numbers. In an Info file, it consists +of a menu item leading to the first node referenced. + +When you are making index entries, it is good practice to think of +the different categories under which people may look for something. +Different people *do not* think of the same words when they look +something up. They think of different words. A helpful index will +have items indexed under all the different words that people may use. +For example, someone might think it obvious that the two letter names +for indices should be listed under "Indices, two letter names", since +the word "Index" is the general concept. But another reader may +remember the specific concept of two letter names and search for the +entry listed as "Two letter names for indices". A good index will +have both entries and will help both kinds of user. + +Like typesetting, the construction of an index is a highly skilled, +professional art, the subtleties of which are not appreciated until +you have to do it yourself. + +Normally, six indices are provided for: + + * A "program index" listing names of programs and leading to the + places where those programs are documented. + + * A "function index" listing functions (such as, entry points of + libraries). + + * A "variables index" listing variables (such as, external + variables of libraries). + + * A "data type index" listing data types (such as, structures + defined in header files). + + * A "keystroke index" listing keyboard commands. + + * A "concept index" listing concepts that are discussed. + +Not every manual needs all of these. This manual has two indices: a +concept index and an @-command index (that uses the function index +but is called a command index in the chapter heading). Two or more +indices can be combined into one using the `@synindex' command. +*Note Combining Indices::. + +* Menu: + +* Index Entries:: Defining the entries of an index +* Combining Indices:: +* Printing Indices & Menus:: + + + +File: texinfo, Node: Index Entries, Next: Combining Indices, Up: Indices + +Defining the Entries of an Index +-------------------------------- + +The data to make an index comes from many individual commands +scattered throughout the Texinfo source file. Each command says to +add one entry to a particular index; after processing, it will give +the current page number or node name as the reference. + +`@cindex CONCEPT' + Make an entry in the concept index for CONCEPT, referring to the + current page or node. + +`@findex FUNCTION' + Make an entry in the function index for FUNCTION, referring to + the current page or node. + +`@vindex VARIABLE' + Make an entry in the variable index for VARIABLE, referring to + the current page or node. + +`@pindex PROGRAM' + Make an entry in the program index for PROGRAM, referring to the + current page or node. + +`@kindex KEY' + Make an entry in the key index for KEY, referring to the current + page or node. + +`@tindex DATA TYPE' + Make an entry in the data type index for DATA TYPE, referring to + the current page or node. + +If the same name is indexed on several pages, all the pages are +listed in the printed manual's index. However, *only* the *first* +node referenced will appear in the index of an Info file. This means +that it is best to write indices in which each entry will refer to +only one place in the Texinfo file. Fortunately, this constraint is +a feature rather than loss since it means that the index will be easy +to use. Otherwise, it can be easy to create an index which has many +pages listed for an entry and you don't know which one you need. + +You are not actually required to use indices for their canonical +purposes. For example, you might wish to index some C preprocessor +macros. You could put them in the function index along with actual +functions, just by writing `@findex' commands for them; then, when +you print the "function index", you could give it the title `Function +and Macro Index' and all will be consistent for the reader. Or you +could put the macros in with the data types by writing `@tindex' +commands for them, and give that index a suitable title so the reader +will understand. + + + +File: texinfo, Node: Combining Indices, Next: Printing Indices & Menus, Prev: Index Entries, Up: Indices + +Combining Indices +----------------- + +Sometimes you will want to combine two disparate indices such as +functions and variables, perhaps because you have few enough of one +of them that a separate index for them would look silly. + +You could put variables into the function index by writing `@findex' +commands for them instead of `@vindex' commands, and produce a +consistent manual by printing the function index with the title +`Function and Variable Index' and not printing the `Variable Index' +at all; but this is not a robust procedure. It works only as long as +your document is never included in part of or together with another +document that is designed to have a separate variable index; if you +did that, the variables from your document and those from the other +would not end up together. + +What you should do instead when you want functions and variables in +one index is to index the variables with `@vindex' as they should be, +but use the `@synindex' command to redirect these `@vindex' commands +to the function index. `@synindex' takes two arguments: the name of +an index to redirect, and the name of an index to redirect it to. +For this purpose, the indices are given two-letter names: + +`cp' + the concept index + +`vr' + the variable index + +`fn' + the function index + +`ky' + the key index + +`pg' + the program index + +`tp' + the data type index + +Thus, `@synindex vr fn' at the front of a Texinfo file will cause all +entries designated for the variable index to go to the function index +instead. + + + +File: texinfo, Node: Printing Indices & Menus, Prev: Combining Indices, Up: Indices + +Printing an Index and Generating Menus +-------------------------------------- + +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 print an +index, you must include the `@printindex' command at the place in the +document where you want the index to appear. Also, for the case of +the printed manual, you must run a program called `texindex' to sort +the raw data to produce a sorted index file, which is what will +actually be used to print the index. + +The Texinfo command that is used to print indices is `@printindex'. +It takes the two-letter index name (*note Combining Indices::.) as an +argument without braces, and reads the corresponding sorted index +file and formats it appropriately into an index. + +The two-letter index names are: + +`cp' + the concept index. + +`vr' + the variable index. + +`fn' + the function index. + +`ky' + the key index. + +`pg' + the program index. + +`tp' + the data type index. + +`@printindex' does not generate a chapter heading for the index. +Consequently, you should precede the command with a suitable section +or chapter command (usually `@unnumbered') to supply the chapter +heading and put the index into the table of contents. And before +that, you will probably put a `@node' command. For example, + + @node Variables Index, Concept Index, Function Index, Top + @comment node-name, next, previous, up + @unnumbered Variable Index + + @printindex vr + + @node Concept Index, , Variables Index, Top + @comment node-name, next, previous, up + @unnumbered Concept Index + + @printindex cp + + @summarycontents + @contents + @bye + +In TeX, `@printindex' needs a sorted index file to work from. TeX +does not know how to do sorting; this is one of the main deficiencies +of TeX. You must invoke the program `texindex' to do so, giving it +the names of the raw index files to be sorted as arguments. You do +not have to run `texindex' on all of them; only the ones you are +going to print. (*Note Printing Hardcopy::, for more information.) + + + +File: texinfo, Node: Structuring, Next: Quotations and Examples, Prev: Ending a File, Up: Top + +Node and Chapter Structuring +**************************** + +The chapter structuring commands divide a document into a hierarchy +of chapters, sections, subsections and subsubsections. These +commands generate large headings. + +In a printed manual, the table of contents is based on the +information specified by the chapter structuring commands. + +Although the chapter structuring commands used for creating a printed +document are entirely different from the node commands for +structuring an Info file, you are likely to use the two kinds of +command together since the single Texinfo file is usually designed to +be read both as an Info file and as a printed manual. 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 +will never be put into Info format, for example, a novel, a letter, +an article or a memorandum. + +It is unlikely that you will ever write a Texinfo file that is only +intended as an on-line Info file and not as a printable document. +However, Texinfo is flexible enough so that you can do this if you +wish. + +Although a Texinfo file can be structured in a variety of ways, it is +usually structured like a book with chapters, sections, subsections +and the like. This structure can also be visualized as a tree (or +rather as an upside down tree) with the root at the top and each +level corresponding to chapters or sections or whatnot. In Info +format, you reach the nodes on each level by using the the `Next' and +`Previous' pointers in the node line. For example, you go from one +chapter to the next or previous chapter by using the the pointers to +the next and previous chapters. In Info, you go the level above by +using an `Up' pointer and you go to the level below through a `Menu'. +In the printed manual, cross references are indicated by page and +section numbers; in the on-line file, cross references are specified +by inline menu items. + +Here is a diagram that shows a Texinfo file with three chapters; +each chapter has two sections. + + top + | + | + --------------------------------------------- + | | | + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + | | | + ---------- ---------- ---------- + | | | | | | + Sect. 1.1 Sect. 1.2 Sect. 2.1 Sect. 2.2 Sect. 3.1 Sect. 3.2 + + +In this structure, the node for Chapter 2 looks like this: + + @node Chapter 2, Chapter 3, Chapter 1, top + @comment node-name, next, previous, up + +To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 +that says: + + @menu + * Sect. 2.1:: Description of this section. + * Sect. 2.2:: + @end menu + +This menu is located inside Chapter 2, after the beginning of the +chapter, just before Section 2.1. + +Note that a menu entry has three parts: the menu item name, the name +of the node and, optionally, a description of the item (in that +order). If the menu item name and the name of the node are the same, +you can put two colons after the item name, as is shown in the +example. (If the second part is different from the first, the first +part is terminated by a colon and the second part terminated by a +tab, newline, comma or period.) (*Note Menu::.) + +The node for Sect. 2.1 will look like this: + + @node Sect. 2.1, Sect. 2.2, , Chapter 2 + @comment node-name, next, previous, up + +This node does not have a `Previous' node. + +Usually, an `@node' command and a chapter structuring command are +used in sequence, along with indexing commands. For example, the +node for the chapter on ending a file looks like this: + + @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 + +The chapter structuring commands fall into four groups that have the +characteristics of chapters, sections, subsections and subsubsections. +The groups are: + +`@chapter' +`@unnumbered' +`@appendix' + For chapters and chapter-like parts of a document. + +`@section' +`@unnumberedsec' +`@appendixsec' + For sections and section-like parts of a document. + +`@subsection' +`@unnumberedsubsec' +`@appendixsubsec' + For subsections and subsection-like parts of a document. + +`@subsubsection' +`@unnumberedsubsubsec' +`@appendixsubsubsec' + For subsubsections and subsubsection-like parts of a document. + +In the sections that follow, the chapter structuring commands are +described first and then the `@node' and `@menu' commands. + +* Menu: + +* Chapter:: +* Unnumbered and Appendix:: +* Section:: +* Subsection:: +* Subsubsection:: +* Node:: +* Menu:: + + + +File: texinfo, Node: Chapter, Next: Unnumbered and Appendix, Up: Structuring + +@chapter +======== + +`@chapter' identifies a chapter in the document. It is followed by a +single argument which is the rest of the line, as in + + @chapter Node and Chapter Structuring + +In TeX, it creates a chapter in the document, specifying the chapter +title. + +In the Info file, `@chapter' causes its argument to appear on a line +by itself, with a line of asterisks inserted underneath. Thus, the +above example produces the following output: + + Node and Chapter Structuring + **************************** + + + +File: texinfo, Node: Unnumbered and Appendix, Next: Section, Prev: Chapter, Up: Structuring + +@unnumbered, @appendix +====================== + +These commands are equivalent to `@chapter' for Info file output. +(*Note Chapter::.) In a printed manual, they generate chapters that +are numbered differently in the table of contents. `@unnumbered' +chapters appear without chapter numbers of any kind, and `@appendix' +chapters are given a letter instead of a number. + + + +File: texinfo, Node: Section, Next: Subsection, Prev: Unnumbered and Appendix, Up: Structuring + +@section +======== + +`@section' is like `@chapter' except that in TeX it makes a section +rather than a chapter. (*Note Chapter::.) Sections go within +chapters. In the Info file, `@chapter' and `@section' differ only in +that `@section' underlines with `='. For example, + + This is a section + ================= + +@unnumberedsec, @appendixsec +============================ + +Use these constructs for sections within chapters made by +`@unnumbered' or `@appendix'. (*Note Section::.) + + + +File: texinfo, Node: Subsection, Next: Subsubsection, Prev: Section, Up: Structuring + +@subsection +=========== + +Subsections are to sections as sections are to chapters. (*Note +Section::.) They are underlined with `-'. For example, + + This is a subsection + -------------------- + +@unnumberedsubsec, @appendixsubsec +================================== + +Use these constructs for subsections within sections within chapters +made by `@unnumberedsec' or `@appendixsec'. (*Note Subsection::.) + + + +File: texinfo, Node: Subsubsection, Next: Node, Prev: Subsection, Up: Structuring + +@subsubsection And Other Subsection Commands +============================================ + +Subsubsections are to subsections as subsections are to sections. +(*Note Subsection::.) They are underlined with periods. The +equivalent commands for `@unnumberedsubsec' and `@appendixsubsec' are +`@unnumberedsubsubsec' and `@appendixsubsubsec'. For example, + + This is a subsubsection + ....................... + + + +File: texinfo, Node: Node, Next: Menu, Prev: Subsubsection, Up: Structuring + +@node +===== + +`@node' defines the beginning of a new node in the Info output file +(*note info: (info)Top.). It is followed by four arguments, +separated by commas, that make up the rest of the line. Since it is +often hard to remember the order in which are arguments are listed, +`texinfo-mode' provides the `C-c C-c n' command +(`texinfo-insert-@node') which automatically inserts a comment line +listing the arguments. For example, + + @node Texinfo Mode, Beginning a File, Overview, Top + @comment node-name, next, previous, up + +defines a node named `Texinfo Mode', whose `Next' pointer is to node +`Beginning a File', whose `Previous' pointer is to node `Overview', +and whose `Up' pointer is to node `Top'. What this means is that +Texinfo changes `@node ARGS' into the special text string necessary +to separate Info nodes and to identify the node that is starting and +say what nodes it points to. + +The pointer names should be the names of nodes defined elsewhere. +For this example, nodes named `Beginning a File', `Overview' and +`Top' should be defined elsewhere in the file with other `@node' +commands. It does not matter whether they are before or after the +node that refers to them. + +Normally, a node's `Up' pointer should point at the node whose menu +mentions that node. The node's `Next' pointer should point at the +node that follows that node and its `Previous' pointer should point +at the node that precedes it in that menu. + +In TeX, `@node' is nearly ignored. It generates no text. Its only +function is to identify the name to use for cross-references to the +chapter or section which follows the `@node' command and which which +makes up the body of the node. (Cross references are made with +`@xref'. *Note Cross References::.) + +`@node' should be followed immediately by a chapter-structuring +command such as `@chapter', `@section', `@subsection' or +`@subsubsection'. + +The easiest way to write a node is to use the Texinfo mode keyboard +command `C-c C-c n' to insert `@node' and a comment line listing the +names of each of the pointers in their proper order. This way you +won't lose track of which arguments are for which pointers. The +template is especially useful if you are not familiar with Texinfo. +It is important to pick a suitable node name. Generally, these begin +with an uppercase letter as if the node name were a heading for a +chapter or section. Do not use any of the Texinfo @-commands in the +name; these commands confuse Info. The node name should be +informative. Unfortunately, long names will not fit onto the line, +which can be awkward. Sometimes it is better to use long but +informative names rather than short ones. + +Some people insert the names of the `Next', `Previous' and `Up' +pointers at the same time they insert the node's own name. This is +because it is easier to keep track of the node structure as you +create a document than it is to sort it out after you have dozens of +nodes. Others wait to insert the `Next', `Previous' and `Up' +pointers until they have a nearly final version of the document. +This is because they expect to change the organization of the +document while they write it and insert or delete sections and move +them around. The command `texinfo-show-structure' can be used to +find the `Next', `Previous' and `Up' pointers of a node. (See *Note +Using texinfo-show-structure::.) + +However you do it, it is best to name the node whenever you write the +section so you can easily make cross references to the section. A +large number of cross references are an especially important feature +of a good Info file. + +After you have inserted the 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. + +The top node of the file, named `Top', should have as its parent the +name of a node in another file, where there is a menu that leads to +this file. Specify the file name in parentheses. If the file is to +be installed directly in the Info directory file, use `(dir)' as the +parent of the top node; this is short for `(dir)top', the node `top' +in the file `dir', which is the main menu of Info. For example, + + @node Top, Overview, (dir), (dir) + @comment node-name, next, previous, up + +For more information about installing an Info file in the `info' +directory, *note Installing an Info File::. + + + +File: texinfo, Node: Menu, Prev: Node, Up: Structuring + +@menu +===== + +Info file nodes can contain "menus" which point to other nodes. You +must type the menus in by hand, and surround them with lines +containing `@menu' and `@end menu'. In Info, the `@menu' line +changes into `* Menu:', which indicates the beginning of a menu to +the Info program. Otherwise, the contents are unchanged by Texinfo, +except for the processing of any other @-commands within. The entire +menu construct has no effect in the printed manual and will not +appear there. + +By convention, a menu is put at the end of a node. This way, it is +easy for someone using Info to find the menu, using the `M->' +(`end-of-buffer') command. + +In a menu, every line that begins with a `*' lists a single topic. A +line that does not start with a `*' will also appear in the menu and +can be used as a comment. + +A menu item has three parts: + + 1. The menu item name. + + 2. The name of the node. + + 3. A description of the item. + +Only the first part is required. This part is the name of the +topic--the name of the menu item that the user must give to the `m' +command to select this topic when using Info. The first part comes +right after the asterisk and a space, and is followed by a colon, +spaces and tabs, and then the name of the node which discusses that +topic. The name of the node is terminated by a tab, comma, newline +or period. If the node name and topic name are the same, rather than +give the name twice, put two colons after the name instead. For +example, `* Name::'. (You should do this whenever possible, since it +reduces visual clutter in the menu). + +If the second part is present, it may be terminated with a tab, +comma, or newline; or with a period. + +For example, + + @menu + A Section on Foo and Switches + * Foo:: The node named Foo tells you how to go fooing. + * Sw: Switches. Type @code{m Sw} to see node @code{Switches} + which describes the switches available here. + @end menu + +produces + + * menu: + + A Section on Foo and Switches + * Foo:: The node named foo tells you how to go fooing. + * Sw: Switches. Type `m Sw' to see node `Switches' + which describes the switches available here. + + In this example, the menu has two items. `Foo' is both a menu item +name and the name of the node referred to by that item. `Sw' is the +other menu item name, and it refers to the node named `Switches'. +Since no file name is specified with `Foo' or `Switches', they must +be the names of other nodes in the same Info file. + +Nodes in other Info files can be referred to by putting the file name +in parentheses at the beginning of the node name. For example, + + @menu + * Outlining: (emacs) Outline Mode. The major mode for editing outlines. + * Rebinding: (emacs) Rebinding. How to redefine the meaning of a key. + @end menu + +When this is done, the item has to have at least two parts: the first +part is the menu item name and the second part is the name of the node. + + + +File: texinfo, Node: Quotations and Examples, Next: Lists and Tables, Prev: Structuring, Up: Top + +Making Quotations and Examples +****************************** + +Quotations and examples are blocks of text, consisting of one or more +whole paragraphs that are set off from the bulk of the text and +treated differently. They are usually indented. + +In Texinfo, an insertion is always begun by writing an @-command on a +line by itself, and ended by writing an `@end' command that is also +on a line by itself. For instance, an "example" is a kind of +insertion that is begun with `@example' and ended with `@end example'. + +There are three commands for quotations and examples: + +`@quotation' + Used to indicated text that is quoted. + +`@example' + Used to illustrate code, commands and the like in a fixed width + font without filling. + +`@display' + Used for illustrative text. + +* Menu: + +* Quotation:: +* Example:: +* Display:: + + + +File: texinfo, Node: Quotation, Next: Example, Up: Quotations and Examples + +@quotation +========== + +`@quotation' is used to indicate text that is excerpted from another +(real or hypothetical) printed work. The inside of a quotation is +processed normally except that + + 1. The margins are narrower. + + 2. Paragraphs are not indented. + + 3. Interline spacing and interparagraph spacing are reduced. + +Thus, the input + + @quotation + This is + a foo. + @end quotation + +produces in the printed manual + + This is a foo. + +and in the Info file + + This is + a foo. + + + +File: texinfo, Node: Example, Next: Display, Prev: Quotation, Up: Quotations and Examples + +@example +======== + +`@example' is used to indicate an example that is not part of the +running text. In the printed manual, this is done by switching to a +fixed width font, turning off filling, and making extra spaces and +blank lines significant. In the Info file, an analogous result is +obtained by indenting each line with five extra spaces. + +`@example' should appear on a line by itself; this line will +disappear from the output. Mark the end of the example with a line +containing `@end example', which will likewise disappear. For example: + + @example + mv foo bar + @end example + +produces + + mv foo bar + +Since the lines containing `@example' and `@end example' will +disappear, you will want to put a blank line before the `@example' +and another blank line after the `@end example'. (Remember that +blank lines between the beginning `@example' and the ending `@end +example' will appear in the output.) + +Don't use tabs in lines of an example! TeX has trouble with tabs: +it treats them like single spaces, and that is not what they look like. + + + +File: texinfo, Node: Display, Prev: Example, Up: Quotations and Examples + +@display +======== + +`@display' is just like `@example' except that, in the printed +manual, `@display' does not select the fixed-width font. In fact, it +does not specify the font at all, so that the text appears in the +same font it would have appeared in without the `@display'. + + + +File: texinfo, Node: Lists and Tables, Next: Cross References, Prev: Quotations and Examples, Up: Top + +Making Lists and Tables +*********************** + +Texinfo has several ways of making lists and two-column tables. +Lists can be bulleted or numbered while two-column tables can +highlight the items in the first column. + +For example, this is an enumerated list: + + 1. This is a numbered item. + + 2. This is the second item in this list. + + 3. This is the third item on this list. + +Texinfo will automatically indent the text in lists or tables and +number an enumerated list. This last feature is useful if you are +reordering the list, since you do not have to renumber it yourself. + +Lists or tables are always begun by an @-command on a line by itself +and ended with an `@end' command on a line by itself. For example, +an enumerated list begins with the command `@enumerate' and ends with +the command `@end enumerate'; and an itemized list begins with the +command `@itemize' and ends with the command `@end itemize'. + +The elements of a list are begun with the `@item' command. + +Here is an itemized list of the different kinds of table and lists: + + * Itemized lists with or without bullets. + + * Numbered lists. + + * two-column tables with highlighting. + +* Menu: + +* Itemize:: +* Enumerate:: +* Table:: + + + +File: texinfo, Node: Itemize, Next: Enumerate, Up: Lists and Tables + +@itemize +======== + +`@itemize' is used to produce sequences of indented paragraphs, with +a mark inside the left margin at the beginning of each paragraph. +The rest of the line that starts with `@itemize' should contain the +character or Texinfo commands to generate such a mark. Usually, it +is the @-command `@bullet'. Whatever mark you choose, ultimately, it +should result in a single character in the Texinfo file, or the +indentation will come out wrong. When you write the command, omit +the `{}' after the command if you use just one command and nothing +else. + +The text of the indented paragraphs themselves come after the +`@itemize', up to another line that says `@end itemize'. + +Before each paragraph for which a mark in the margin is desired, +place a line that says just `@item'. Don't put any other text on +this line. + +Info indents the lines in an itemized list by five columns, but it +does not fill them. This can produce lines in the Info file that are +too wide. You can either write shorter lines in the Texinfo file by +setting the fill column to five columns less than it is normally, or +else you can tell Info to refill the paragraphs by adding the +@-command `@refill' to the end of the paragraph. (*Note Refill::, for +more information about the use of the `@refill' command.) + +Usually, you should put a blank line before an `@item'. This puts a +blank like in the Info file. Except when the entries are very brief, +a blank line looks better. + +Here is an example of the use of `@itemize', followed by the output +it produces. Note that `@bullet' produces a `*' in Texinfo and a +round dot in TeX. + + @itemize @bullet + @item + Some text for foo. + + @item + Some text + for bar. + @end itemize + +produces + + * Some text for foo. + + * Some text for bar. + + + +File: texinfo, Node: Enumerate, Next: Table, Prev: Itemize, Up: Lists and Tables + +@enumerate +========== + +`@enumerate' is like `@itemize' except that the marks in the left +margin contain successive integers starting with 1. (*Note +Itemize::.) Do not put any argument on the same line as `@enumerate'. + + @enumerate + @item + Some text for foo. + @item + Some text + for bar. + @end enumerate + +produces + + 1. Some text for foo. + + 2. Some text for bar. + +If you want, you can put a blank line between the entries in the list. +This often makes it easier to read the Info file. For example, + + @enumerate + @item + This is the first item. + + @item + This is the second item. + @end enumerate + +Info indents the lines of the enumerated list by five columns, but it +does not fill them. As a result, the lines in the Info file may be +too wide. To prevent this, you can either write shorter lines in the +Texinfo file file by setting the fill column to five columns less +than it is normally, or else you can tell Info to refill the +paragraphs by adding the @-command `@refill' to the end of the +paragraph. (*Note Refill::, for more information about the use of +the `@refill' command.) + + + +File: texinfo, Node: Table, Prev: Enumerate, Up: Lists and Tables + +@table +====== + +`@table' is similar to `@itemize', but allows you to specify a name +or heading line for each item. (*Note Itemize::.) The command is +used to produce two-column tables, and is especially useful for +glossaries and explanatory exhibits. + +You must follow each use of `@item' inside of `@table' with text to +serve as the heading line for that item. This text is put on the +same line as the `@item' command. Each heading line is put into the +first column of the table and the supporting text, which you put on +the line following the line beginning with `@item', goes into the +second column. + +Also, `@table' itself must be followed by an argument that is a +Texinfo command such as `@code', `@var', `@kbd' or `@asis'. Although +these commands are usually followed by arguments in braces, in this +case you use the command name without an argument. (`@item' supplies +the argument.) This command will be applied to the text that goes +into the first column of each item and determines how it will be +highlighted. For example, `@samp' will cause the text in the first +column to be highlighted as if it were acted on by an `@samp' command. + +`@asis' is a command that does nothing; in that case, each item will +come out without highlighting, unless that particular piece of text +contains @-commands for highlighting. + +(Various other command names might work with `@table'. However, only +commands that normally take arguments in braces may be used.) + +Usually, you should put a blank line before an `@item'. This puts a +blank like in the Info file. Except when the entries are very brief, +a blank line looks better. + +The following table, for example, highlights the text in the first +column as if each item were acted on by an `@samp' command: + + @table @samp + @item foo + This is the text for + @samp{foo}. + + @item bar + Text for @samp{bar}. + @end table + +produces + + `foo' + This is the text for `foo'. + + `bar' + Text for `bar'. + +Info indents the lines of text in the second column, but does not +fill them. As a result, the lines in the Info file may be too wide. +To prevent this, cause Info to refill the paragraphs after processing +by adding the @-command `@refill' to the end of the paragraph. (*Note +Refill::, for more information about the use of the `@refill' command.) + +If you want to list two or more named items with a single block of +text, use the `@itemx' command. + +* Menu: + +* Itemx:: + + + +File: texinfo, Node: Itemx, Prev: Table, Up: Table + +@itemx +------ + +`@itemx' is used inside a `@table' when you have two or more named +items for the same block of text. Use `@itemx' for all but the first +of the items. It works exactly like `@item' except that it does not +generate extra vertical space above the item text. For example, + + @table @code + @item upcase + @itemx downcase + These two functions accept a character or a string as argument, + and return the corresponding upper case (lower case) character + or string. @refill + @end table + +produces + + `upcase' + `downcase' + These two functions accept a character or a string as + argument, and return the corresponding upper case (lower + case) character or string. + +A more complicated example of the use of `@itemx' comes from the +chapter on structuring commands. Here is how the list showing how +the chapter structuring commands fall into four groups was constructed. +(*Note Chapter Structuring Commands: Structuring.) + + @table @code + @item @@chapter + @itemx @@unnumbered + @itemx @@appendix + For chapters and chapter-like parts of a document. + + @item @@section + @itemx @@unnumberedsec + @itemx @@appendixsec + For sections and section-like parts of a document. + + @item @@subsection + @itemx @@unnumberedsubsec + @itemx @@appendixsubsec + For subsections and subsection-like parts of a document. + + @item @@subsubsection + @itemx @@unnumberedsubsubsec + @itemx @@appendixsubsubsec + For subsubsections and similar parts of a document. + @end table + +and this is what the resulting table looks like: + +`@chapter' +`@unnumbered' +`@appendix' + For chapters and chapter-like parts of a document. + +`@section' +`@unnumberedsec' +`@appendixsec' + For sections and section-like parts of a document. + +`@subsection' +`@unnumberedsubsec' +`@appendixsubsec' + For subsections and subsection-like parts of a document. + +`@subsubsection' +`@unnumberedsubsubsec' +`@appendixsubsubsec' + For subsubsections and similar parts of a document. + +Also, either column of a table can be empty. + + + +File: texinfo, Node: Cross References, Next: Formatting Paragraphs, Prev: Lists and Tables, Up: Top + +Making Cross References +*********************** + +Cross references are used to refer the reader to other parts of the +same or different Texinfo files. In Texinfo, "nodes" are the points +to which cross-references can refer. + +In general, a document should be designed so that it can be read +sequentially. People soon tire of flipping back and forth to find +information that should be presented to them as they need it. +However, there will be information (often too detailed for whatever +the current context may be) that is related to whatever is presented +and to which reference should be made. More important, in an on-line +help system or in a reference manual, readers do *not* read +everything in sequence from beginning to end. Instead, they look up +what they need. For this reason, such creations should contain many +cross references to help the reader find other information that he or +she may not have read. + +Although nodes are not a fundamental concept in a printed manual, +they still serve to define a cross-reference point and the variants +of `@xref' still serve to make references. Thus, if you are writing +a manual that will only be printed, and will not be used on-line, you +continue to use the `@node' command for when you make cross references. + +There are several kinds of cross reference command. + +`@xref' + Used to start a sentence in the printed manual saying, `See ...' + or an entry in the Info file saying `*note ...'. + +`@pxref' + Used to make a reference that starts with a lowercase `see' + and is usually contained within parentheses. + +`@inforef' + Used to make a reference to an Info file for which there is no + printed manual. + +* Menu: + +* Xref:: +* Pxref:: +* Inforef:: + + + +File: texinfo, Node: Xref, Next: Pxref, Prev: Cross References, Up: Cross References + +@xref +===== + +`@xref' generates a cross-reference. In Texinfo, it turns into an +Info cross-reference which the Info `f' command can use to go +directly to another node. In TeX, it turns into a sentence of the form + + See section SECTION [TOPIC], page PAGE + +but does not generate a period to end it. + +`@xref' must refer to an Info node created by `@node', by the node's +name. + +`@xref' is followed by an argument inside braces; but actually the +text inside the braces is treated as several arguments, separated by +commas. Whitespace after these commas is ignored. A period or comma +*must* follow the closing brace of an `@xref'. It is required to +terminate the cross reference. This period or comma will appear in +the output, both in the Info file and in the printed manual. + +The simplest form of `@xref' takes one argument, the name of another +node in the same Info file. Here we show the input text, followed by +a blank line and then the output text for Info files and the output +text for printed manuals. + + @xref{node-name}, for more info. + + *note node-name::, for more info. + + See section NNN [node-name], page PPP, for more info. + +With two arguments, the second one is used as the name of the Info +cross-reference, while the first argument is still the node that the +cross-reference points to: + + @xref{node-name, name-for-note}, for more info. + + *note name-for-note: node-name, for more info. + + See section NNN [node-name], page PPP, for more info. + +A third argument replaces the node name when it actually appears in +the TeX output. It should state the topic discussed by the section +being referenced. Often, you will want to use initial uppercase +letters so it will be easier to read when the reference is printed. +Use a third argument when the node name is unsuitable because of +syntax, grammar or diction. + + @xref{node-name, name-for-note, Topic Description}, for more info. + + *note name-for-note: node-name, for more info. + + See section NNN [Topic Description], page PPP, for more info. + +If a third argument is given and the second one is empty, then the +third argument serves both purposes: + + @xref{node-name, , Topic Description}, for more info. + + *note Topic Description: node-name, for more info. + + See section NNN [Topic Description], page PPP, for more info. + +A fourth argument specifies the name of the Info file in which the +referenced node is located, assuming it is not the one in which the +reference appears. `@xref' with only four arguments is used when the +reference is not within one Info file, but is within a single printed +manual--when multiple Texinfo files are incorporated into the same +TeX run but make separate Info files. (This is seldom the case and +usually you will use five arguments if you are making a reference +that is outside the current Info file.) + + @xref{node-name, name-for-note, Topic, info-file-name}, + for more info. + + *note name-for-note: (info-file-name) node-name, for more info. + + See section NNN [Topic], page PPP, for more info. + +A fifth argument is used when you are making a reference to another +Info file which is also part of another printed manual. Write the +title of the manual in this slot. Since a different manual is made +during a different TeX run, the printed reference will not have a +page number. + +Whenever you refer to another manual, use this version of `@xref' +with five arguments. + + @xref{node-name, name-for-note, Topic, info-file-name, A Printed Manual}, + for more info. + + *note name-for-note: (info-file-name) node-name, for more info. + + See section Topic of A Printed Manual, for more info. + +The name of the printed manual will be typeset in italics. + +Often, you will leave out the second argument when you use the long +version of `@xref'. In this case, the third argument, the topic +description, will replace the node name: + + @xref{node-name, , Topic Description, info-file-name, A Printed Manual}, + for more info. + + *note Topic Description: (info-file-name) node-name, for more info. + + See section Topic Description of A Printed Manual, for more info. + + + +File: texinfo, Node: Pxref, Next: Inforef, Prev: Xref, Up: Cross References + +@pxref +====== + +`@pxref' is nearly the same as `@xref'; it differs in only two ways: + + 1. The output starts with lower case `see' rather than `See'. + + 2. A period is generated automatically in the Info file output to + end the Info cross-reference, but no period is generated for the + printed manual. + +The purpose of `@pxref' is to be used inside parentheses as part of +another sentence. In the printed manual, no period is needed after +the cross reference text itself (within the parentheses), but a +period is needed after the cross reference text in the Info file +because only thus can Info recognize the end of the cross-reference. +`@pxref' spares you the need to use complicated methods to put a +period into one form of the output and not the other. + +`@pxref' can be used with up to five arguments just like `@xref'. +(*Note Xref::.) + + + +File: texinfo, Node: Inforef, Prev: Pxref, Up: Cross References + +@inforef +======== + +`@inforef' is used for cross-references to Info files for which there +are no printed manuals. Even in a printed manual, `@inforef' +generates a reference directing the user to look in an Info file. +`@inforef' takes exactly three arguments. The syntax is +`@inforef{NODE, NAME, FILE}'. + + @inforef{node-name, name-for-note, info-file-name}, for more information. + + *note name-for-note: (info-file-name) node-name, for more information. + + See Info file `info-file-name', node `node-name', for more + information. + + + +File: texinfo, Node: Formatting Paragraphs, Next: Marking Text, Prev: Cross References, Up: Top + +Formatting Paragraphs +********************* + +Usually, a Texinfo file will be processed both by TeX and by the `M-x +texinfo-format-buffer' command. Consequently, you must make sure +that text will come out looking right both in the printed manual and +in the on-line help. + +For example, unless told otherwise, `M-x texinfo-format-buffer' will +not refill a paragraph after processing it although TeX will. This +means that a paragraph with numerous or large @-commands may not look +properly filled after processing by Info. The @-commands are removed +from the text but the lines are not refilled so some are much shorter +than they were. To cause the `M-x texinfo-format-buffer' command to +refill such a paragraph, put `@refill' at the end of the paragraph. + +TeX may also format a document improperly. For example, page breaks +may occur in the "wrong place"; to control this, text can be held +together by a group command that keeps the text within the group from +being split across two pages. + +* Menu: + +* Refilling & Noindent:: Refilling paragraphs & preventing indentation +* Breaks Blank-Lines Groups:: Line and paragraph breaks, blank lines, grouping + + + +File: texinfo, Node: Refilling & Noindent, Next: Breaks Blank-Lines Groups, Prev: Formatting Paragraphs, Up: Formatting Paragraphs + +Refilling Paragraphs and Preventing Indentation +=============================================== + +The `@refill' and `@noindent' commands are used just after or just +before paragraphs which, after processing by either Info or TeX, +might look bad. The `@refill' command refills a paragraph in the +Info file after all the other processing has been done. In the +printed manual, the `@noindent' command prevents a piece of text that +is a continuation of the preceding paragraph from being indented as +if it were a new paragraph. + +* Menu: + +* Refill:: Refilling an info paragraph after other processing. +* Noindent:: Preventing paragraph indentation in continuation text. + + + +File: texinfo, Node: Refill, Next: Noindent, Prev: Refilling & Noindent, Up: Refilling & Noindent + +@refill +------- + +If a paragraph contains sizable @-constructs, it may look badly +filled after `texinfo-format-buffer' is through with it. + +Put `@refill' at the end of the paragraph to tell +`texinfo-format-buffer' to refill the paragraph after finishing all +other processing on it. `@refill' has no effect on TeX, which always +fills everything that ought to be filled. For example, + + To use @code{foo}, pass @samp{xx%$} and @var{flag} and type @kbd{x} + after running @code{make-foo}.@refill + +produces (in the Info file) + + To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'. + + whereas without the `@refill' it would produce + + To use `foo', pass `xx%$' and FLAG and type `x' + after running `make-foo'. + + with the line broken at the same place as in the Texinfo input file. + +Do not put a space before `@refill'; otherwise the command might be +put at the beginning of the line when you refill the paragraph in the +Texinfo file with `M-q' (`fill-paragraph'). If this were to happen, +the `@refill' command might fail to work + + + +File: texinfo, Node: Noindent, Prev: Refill, Up: Refilling & Noindent + +@noindent +--------- + +If you have text following an `@example' or other similar "special +paragraph" that reads as a continuation of the text before the +`@example', it is good to prevent this text from being indented as a +new paragraph. To accomplish this, put `@noindent' on a line by +itself before the start of the text that should not be indented. For +example, + + @example + This is an example + @end example + + @noindent + This line will not be indented. + + produces + + This is an example + +This line will not be indented. + +To adjust the number of blank lines properly in the Info file output, +remember that the line containing `@noindent' does not generate a +blank line, and neither does the `@end example' line. + +In the Texinfo source file for this documentation, each of the lines +that says `produces' is preceded by a line containing `@noindent'. + + |