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, 0 insertions, 1433 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-5 b/gnu/usr.bin/texinfo/info-files/texi.info-5 deleted file mode 100644 index 84b7295..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-5 +++ /dev/null @@ -1,1433 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Free Software Foundation. - - -File: texi.info, Node: 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. - |
