NAME-OF-MANUAL

‘i’, ‘o’, ‘u’, and sometimes ‘y’. This produces: In English, the vowels are ‘a’, ‘e’, ‘i’, ‘o’, ‘u’, and sometimes ‘y’. File: texinfo.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 filename, type rm 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 info-file-name @settitle name-of-manual This produces: \input texinfo 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: texinfo.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 ‘.el’ files are in the ‘/usr/local/emacs/lisp’ directory. produces The ‘.el’ files are in the ‘/usr/local/emacs/lisp’ directory. File: texinfo.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 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: texinfo.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: texinfo.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. * Customized Highlighting:: How to define highlighting commands. File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, 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,

Caution: rm * .[^.]* removes all files in the directory.

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: texinfo.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 ACM and 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: texinfo.info, Node: Fonts, Next: Customized Highlighting, 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, 

     (+ 2 2)    ; Add two plus two.

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: texinfo.info, Node: Customized Highlighting, Prev: Fonts, Up: Emphasis Customized Highlighting ———————– You can use regular TeX commands inside of ‘’ to create your own customized highlighting commands for Texinfo. The easiest way to do this is to equate your customized commands with pre-existing commands, such as those for italics. Such new commands work only with TeX. You can use the ‘commands for TeX. ‘@definfoenclosecommands for TeX. ‘’ creates new commands for Info that mark text by enclosing it in strings that precede and follow the text. (1) (*note Customized Highlighting-Footnotes::) Here is how to create a new command called ‘@phoo’ that causes TeX to typeset its argument in italics and causes Info to display the argument between ‘//’ and ‘\\’. For TeX, write the following to equate the ‘@phoo’ command with the existing ‘@i’ italics command: This defines ‘@phoo’ as a command that causes TeX to typeset the argument to ‘@phoo’ in italics. ‘@global@let’ tells TeX to equate the next argument with the argument that follows the equals sign. For Info, write the following to tell the Info formatters to enclose the argument between ‘//’ and ‘\\’: Write the ‘@definfoencloseWrite the ‘’ command on a line and follow it with three arguments separated by commas (commas are used as separators in an ‘@node’ line in the same way). * The first argument to ‘ *without* the ‘;' * the second argument is the Info start delimiter string; and, * the third argument is the Info end delimiter string. The latter two arguments enclose the highlighted text in the Info file. A delimiter string may contain spaces. Neither the start nor end delimiter is required. However, if you do not provide a start delimiter, you must follow the command name with two commas in a row; otherwise, the Info formatting commands will misinterpret the end delimiter string as a start delimiter string. After you have defined ‘@phoo’ both for TeX and for Info, you can then write ‘@phoo{bar}’ to see ‘//bar\\’ in Info and see ‘bar’ in italics in printed output. Note that each definition applies to its own formatter: one for TeX, the other for Info. Here is another example: This defines ‘@headword’ as an Info formatting command that inserts nothing before and a colon after the argument and as a TeX formatting command to typeset its argument in bold. File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting (1) Currently, ‘‘texinfo-format-buffer’ and ‘texinfo-format-region’, not with ‘makeinfo’. File: texinfo.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 ‘

' by itself at
the beginning of a line and end the example by writing `

’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 ‘* 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: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples The Block Enclosing Commands ============================ Here are commands for quotations and examples: ‘

’: Indicate text that is quoted. The text is filled, indented, and printed in a roman font by default. ‘

'
     Illustrate code, commands, and the like. The text is printed in a
     fixed-width font, and indented but not filled.
`
'
     Illustrate Lisp code. The text is printed in a fixed-width font,
     and indented but not filled.
`
'
     Illustrate code, commands, and the like.  Similar to `
',
     except that in TeX this command typesets text in a smaller font
     for the smaller `     format.
`
'
     Illustrate Lisp code.  Similar to `
', except that in TeX this
     command typesets text in a smaller font for the smaller
     ``
'
     Display illustrative text.  The text is indented but not filled,
     and no font is specified (so, by default, the font is roman).
`
'
     Print illustrative text.  The text is not indented and not filled
     and no font is specified (so, by default, the font is roman).
  The `' command is used within the above constructs to undo the
indentation of a line.
  The `
