diff options
Diffstat (limited to 'gnu/usr.bin/texinfo/info-files/texi.info-5')
| -rw-r--r-- | gnu/usr.bin/texinfo/info-files/texi.info-5 | 1433 |
1 files changed, 1433 insertions, 0 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-5 b/gnu/usr.bin/texinfo/info-files/texi.info-5 new file mode 100644 index 0000000..84b7295 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-5 @@ -0,0 +1,1433 @@ +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: var, Next: file, Prev: samp, Up: Indicating + +`@var'{METASYNTACTIC-VARIABLE} +------------------------------ + + Use the `@var' command to indicate metasyntactic variables. A +"metasyntactic variable" is something that stands for another piece of +text. For example, you should use a metasyntactic variable in the +documentation of a function to describe the arguments that are passed +to that function. + + Do not use `@var' for the names of particular variables in +programming languages. These are specific names from a program, so +`@code' is correct for them. For example, the Lisp variable +`texinfo-tex-command' is not a metasyntactic variable; it is properly +formatted using `@code'. + + The effect of `@var' in the Info file is to change the case of the +argument to all upper case; in the printed manual, to italicize it. + + For example, + + To delete file @var{filename}, + type @code{rm @var{filename}}. + +produces + + To delete file FILENAME, type `rm FILENAME'. + +(Note that `@var' may appear inside `@code', `@samp', `@file', etc.) + + Write a metasyntactic variable all in lower case without spaces, and +use hyphens to make it more readable. Thus, the Texinfo source for the +illustration of how to begin a Texinfo manual looks like this: + + \input texinfo + @@setfilename @var{info-file-name} + @@settitle @var{name-of-manual} + +This produces: + + \input texinfo + @setfilename INFO-FILE-NAME + @settitle NAME-OF-MANUAL + + In some documentation styles, metasyntactic variables are shown with +angle brackets, for example: + + ..., type rm <filename> + +However, that is not the style that Texinfo uses. (You can, of course, +modify the sources to TeX and the Info formatting commands to output +the `<...>' format if you wish.) + + +File: texi.info, Node: file, Next: dfn, Prev: var, Up: Indicating + +`@file'{FILE-NAME} +------------------ + + Use the `@file' command to indicate text that is the name of a file, +buffer, or directory, or is the name of a node in Info. You can also +use the command for file name suffixes. Do not use `@file' for symbols +in a programming language; use `@code'. + + Currently, `@file' is equivalent to `@samp' in its effects. For +example, + + The @file{.el} files are in + the @file{/usr/local/emacs/lisp} directory. + +produces + + The `.el' files are in the `/usr/local/emacs/lisp' directory. + + +File: texi.info, Node: dfn, Next: cite, Prev: file, Up: Indicating + +`@dfn'{TERM} +------------ + + Use the `@dfn' command to identify the introductory or defining use +of a technical term. Use the command only in passages whose purpose is +to introduce a term which will be used again or which the reader ought +to know. Mere passing mention of a term for the first time does not +deserve `@dfn'. The command generates italics in the printed manual, +and double quotation marks in the Info file. For example: + + Getting rid of a file is called @dfn{deleting} it. + +produces + + Getting rid of a file is called "deleting" it. + + As a general rule, a sentence containing the defining occurrence of a +term should be a definition of the term. The sentence does not need to +say explicitly that it is a definition, but it should contain the +information of a definition--it should make the meaning clear. + + +File: texi.info, Node: cite, Prev: dfn, Up: Indicating + +`@cite'{REFERENCE} +------------------ + + Use the `@cite' command for the name of a book that lacks a +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file. + + (If a book is written in Texinfo, it is better to use a cross +reference command since a reader can easily follow such a reference in +Info. *Note `@xref': xref.) + + +File: texi.info, Node: Emphasis, Prev: Indicating, Up: Marking Text + +Emphasizing Text +================ + + Usually, Texinfo changes the font to mark words in the text +according to what category the words belong to; an example is the +`@code' command. Most often, this is the best way to mark words. +However, sometimes you will want to emphasize text without indicating a +category. Texinfo has two commands to do this. Also, Texinfo has +several commands that specify the font in which TeX will typeset text. +These commands have no affect on Info and only one of them, the `@r' +command, has any regular use. + +* Menu: + +* emph & strong:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. + + +File: texi.info, Node: emph & strong, Next: Smallcaps, Up: Emphasis + +`@emph'{TEXT} and `@strong'{TEXT} +--------------------------------- + + The `@emph' and `@strong' commands are for emphasis; `@strong' is +stronger. In printed output, `@emph' produces *italics* and `@strong' +produces *bold*. + + For example, + + @quotation + @strong{Caution:} @code{rm * .[^.]*} removes @emph{all} + files in the directory. + @end quotation + +produces: + + *Caution*: `rm * .[^.]*' removes *all* + files in the directory. + + The `@strong' command is seldom used except to mark what is, in +effect, a typographical element, such as the word `Caution' in the +preceding example. + + In the Info file, both `@emph' and `@strong' put asterisks around +the text. + + *Caution:* Do not use `@emph' or `@strong' with the word `Note'; + Info will mistake the combination for a cross reference. Use a + phrase such as *Please note* or *Caution* instead. + + +File: texi.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis + +`@sc'{TEXT}: The Small Caps Font +-------------------------------- + + Use the `@sc' command to set text in the printed output in a small +caps font and set text in the Info file in upper case letters. + + Write the text between braces in lower case, like this: + + The @sc{acm} and @sc{ieee} are technical societies. + +This produces: + + The ACM and IEEE are technical societies. + + TeX typesets the small caps font in a manner that prevents the +letters from `jumping out at you on the page'. This makes small caps +text easier to read than text in all upper case. The Info formatting +commands set all small caps text in upper case. + + If the text between the braces of an `@sc' command is upper case, +TeX typesets in full-size capitals. Use full-size capitals sparingly. + + You may also use the small caps font for a jargon word such as ATO +(a NASA word meaning `abort to orbit'). + + There are subtleties to using the small caps font with a jargon word +such as CDR, a word used in Lisp programming. In this case, you should +use the small caps font when the word refers to the second and +subsequent elements of a list (the CDR of the list), but you should use +`@code' when the word refers to the Lisp function of the same spelling. + + +File: texi.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis + +Fonts for Printing, Not Info +---------------------------- + + Texinfo provides four font commands that specify font changes in the +printed manual but have no effect in the Info file. `@i' requests +italic font (in some versions of TeX, a slanted font is used), `@b' +requests bold face, `@t' requests the fixed-width, typewriter-style +font used by `@code', and `@r' requests a roman font, which is the +usual font in which text is printed. All four commands apply to an +argument that follows, surrounded by braces. + + Only the `@r' command has much use: in example programs, you can use +the `@r' command to convert code comments from the fixed-width font to +a roman font. This looks better in printed output. + + For example, + + @lisp + (+ 2 2) ; @r{Add two plus two.} + @end lisp + +produces + + (+ 2 2) ; Add two plus two. + + If possible, you should avoid using the other three font commands. +If you need to use one, it probably indicates a gap in the Texinfo +language. + + +File: texi.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top + +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, you always begin a quotation or example by writing an +@-command at the beginning of a line by itself, and end it by writing +an `@end' command that is also at the beginning of a line by itself. +For instance, you begin an example by writing `@example' by itself at +the beginning of a line and end the example by writing `@end example' +on a line by itself, at the beginning of that line. + +* Menu: + +* Block Enclosing Commands:: Use different constructs for + different purposes. +* quotation:: How to write a quotation. +* example:: How to write an example in a fixed-width font. +* noindent:: How to prevent paragraph indentation. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the `@smallbook' option. +* display:: How to write an example in the current font. +* format:: How to write an example that does not narrow + the margins. +* exdent:: How to undo the indentation of a line. +* flushleft & flushright:: How to push text flushleft or flushright. +* cartouche:: How to draw cartouches around examples. + + +File: texi.info, Node: Block Enclosing Commands, Next: quotation, Up: Quotations and Examples + +The Block Enclosing Commands +============================ + + Here are commands for quotations and examples: + +`@quotation' + Indicate text that is quoted. The text is filled, indented, and + printed in a roman font by default. + +`@example' + Illustrate code, commands, and the like. The text is printed in a + fixed-width font, and indented but not filled. + +`@lisp' + Illustrate Lisp code. The text is printed in a fixed-width font, + and indented but not filled. + +`@smallexample' + Illustrate code, commands, and the like. Similar to `@example', + except that in TeX this command typesets text in a smaller font + for the smaller `@smallbook' format than for the 8.5 by 11 inch + format. + +`@smalllisp' + Illustrate Lisp code. Similar to `@lisp', except that in TeX this + command typesets text in a smaller font for the smaller + `@smallbook' format than for the 8.5 by 11 inch format. + +`@display' + Display illustrative text. The text is indented but not filled, + and no font is specified (so, by default, the font is roman). + +`@format' + Print illustrative text. The text is not indented and not filled + and no font is specified (so, by default, the font is roman). + + The `@exdent' command is used within the above constructs to undo +the indentation of a line. + + The `@flushleft' and `@flushright' commands are used to line up the +left or right margins of unfilled text. + + The `@noindent' command may be used after one of the above +constructs to prevent the following text from being indented as a new +paragraph. + + You can use the `@cartouche' command within one of the above +constructs to highlight the example or quotation by drawing a box with +rounded corners around it. (The `@cartouche' command affects only the +printed manual; it has no effect in the Info file; see *Note Drawing +Cartouches Around Examples: cartouche.) + + +File: texi.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples + +`@quotation' +============ + + The text of a quotation is processed normally except that: + + * the margins are closer to the center of the page, so the whole of + the quotation is indented; + + * the first lines of paragraphs are indented no more than other + lines; + + * in the printed output, interparagraph spacing is reduced. + + This is an example of text written between an `@quotation' command + and an `@end quotation' command. An `@quotation' command is most + often used to indicate text that is excerpted from another (real + or hypothetical) printed work. + + Write an `@quotation' command as text on a line by itself. This +line will disappear from the output. Mark the end of the quotation +with a line beginning with and containing only `@end quotation'. The +`@end quotation' line will likewise disappear from the output. Thus, +the following, + + @quotation + This is + a foo. + @end quotation + +produces + + This is a foo. + + +File: texi.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples + +`@example' +========== + + The `@example' command is used to indicate an example that is not +part of the running text, such as computer input or output. + + This is an example of text written between an + `@example' command + and an `@end example' command. + The text is indented but not filled. + + In the printed manual, the text is typeset in a + fixed-width font, and extra spaces and blank lines are + significant. In the Info file, an analogous result is + obtained by indenting each line with five spaces. + + Write an `@example' command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the example +with an `@end example' command, also written at the beginning of a line +by itself. The `@end example' will disappear from the output. + + For example, + + @example + mv foo bar + @end example + +produces + + mv foo bar + + Since the lines containing `@example' and `@end example' will +disappear, you should 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.) + + *Caution:* Do not use tabs in the lines of an example (or anywhere + else in Texinfo, for that matter)! TeX treats tabs as single + spaces, and that is not what they look like. This is a problem + with TeX. (If necessary, in Emacs, you can use `M-x untabify' to + convert tabs in a region to multiple spaces.) + + Examples are often, logically speaking, "in the middle" of a +paragraph, and the text continues after an example should not be +indented. The `@noindent' command prevents a piece of text from being +indented as if it were a new paragraph. (*Note noindent::.) + + (The `@code' command is used for examples of code that are embedded +within sentences, not set off from preceding and following text. *Note +`@code': code.) + + +File: texi.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples + +`@noindent' +=========== + + An example or other inclusion can break a paragraph into segments. +Ordinarily, the formatters indent text that follows an example as a new +paragraph. However, you can prevent this by writing `@noindent' at the +beginning of a line by itself preceding the continuation text. + + For example: + + @example + This is an example + @end example + + @noindent + This line is not indented. As you can see, the + beginning of the line is fully flush left with the line + that follows after it. (This whole example is between + @code{@@display} and @code{@@end display}.) + +produces + + This is an example + + + This line is not indented. As you can see, the + beginning of the line is fully flush left with the line + that follows after it. (This whole example is between + `@display' and `@end display'.) + + 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 manual, each line that says +`produces' is preceded by a line containing `@noindent'. + + Do not put braces after an `@noindent' command; they are not +necessary, since `@noindent' is a command used outside of paragraphs +(*note Command Syntax::.). + + +File: texi.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples + +`@lisp' +======= + + The `@lisp' command is used for Lisp code. It is synonymous with +the `@example' command. + + This is an example of text written between an + `@lisp' command and an `@end lisp' command. + + Use `@lisp' instead of `@example' so as to preserve information +regarding the nature of the example. This is useful, for example, if +you write a function that evaluates only and all the Lisp code in a +Texinfo file. Then you can use the Texinfo file as a Lisp library.(1) + + Mark the end of `@lisp' with `@end lisp' on a line by itself. + + ---------- Footnotes ---------- + + (1) It would be straightforward to extend Texinfo to work in a +similar fashion for C, FORTRAN, or other languages. + + +File: texi.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples + +`@smallexample' and `@smalllisp' +================================ + + In addition to the regular `@example' and `@lisp' commands, Texinfo +has two other "example-style" commands. These are the `@smallexample' +and `@smalllisp' commands. Both these commands are designed for use +with the `@smallbook' command that causes TeX to produce a printed +manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 +inch format. + + In TeX, the `@smallexample' and `@smalllisp' commands typeset text +in a smaller font for the smaller `@smallbook' format than for the 8.5 +by 11 inch format. Consequently, many examples containing long lines +fit in a narrower, `@smallbook' page without needing to be shortened. +Both commands typeset in the normal font size when you format for the +8.5 by 11 inch size; indeed, in this situation, the `@smallexample' and +`@smalllisp' commands are defined to be the `@example' and `@lisp' +commands. + + In Info, the `@smallexample' and `@smalllisp' commands are +equivalent to the `@example' and `@lisp' commands, and work exactly the +same. + + Mark the end of `@smallexample' or `@smalllisp' with `@end +smallexample' or `@end smalllisp', respectively. + + This is an example of text written between `@smallexample' and + `@end smallexample'. In Info and in an 8.5 by 11 inch manual, + this text appears in its normal size; but in a 7 by 9.25 inch manual, + this text appears in a smaller font. + + The `@smallexample' and `@smalllisp' commands make it easier to +prepare smaller format manuals without forcing you to edit examples by +hand to fit them onto narrower pages. + + As a general rule, a printed document looks better if you write all +the examples in a chapter consistently in `@example' or in +`@smallexample'. Only occasionally should you mix the two formats. + + *Note Printing "Small" Books: smallbook, for more information about +the `@smallbook' command. + + +File: texi.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples + +`@display' +========== + + The `@display' command begins a kind of example. It is like the +`@example' command except that, in a 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' command. + + This is an example of text written between an `@display' command + and an `@end display' command. The `@display' command + indents the text, but does not fill it. + + +File: texi.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples + +`@format' +========= + + The `@format' command is similar to `@example' except that, in the +printed manual, `@format' does not select the fixed-width font and does +not narrow the margins. + +This is an example of text written between an `@format' command +and an `@end format' command. As you can see +from this example, +the `@format' command does not fill the text. + + +File: texi.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples + +`@exdent': Undoing a Line's Indentation +======================================= + + The `@exdent' command removes any indentation a line might have. +The command is written at the beginning of a line and applies only to +the text that follows the command that is on the same line. Do not use +braces around the text. In a printed manual, the text on an `@exdent' +line is printed in the roman font. + + `@exdent' is usually used within examples. Thus, + + @example + This line follows an @@example command. + @exdent This line is exdented. + This line follows the exdented line. + The @@end example comes on the next line. + @end group + +produces + + This line follows an @example command. +This line is exdented. + This line follows the exdented line. + The @end example comes on the next line. + + In practice, the `@exdent' command is rarely used. Usually, you +un-indent text by ending the example and returning the page to its +normal width. + + +File: texi.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples + +`@flushleft' and `@flushright' +============================== + + The `@flushleft' and `@flushright' commands line up the ends of +lines on the left and right margins of a page, but do not fill the +text. The commands are written on lines of their own, without braces. +The `@flushleft' and `@flushright' commands are ended by `@end +flushleft' and `@end flushright' commands on lines of their own. + + For example, + + @flushleft + This text is + written flushleft. + @end flushleft + +produces + + This text is + written flushleft. + + Flushright produces the type of indentation often used in the return +address of letters. + +For example, + + @flushright + Here is an example of text written + flushright. The @code{@flushright} command + right justifies every line but leaves the + left end ragged. + @end flushright + +produces + + Here is an example of text written + flushright. The `@flushright' command + right justifies every line but leaves the + left end ragged. + + +File: texi.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples + +Drawing Cartouches Around Examples +================================== + + In a printed manual, the `@cartouche' command draws a box with +rounded corners around its contents. You can use this command to +further highlight an example or quotation. For instance, you could +write a manual in which one type of example is surrounded by a cartouche +for emphasis. + + The `@cartouche' command affects only the printed manual; it has no +effect in the Info file. + + For example, + + @example + @cartouche + % pwd + /usr/local/lib/emacs/info + @end cartouche + @end example + +surrounds the two-line example with a box with rounded corners, in the +printed manual. + + +File: texi.info, Node: Lists and Tables, Next: Indices, 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. + +* Menu: + +* Introducing Lists:: Texinfo formats lists for you. +* itemize:: How to construct a simple list. +* enumerate:: How to construct a numbered list. +* Two-column Tables:: How to construct a two-column table. + + +File: texi.info, Node: Introducing Lists, Next: itemize, Up: Lists and Tables + +Introducing Lists +================= + + Texinfo automatically indents the text in lists or tables, and +numbers an enumerated list. This last feature is useful if you modify +the list, since you do not need to renumber it yourself. + + Numbered lists and tables begin with the appropriate @-command at the +beginning of a line, and end with the corresponding `@end' command on a +line by itself. The table and itemized-list commands also require that +you write formatting information on the same line as the beginning +@-command. + + Begin an enumerated list, for example, with an `@enumerate' command +and end the list with an `@end enumerate' command. Begin an itemized +list with an `@itemize' command, followed on the same line by a +formatting command such as `@bullet', and end the list with an `@end +itemize' command. + + Precede each element of a list with an `@item' or `@itemx' command. + +Here is an itemized list of the different kinds of table and lists: + + * Itemized lists with and without bullets. + + * Enumerated lists, using numbers or letters. + + * Two-column tables with highlighting. + +Here is an enumerated list with the same items: + + 1. Itemized lists with and without bullets. + + 2. Enumerated lists, using numbers or letters. + + 3. Two-column tables with highlighting. + +And here is a two-column table with the same items and their @-commands: + +`@itemize' + Itemized lists with and without bullets. + +`@enumerate' + Enumerated lists, using numbers or letters. + +`@table' +`@ftable' +`@vtable' + Two-column tables with highlighting. + + +File: texi.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables + +Making an Itemized List +======================= + + The `@itemize' command produces sequences of indented paragraphs, +with a bullet or other mark inside the left margin at the beginning of +each paragraph for which such a mark is desired. + + Begin an itemized list by writing `@itemize' at the beginning of a +line. Follow the command, on the same line, with a character or a +Texinfo command that generates a mark. Usually, you will write +`@bullet' after `@itemize', but you can use `@minus', or any character +or any special symbol that results in a single character in the Info +file. (When you write `@bullet' or `@minus' after an `@itemize' +command, you may omit the `{}'.) + + Write the text of the indented paragraphs themselves after the +`@itemize', up to another line that says `@end itemize'. + + Before each paragraph for which a mark in the margin is desired, +write a line that says just `@item'. Do not write any other text on +this line. + + Usually, you should put a blank line before an `@item'. This puts a +blank line in the Info file. (TeX inserts the proper interline +whitespace in either case.) Except when the entries are very brief, +these blank lines make the list look better. + + Here is an example of the use of `@itemize', followed by the output +it produces. Note that `@bullet' produces an `*' in Info and a round +dot in TeX. + + @itemize @bullet + @item + Some text for foo. + + @item + Some text + for bar. + @end itemize + +This produces: + + * Some text for foo. + + * Some text for bar. + + Itemized lists may be embedded within other itemized lists. Here is +a list marked with dashes embedded in a list marked with bullets: + + @itemize @bullet + @item + First item. + + @itemize @minus + @item + Inner item. + + @item + Second inner item. + @end itemize + + @item + Second outer item. + @end itemize + +This produces: + + * First item. + + - Inner item. + + - Second inner item. + + * Second outer item. + + +File: texi.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables + +Making a Numbered or Lettered List +================================== + + `@enumerate' is like `@itemize' except that the marks in the left +margin contain successive integers or letters. (*Note `@itemize': +itemize.) + + Write the `@enumerate' command at the beginning of a line. The +command does not require an argument, but accepts either a number or a +letter as an option. Without an argument, `@enumerate' starts the list +with the number 1. With a numeric argument, such as 3, the command +starts the list with that number. With an upper or lower case letter, +such as `a' or `A', the command starts the list with that letter. + + Write the text of the enumerated list in the same way you write an +itemized list: put `@item' on a line of its own before the start of +each paragraph that you want enumerated. Do not write any other text on +the line beginning with `@item'. + + You should put a blank line between entries in the list. This +generally makes it easier to read the Info file. + + Here is an example of `@enumerate' without an argument: + + @enumerate + @item + Underlying causes. + + @item + Proximate causes. + @end enumerate + +This produces: + + 1. Underlying causes. + + 2. Proximate causes. + + Here is an example with an argument of `3': + + @enumerate 3 + @item + Predisposing causes. + + @item + Precipitating causes. + + @item + Perpetuating causes. + @end enumerate + +This produces: + + 3. Predisposing causes. + + 4. Precipitating causes. + + 5. Perpetuating causes. + + Here is a brief summary of the alternatives. The summary is +constructed using `@enumerate' with an argument of `a'. + + a. `@enumerate' + + Without an argument, produce a numbered list, starting with the + number 1. + + b. `@enumerate POSITIVE-INTEGER' + + With a (positive) numeric argument, start a numbered list with that + number. You can use this to continue a list that you interrupted + with other text. + + c. `@enumerate UPPER-CASE-LETTER' + + With an upper case letter as argument, start a list in which each + item is marked by a letter, beginning with that upper case letter. + + d. `@enumerate LOWER-CASE-LETTER' + + With a lower case letter as argument, start a list in which each + item is marked by a letter, beginning with that lower case letter. + + You can also nest enumerated lists, as in an outline. + + +File: texi.info, Node: Two-column Tables, Prev: enumerate, Up: Lists and Tables + +Making a Two-column Table +========================= + + `@table' is similar to `@itemize', but the command allows you to +specify a name or heading line for each item. (*Note `@itemize': +itemize.) The `@table' command is used to produce two-column tables, +and is especially useful for glossaries and explanatory exhibits. + +* Menu: + +* table:: How to construct a two-column table. +* ftable vtable:: How to construct a two-column table + with automatic indexing. +* itemx:: How to put more entries in the first column. + + +File: texi.info, Node: table, Next: ftable vtable, Up: Two-column Tables + +Using the `@table' Command +-------------------------- + + Use the `@table' command to produce two-column tables. + + Write the `@table' command at the beginning of a line and follow it +on the same line with an argument that is a Texinfo command such as +`@code', `@samp', `@var', or `@kbd'. Although these commands are +usually followed by arguments in braces, in this case you use the +command name without an argument because `@item' will supply 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 with an `@samp' command. + + You may also choose to use the `@asis' command as an argument to +`@table'. `@asis' is a command that does nothing; if you use this +command after `@table', TeX and the Info formatting commands output the +first column entries without added highlighting (`as is'). + + (The `@table' command may work with other commands besides those +listed here. However, you can only use commands that normally take +arguments in braces.) + + Begin each table entry with an `@item' command at the beginning of a +line. Write the first column text on the same line as the `@item' +command. Write the second column text on the line following the +`@item' line and on subsequent lines. (You do not need to type +anything for an empty second column entry.) You may write as many +lines of supporting text as you wish, even several paragraphs. But +only text on the same line as the `@item' will be placed in the first +column. + + Normally, you should put a blank line before an `@item' line. 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 with an `@samp' command: + + @table @samp + @item foo + This is the text for + @samp{foo}. + + @item bar + Text for @samp{bar}. + @end table + +This produces: + +`foo' + This is the text for `foo'. + +`bar' + Text for `bar'. + + If you want to list two or more named items with a single block of +text, use the `@itemx' command. (*Note `@itemx': itemx.) + + +File: texi.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables + +`@ftable' and `@vtable' +----------------------- + + The `@ftable' and `@vtable' commands are the same as the `@table' +command except that `@ftable' automatically enters each of the items in +the first column of the table into the index of functions and `@vtable' +automatically enters each of the items in the first column of the table +into the index of variables. This simplifies the task of creating +indices. Only the items on the same line as the `@item' commands are +indexed, and they are indexed in exactly the form that they appear on +that line. *Note Creating Indices: Indices, for more information about +indices. + + Begin a two-column table using `@ftable' or `@vtable' by writing the +@-command at the beginning of a line, followed on the same line by an +argument that is a Texinfo command such as `@code', exactly as you +would for an `@table' command; and end the table with an `@end ftable' +or `@end vtable' command on a line by itself. + + +File: texi.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables + +`@itemx' +-------- + + Use the `@itemx' command inside a table when you have two or more +first column entries for the same item, each of which should appear on +a line of its own. Use `@itemx' for all but the first entry. The +`@itemx' command works exactly like `@item' except that it does not +generate extra vertical space above the first column 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. + @end table + +This 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. + +(Note also that this example illustrates multi-line supporting text in +a two-column table.) + + +File: texi.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top + +Creating Indices +**************** + + Using Texinfo, you can generate indices without having to sort and +collate entries manually. In an index, the entries are listed 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, this information is a menu +entry leading to the first node referenced. + + Texinfo provides several predefined kinds of index: an index for +functions, an index for variables, an index for concepts, and so on. +You can combine indices or use them for other than their canonical +purpose. If you wish, you can define your own indices. + +* Menu: + +* Index Entries:: Choose different words for index entries. +* Predefined Indices:: Use different indices for different kinds + of entry. +* Indexing Commands:: How to make an index entry. +* Combining Indices:: How to combine indices. +* New Indices:: How to define your own indices. + + +File: texi.info, Node: Index Entries, Next: Predefined Indices, Up: Indices + +Making Index Entries +==================== + + When you are making index entries, it is good practice to think of +the different ways people may look for something. Different people *do +not* think of the same words when they look something up. A helpful +index will have items indexed under all the different words that people +may use. For example, one reader may 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 readers. + + Like typesetting, the construction of an index is a highly skilled, +professional art, the subtleties of which are not appreciated until you +need to do it yourself. + + *Note Printing Indices & Menus::, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +File: texi.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices + +Predefined Indices +================== + + Texinfo provides six predefined indices: + + * A "concept index" listing concepts that are discussed. + + * A "function index" listing functions (such as entry points of + libraries). + + * A "variables index" listing variables (such as global variables of + libraries). + + * A "keystroke index" listing keyboard commands. + + * A "program index" listing names of programs. + + * A "data type index" listing data types (such as structures defined + in header files). + +Not every manual needs all of these, and most manuals use two or three +of them. This manual has two indices: a concept index and an @-command +index (that is actually 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' or `@syncodeindex' commands. *Note +Combining Indices::. + + +File: texi.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices + +Defining the Entries of an Index +================================ + + The data to make an index come from many individual indexing commands +scattered throughout the Texinfo source file. Each command says to add +one entry to a particular index; after formatting, the index will give +the current page number or node name as the reference. + + An index entry consists of an indexing command at the beginning of a +line followed, on the rest of the line, by the entry. + + For example, this section begins with the following five entries for +the concept index: + + @cindex Defining indexing entries + @cindex Index entries + @cindex Entries for an index + @cindex Specifying index entries + @cindex Creating index entries + + Each predefined index has its own indexing command--`@cindex' for +the concept index, `@findex' for the function index, and so on. + + The usual convention is to capitalize the first word of each index +entry, unless that word is the name of a function, variable, or other +such entity that should not be capitalized. Thus, if you are +documenting Emacs Lisp, you should usually capitalize entries in the +concept index, but not those in the function index. However, if your +concept index entries are consistently short (one or two words each) it +may look better for each regular entry to start with a lower case +letter. Whichever convention you adapt, please be consistent! + + By default, entries for a concept index are printed in a small roman +font and entries for the other indices are printed in a small `@code' +font. You may change the way part of an entry is printed with the +usual Texinfo commands, such as `@file' for file names and `@emph' for +emphasis (*note Marking Text::.). + + The six indexing commands for predefined indices are: + +`@cindex CONCEPT' + Make an entry in the concept index for CONCEPT. + +`@findex FUNCTION' + Make an entry in the function index for FUNCTION. + +`@vindex VARIABLE' + Make an entry in the variable index for VARIABLE. + +`@kindex KEYSTROKE' + Make an entry in the key index for KEYSTROKE. + +`@pindex PROGRAM' + Make an entry in the program index for PROGRAM. + +`@tindex DATA TYPE' + Make an entry in the data type index for DATA TYPE. + + *Caution:* Do not use a colon in an index entry. In Info, a colon + separates the menu entry name from the node name. An extra colon + confuses Info. *Note The Parts of a Menu: Menu Parts, for more + information about the structure of a menu entry. + + If you write several identical index entries in different places in a +Texinfo file, the index in the printed manual will list all the pages to +which those entries refer. However, the index in the Info file will +list *only* the node that references the *first* of those index +entries. Therefore, it is best to write indices in which each entry +refers to only one place in the Texinfo file. Fortunately, this +constraint is a feature rather than a loss since it means that the index +will be easy to use. Otherwise, you could create an index that lists +several pages for one entry and your reader would not know to which page +to turn. If you have two identical entries for one topic, change the +topics slightly, or qualify them to indicate the difference. + + You are not actually required to use the predefined indices for their +canonical purposes. For example, suppose you 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" as an unnumbered chapter, 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. (*Note Printing +Indices & Menus::.) + + +File: texi.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices + +Combining Indices +================= + + Sometimes you will want to combine two disparate indices such as +functions and concepts, perhaps because you have few enough of one of +them that a separate index for them would look silly. + + You could put functions into the concept index by writing `@cindex' +commands for them instead of `@findex' commands, and produce a +consistent manual by printing the concept index with the title +`Function and Concept Index' and not printing the `Function Index' at +all; but this is not a robust procedure. It works only if your +document is never included as part of another document that is designed +to have a separate function index; if your document were to be included +with such a document, the functions from your document and those from +the other would not end up together. Also, to make your function names +appear in the right font in the concept index, you would need to +enclose every one of them between the braces of `@code'. + +* Menu: + +* syncodeindex:: How to merge two indices, using `@code' + font for the merged-from index. +* synindex:: How to merge two indices, using the + default font of the merged-to index. + + +File: texi.info, Node: syncodeindex, Next: synindex, Up: Combining Indices + +`@syncodeindex' +............... + + When you want to combine functions and concepts into one index, you +should index the functions with `@findex' and index the concepts with +`@cindex', and use the `@syncodeindex' command to redirect the function +index entries into the concept index. + + The `@syncodeindex' command takes two arguments; they are the name +of the index to redirect, and the name of the index to redirect it to. +The template looks like this: + + @syncodeindex FROM TO + + For this purpose, the indices are given two-letter names: + +`cp' + concept index + +`fn' + function index + +`vr' + variable index + +`ky' + key index + +`pg' + program index + +`tp' + data type index + + Write an `@syncodeindex' command before or shortly after the +end-of-header line at the beginning of a Texinfo file. For example, to +merge a function index with a concept index, write the following: + + @syncodeindex fn cp + +This will cause all entries designated for the function index to merge +in with the concept index instead. + + To merge both a variables index and a function index into a concept +index, write the following: + + @syncodeindex vr cp + @syncodeindex fn cp + + The `@syncodeindex' command puts all the entries from the `from' +index (the redirected index) into the `@code' font, overriding whatever +default font is used by the index to which the entries are now +directed. This way, if you direct function names from a function index +into a concept index, all the function names are printed in the `@code' +font as you would expect. + + +File: texi.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices + +`@synindex' +........... + + The `@synindex' command is nearly the same as the `@syncodeindex' +command, except that it does not put the `from' index entries into the +`@code' font; rather it puts them in the roman font. Thus, you use +`@synindex' when you merge a concept index into a function index. + + *Note Printing Indices & Menus::, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +File: texi.info, Node: New Indices, Prev: Combining Indices, Up: Indices + +Defining New Indices +==================== + + In addition to the predefined indices, you may use the `@defindex' +and `@defcodeindex' commands to define new indices. These commands +create new indexing @-commands with which you mark index entries. The +`@defindex 'command is used like this: + + @defindex NAME + + The name of an index should be a two letter word, such as `au'. For +example: + + @defindex au + + This defines a new index, called the `au' index. At the same time, +it creates a new indexing command, `@auindex', that you can use to make +index entries. Use the new indexing command just as you would use a +predefined indexing command. + + For example, here is a section heading followed by a concept index +entry and two `au' index entries. + + @section Cognitive Semantics + @cindex kinesthetic image schemas + @auindex Johnson, Mark + @auindex Lakoff, George + +(Evidently, `au' serves here as an abbreviation for "author".) Texinfo +constructs the new indexing command by concatenating the name of the +index with `index'; thus, defining an `au' index leads to the automatic +creation of an `@auindex' command. + + Use the `@printindex' command to print the index, as you do with the +predefined indices. For example: + + @node Author Index, Subject Index, , Top + @unnumbered Author Index + + @printindex au + + The `@defcodeindex' is like the `@defindex' command, except that, in +the printed output, it prints entries in an `@code' font instead of a +roman font. Thus, it parallels the `@findex' command rather than the +`@cindex' command. + + You should define new indices within or right after the end-of-header +line of a Texinfo file, before any `@synindex' or `@syncodeindex' +commands (*note Header::.). + + +File: texi.info, Node: Insertions, Next: Glyphs, Prev: Indices, Up: Top + +Special Insertions +****************** + + Texinfo provides several commands for formatting dimensions, for +inserting single characters that have special meaning in Texinfo, such +as braces, and for inserting special graphic symbols that do not +correspond to characters, such as dots and bullets. + +* Menu: + +* Braces Atsigns Periods:: How to insert braces, `@' and periods. +* dmn:: How to format a dimension. +* Dots Bullets:: How to insert dots and bullets. +* TeX and copyright:: How to insert the TeX logo + and the copyright symbol. +* minus:: How to insert a minus sign. + + +File: texi.info, Node: Braces Atsigns Periods, Next: dmn, Up: Insertions + +Inserting `@', Braces, and Periods +================================== + + `@' and curly braces are special characters in Texinfo. To insert +these characters so they appear in text, you must put an `@' in front +of these characters to prevent Texinfo from misinterpreting them. + + Periods are also special. Depending on whether the period is inside +or at the end of a sentence, less or more space is inserted after a +period in a typeset manual. Since it is not always possible for +Texinfo to determine when a period ends a sentence and when it is used +in an abbreviation, special commands are needed in some circumstances. +(Usually, Texinfo can guess how to handle periods, so you do not need +to use the special commands; you just enter a period as you would if +you were using a typewriter, which means you put two spaces after the +period, question mark, or exclamation mark that ends a sentence.) + + Do not put braces after any of these commands; they are not +necessary. + +* Menu: + +* Inserting An Atsign:: +* Inserting Braces:: How to insert `{' and `}' +* Controlling Spacing:: How to insert the right amount of space + after punctuation within a sentence. + |