' and `
' commands are used to line up the
left or right margins of unfilled text.
  The `' 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 `
' command within one of the above
constructs to highlight the example or quotation by drawing a box with
rounded corners around it.  (The `
' command affects only the
printed manual; it has no effect in the Info file; see *Note Drawing
Cartouches Around Examples: cartouche.)
File: texinfo.info,  Node: quotation,  Next: example,  Prev: Block Enclosing Commands,  Up: Quotations and Examples
`
': ============
  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 `
' command:      and an `
'command.  An `
' command is most:      often used to indicate text that is excerpted from another (real
     or hypothetical) printed work.
  Write an `
' 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 `
'. The `@end
quotation' line will likewise disappear from the output.  Thus, the
following,
     
     This is
     a foo.
     
produces
     This is a foo.
File: texinfo.info,  Node: example,  Next: noindent,  Prev: quotation,  Up: Quotations and Examples
`
'
==========
  The `
' 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
     `
' command
     and an `
'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 `
' command at the beginning of a line by itself.
This line will disappear from the output.  Mark the end of the example
with an `
'command, also written at the beginning of a line
by itself.  The `
'will disappear from the output.
  For example,
     
     mv foo bar
     
produces
     mv foo bar
  Since the lines containing `
' and `
'will
disappear, you should put a blank line before the `
' and
another blank line after the `
'. (Remember that blank
lines between the beginning `
' and the ending `
'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 `' 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: texinfo.info,  Node: noindent,  Next: Lisp Example,  Prev: example,  Up: Quotations and Examples
`'
===========
  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 `' at the
beginning of a line by itself preceding the continuation text.
  For example:
     
     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.)
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
     `
' and `
'.)  To adjust the number of blank lines properly in the Info file output,
remember that the line containing `' does not generate a blank
line, and neither does the `
'line.
  In the Texinfo source file for this manual, each line that says
`produces' is preceded by a line containing `'.
  Do not put braces after an `' command; they are not
necessary, since `' is a command used outside of paragraphs
(*note Command Syntax::.).
File: texinfo.info,  Node: Lisp Example,  Next: smallexample & smalllisp,  Prev: noindent,  Up: Quotations and Examples
`
'
=======
  The `
' command is used for Lisp code.  It is synonymous with the
`
' command.
     This is an example of text written between an
     `
' command and an `
'command.
  Use `
' instead of `
' 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)
(*note Lisp Example-Footnotes::)
  Mark the end of `
' with `
'on a line by itself.
File: texinfo.info,  Node: Lisp Example-Footnotes,  Up: Lisp Example
  (1)  It would be straightforward to extend Texinfo to work in a
similar fashion for C, FORTRAN, or other languages.
File: texinfo.info,  Node: smallexample & smalllisp,  Next: display,  Prev: Lisp Example,  Up: Quotations and Examples
`
' and `
'
================================
  In addition to the regular `
' and `
' commands, Texinfo
has two other "example-style" commands.  These are the `
'
and `
' commands.  Both these commands are designed for use
with the `manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
inch format.
  In TeX, the `
' and `
' commands typeset text in
a smaller font for the smaller `11 inch format.  Consequently, many examples containing long lines fit
in a narrower, `commands typeset in the normal font size when you format for the 8.5 by
11 inch size; indeed, in this situation, the `
' and
`
' commands are defined to be the `
' and `
'
commands.
  In Info, the `
' and `
' commands are equivalent
to the `
' and `
' commands, and work exactly the same.
  Mark the end of `
' or `
' with `@end
smallexample' or `
',respectively.
     This is an example of text written between `
' and
     `
'. 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 `
' and `
' 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 `
' or in
`
'.  Only occasionally should you mix the two formats.
  *Note Printing "Small" Books: smallbook, for more information about
the `File: texinfo.info,  Node: display,  Next: format,  Prev: smallexample & smalllisp,  Up: Quotations and Examples
`
'
==========
  The `
' command begins a kind of example.  It is like the
`
' command except that, in a printed manual, `
' 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 `
' command.
     This is an example of text written between an `
' command
     and an `
'command.  The `
' command
     indents the text, but does not fill it.
File: texinfo.info,  Node: format,  Next: exdent,  Prev: display,  Up: Quotations and Examples
`
'
=========
  The `
' command is similar to `
' except that, in the
printed manual, `
' does not select the fixed-width font and does
not narrow the margins.
This is an example of text written between an `
' command
and an `
'command.  As you can see
from this example,
the `
' command does not fill the text.
File: texinfo.info,  Node: exdent,  Next: flushleft & flushright,  Prev: format,  Up: Quotations and Examples
`': Undoing a Line's Indentation
=======================================
  The `' 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 `'
line is printed in the roman font.
  `' is usually used within examples.  Thus,
     
     This line follows an @example command.
     This line is exdented.
     This line follows the exdented line.
     The @end example comes on the next line.

produces This line follows an 

command.
This line is exdented.
     This line follows the exdented line.
     The

comes on the next line. In practice, the ‘’ command is rarely used. Usually, you un-indent text by ending the example and returning the page to its normal width. File: texinfo.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples ‘

’ and ‘

’ ============================== The ‘

’ and ‘

’ 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 ‘

’ and ‘

’ commands are ended by ‘

’and ‘

’commands on lines of their own. For example,

This text is written flushleft.

produces This text is written flushleft. Flushright produces the type of indentation often used in the return address of letters. For example,

Here is an example of text written flushright. The

command right justifies every line but leaves the left end ragged.

produces Here is an example of text written flushright. The ‘

’ command right justifies every line but leaves the left end ragged. File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples Drawing Cartouches Around Examples ================================== In a printed manual, the ‘

’ 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 ‘

’ command affects only the printed manual; it has no effect in the Info file. For example, 

     
     % pwd
     /usr/local/lib/emacs/info

surrounds the two-line example with a box with rounded corners, in the printed manual. File: texinfo.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: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, 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 ‘

  1. ’ command and end the list with an ‘

’command. Begin an itemized list with an ‘

  • formatting command such as ‘•’, and end the list with an ‘@end itemize’ command. Precede each element of a list with an ‘
  • ’ command, followed on the same line by a ’ or ‘
  • ’ command, followed on the same line by a ’ 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: ‘
    • Itemized lists with and without bullets. ‘
      1. ’ Enumerated lists, using numbers or letters. ‘

        ‘

        ‘

        Two-column tables with highlighting. File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables Making an Itemized List ======================= The ‘

        • 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 ‘
          • line. Follow the command, on the same line, with a character or a Texinfo command that generates a mark. Usually, you will write ‘•’ after ‘
            • or any special symbol that results in a single character in the Info file. (When you write ‘•’ or ‘-’ after an ‘
              • command, you may omit the ‘{’.) Write the text of the indented paragraphs themselves after the ‘
                • Before each paragraph for which a mark in the margin is desired, write a line that says just ‘
                • ’, up to another line that says ‘

                ’.’. Do not write any other text on this line. Usually, you should put a blank line before an ‘

              • ’ ’. 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 ‘
                • it produces. Note that ‘•’ produces an ‘*’ in Info and a round dot in TeX.
                  • Some text for foo.
                  • Some text for bar.

                  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:

                  • First item.
                    • - Inner item.
                    • - Second inner item.
                  • Second outer item.

                  This produces: * First item. - Inner item. - Second inner item. * Second outer item. File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables Making a Numbered or Lettered List ================================== ‘

                  1. ’ is like ‘
                    • margin contain successive integers or letters. (*Note ‘
                      • itemize.) Write the ‘
                        1. ’ 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, ‘
                          1. ’ 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 ‘
                          2. ’ 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 ‘
                          3. ’. 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 ‘
                            1. ’ without an argument:
                              1. Underlying causes.
                              2. Proximate causes.

                              This produces: 1. Underlying causes. 2. Proximate causes. Here is an example with an argument of ‘3’:

                              1. Predisposing causes.
                              2. Precipitating causes.
                              3. Perpetuating causes.

                              This produces: 3. Predisposing causes. 4. Precipitating causes. 5. Perpetuating causes. Here is a brief summary of the alternatives. The summary is constructed using ‘

                              1. ’ with an argument of ‘a’. a. ‘
                                1. ’ Without an argument, produce a numbered list, starting with the number 1. b. ‘
                                  1. 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. ‘
                                    1. 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. ‘
                                      1. 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: texinfo.info, Node: Two-column Tables, Prev: enumerate, Up: Lists and Tables Making a Two-column Table ========================= ‘

                                        specify a name or heading line for each item. (*Note ‘

                                        • itemize.) The ‘

                                          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: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables Using the ‘

                                          ————————– Use the ‘

                                          Write the ‘

                                          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 ‘

                                          ’ 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 ‘

                                          command after ‘

                                          first column entries without added highlighting (‘as is’). (The ‘

                                          listed here. However, you can only use commands that normally take arguments in braces.) Begin each table entry with an ‘

                                          ’ command at the beginning of a

                                          line. Write the first column text on the same line as the ‘

                                          ’

                                          command. Write the second column text on the line following the ‘

                                          ’ 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 ‘

                                          ’ will be placed in the first

                                          column. Normally, you should put a blank line before an ‘

                                          ’ 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:

                                          ‘foo’

                                          This is the text for ‘foo’.

                                          ‘bar’

                                          Text for ‘bar’.

                                          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 ‘

                                          ’ command. (*Note ‘
                                          ’: itemx.)

                                          File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables ‘

                                          ———————– The ‘

                                          command except that ‘

                                          the first column of the table into the index of functions and ‘

                                          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 ‘

                                          ’ 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 ‘

                                          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 ‘

                                          or ‘

                                          ’command on a line by itself. File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables ‘

                                          ’

                                          ——– Use the ‘

                                          ’ 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 ‘

                                          ’ for all but the first entry. The

                                          ‘

                                          ’ command works exactly like ‘
                                          ’ except that it does not

                                          generate extra vertical space above the first column text. For example,

                                          upcase
                                          downcase

                                          These two functions accept a character or a string as argument, and return the corresponding upper case (lower case) character or string.

                                          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: texinfo.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: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: 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: texinfo.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 ‘Combining Indices::. File: texinfo.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: Each predefined index has its own indexing command–‘ concept index, ‘ Concept index entries consist of text. The best way to write an index is to choose entries that are terse yet clear. If you can do this, the index often looks better if the entries are not capitalized, but written just as they would appear in the middle of a sentence. (Capitalize proper names and acronyms that always call for upper case letters.) This is the case convention we use in most GNU manuals’ indices. If you don’t see how to make an entry terse yet clear, make it longer and clear–not terse and confusing. If many of the entries are several words long, the index may look better if you use a different convention: to capitalize the first word of each entry. But do not capitalize a case-sensitive name such as a C or Lisp function name or a shell command; that would be a spelling error. Whichever case convention you use, please use it consistently! Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them. 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: ‘ Make an entry in the concept index for CONCEPT. ‘ Make an entry in the function index for FUNCTION. ‘ Make an entry in the variable index for VARIABLE. ‘ Make an entry in the key index for KEYSTROKE. ‘ Make an entry in the program index for PROGRAM. ‘ 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 ‘ 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 ‘ a suitable title so the reader will understand. (*Note Printing Indices & Menus::.) File: texinfo.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 ‘ commands for them instead of ‘ 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.

This document was generated on January 15, 2023 using texi2html 5.0.