texinfo/doc texinfo.txi,1.26,1.27

[karl]

Update of /cvsroot/texinfo/texinfo/doc
In directory sheep:/tmp/cvs-serv8201

Modified Files:
        texinfo.txi 
Log Message:
(Printing Indices & Menus, Indices, Predefined
Indices): remove redundancies, make different
purposes clear, etc.


Index: texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.26
retrieving revision 1.27
diff -C2 -d -r1.26 -r1.27
*** texinfo.txi 18 Feb 2004 01:44:49 -0000      1.26
--- texinfo.txi 18 Feb 2004 14:58:00 -0000      1.27
***************
*** 4075,4079 ****
  @node Printing Indices & Menus
  @section Printing Indices and Menus
- @findex printindex
  @cindex Printing an index
  @cindex Indices, printing and menus
--- 4075,4078 ----
***************
*** 4092,4128 ****
  print the index.
  
! Texinfo offers six separate types of predefined index, each with a
! two-letter abbreviation, as illustrated in the following table.
! However, you may merge indices (@pxref{Combining Indices}) or define
! your own indices (@pxref{New Indices}).
! 
! Here are the predefined indices, their abbreviations, and the
! corresponding index entry commands:
! 
! @table @samp
! @item cp
! concept index (@code{@@cindex})
! @item fn
! function index (@code{@@findex})
! @item vr
! variable index (@code{@@vindex})
! @item ky
! key index (@code{@@kindex})
! @item pg
! program index (@code{@@pindex})
! @item tp
! data type index (@code{@@tindex})
! @end table
  
! The @code{@@printindex} command takes a two-letter index abbreviation,
! reads the corresponding sorted index file and formats it appropriately
! into an index.
  
! The @code{@@printindex} command does not generate a chapter heading for
! the index.  Consequently, you should precede the @code{@@printindex}
! command with a suitable section or chapter command (usually
! @code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading
! and put the index into the table of contents.  Precede the
! @code{@@unnumbered} command with an @code{@@node} line.
  
  For example:
--- 4091,4113 ----
  print the index.
  
! Texinfo offers six separate types of predefined index, which suffice
! in most cases.  @xref{Indices}, for information on this, as well
! defining your own new indices, combining indices, and, most
! importantly advice on writing the actual index entries.  This section
! focuses on printing indices, which is done with the
! @code{@@printindex} command.
  
! @findex printindex
! @code{@@printindex} takes one argument, a two-letter index
! abbreviation.  It reads the corresponding sorted index file (for
! printed output), and formats it appropriately into an index.
  
! The @code{@@printindex} command does not generate a chapter heading
! for the index, since different manuals have different needs.
! Consequently, you should precede the @code{@@printindex} command with
! a suitable section or chapter command (usually @code{@@appendix} or
! @code{@@unnumbered}) to supply the chapter heading and put the index
! into the table of contents.  Precede the chapter heading with an
! @code{@@node} line as usual.
  
  For example:
***************
*** 4144,4152 ****
  @end smallexample
  
! @noindent
  
! We recommend placing the concept index last, since that makes it easiest
! to find.  We also recommend having a single index whenever possible,
! since then readers have only one place to look (@pxref{Combining Indices}).
  
  
--- 4129,4170 ----
  @end smallexample
  
! If you have more than one index, we recommend placing the concept index last.
  
! @itemize
! @item
! In printed output, @code{@@printindex} produces a traditional
! two-column index, with dot leaders between the index terms and page
! numbers.
! 
! @item
! In Info output, @code{@@printindex} produces a special menu containing
! the line number of the entry, relative to the start of the node.  Info
! readers can use this to go to the exact line of an entry, not just the
! containing node.  (Older Info readers will just go to the node.)
! Here's an example:
! 
! @smallexample
! * First index entry:   Top.   (line  7)
! @end smallexample
! 
! @noindent The actual number of spaces is variable, to right-justify
! the line number; it's been reduced here to make the line fit in the
! printed manual.
! 
! @item
! In plain text output, @code{@@printindex} produces the same menu, but
! the line numbers are relative to the start of the file, since that's
! more convenient for that format.
! 
! @item
! In HTML and Docbook output, @code{@@printindex} produces links
! to the index entries.
! 
! @item
! In XML output, it simply records the index to be printed.
! @end itemize
! 
! It's not possible to generate an index when writing to standard
! output; @command{makeinfo} generates a warning in this case.
  
  
***************
*** 9411,9414 ****
--- 9429,9435 ----
  canonical purpose.  Lastly, you can define your own new indices.
  
+ @xref{Printing Indices & Menus}, for information on how to print
+ indices.
+ 
  @menu
  * Index Entries::               Choose different words for index entries.
***************
*** 9420,9425 ****
  @end menu
  
  @node Index Entries
- @comment  node-name,  next,  previous,  up
  @section Making Index Entries
  @cindex Index entries, making
--- 9441,9446 ----
  @end menu
  
+ 
  @node Index Entries
  @section Making Index Entries
  @cindex Index entries, making
***************
*** 9445,9487 ****
  at the end of a book or creating an index menu in an Info address@hidden
  
  @node Predefined Indices
- @comment  node-name,  next,  previous,  up
  @section Predefined Indices
  
! Texinfo provides six predefined indices:@refill
! 
! @itemize @bullet
! @item
! A @dfn{concept index} listing concepts that are address@hidden
  
! @item
! A @dfn{function index} listing functions (such as entry points of
! libraries)address@hidden
  
! @item
! A @dfn{variables index} listing variables (such as global variables
! of libraries)address@hidden
  
! @item
! A @dfn{keystroke index} listing keyboard address@hidden
  
! @item
! A @dfn{program index} listing names of address@hidden
  
! @item
! A @dfn{data type index} listing data types (such as structures defined in
! header files)address@hidden
! @end itemize
  
- @noindent
- 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 @code{@@synindex} or
- @code{@@syncodeindex} commands.  @xref{Combining address@hidden
  
  @node Indexing Commands
- @comment  node-name,  next,  previous,  up
  @section Defining the Entries of an Index
  @cindex Defining indexing entries
--- 9466,9528 ----
  at the end of a book or creating an index menu in an Info address@hidden
  
+ 
  @node Predefined Indices
  @section Predefined Indices
  
! Texinfo provides six predefined indices.  Here are their nominal
! meanings, abbreviations, and the corresponding index entry commands:
  
! @table @samp
! @item cp
! @cindex @code{cp} (concept) index
! (@code{@@cindex}) concept index, for general concepts.
! @item fn
! @cindex @code{fn} (function) index
! (@code{@@findex}) function index, for function and function-like
! names (such as entry points of libraries).
! @item ky
! @cindex @code{ky} (keystroke) index
! (@code{@@kindex}) keystroke index, for keyboard commands.
! @item pg
! @cindex @code{pg} (program) index
! (@code{@@pindex}) program index, for names of programs.
! @item tp
! @cindex @code{tp} (data type) index
! (@code{@@tindex}) data type index, for type names (such as structures
! defined in header files).
! @item vr
! @cindex @code{vr} (variable) index
! (@code{@@vindex}) variable index, for variable names (such as global
! variables of libraries).
! @end table
  
! @noindent
! Not every manual needs all of these, and most manuals use only two or
! three at most.  The present manual, for example, 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).
  
! You are not required to use the predefined indices strictly 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 @code{@@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.
  
! On the other hand, it is best not to stray too far from the meaning of
! the predefined indices.  Otherwise, in the event that your text is
! combined with other text from other manuals, the index entries will
! not match up.  Instead, define your own new index (@pxref{New
! Indices}).
  
! We recommend having a single index in the final document whenever
! possible, however many source indices you use, since then readers have
! only one place to look.  Two or more source indices can be combined
! into one output index using the @code{@@synindex} or
! @code{@@syncodeindex} commands (@pxref{Combining Indices}).
  
  
  @node Indexing Commands
  @section Defining the Entries of an Index
  @cindex Defining indexing entries
***************
*** 9504,9508 ****
  @example
  @@cindex Defining indexing entries
! @@cindex Index entries
  @@cindex Entries for an index
  @@cindex Specifying index entries
--- 9545,9549 ----
  @example
  @@cindex Defining indexing entries
! @@cindex Index entries, defining
  @@cindex Entries for an index
  @@cindex Specifying index entries
***************
*** 9512,9516 ****
  Each predefined index has its own indexing address@hidden@@cindex}
  for the concept index, @code{@@findex} for the function index, and so
! address@hidden
  
  @cindex Writing index entries
--- 9553,9557 ----
  Each predefined index has its own indexing address@hidden@@cindex}
  for the concept index, @code{@@findex} for the function index, and so
! on, as listed in the previous section.
  
  @cindex Writing index entries
***************
*** 9537,9605 ****
  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{@@code} font.  You may change the way part of an entry is
  printed with the usual Texinfo commands, such as @code{@@file} for
! file names and @code{@@emph} for emphasis (@pxref{Marking
! Text})address@hidden
! @cindex Index font types
! 
! @cindex Predefined indexing commands
! @cindex Indexing commands, predefined
! The six indexing commands for predefined indices are:
! 
! @table @code
! @item @@cindex @var{concept}
! @findex cindex
! Make an entry in the concept index for @address@hidden
! 
! @item @@findex @var{function}
! @findex findex
! Make an entry in the function index for @address@hidden
! 
! @item @@vindex @var{variable}
! @findex vindex
! Make an entry in the variable index for @address@hidden
! 
! @item @@kindex @var{keystroke}
! @findex kindex
! Make an entry in the key index for @address@hidden
! 
! @item @@pindex @var{program}
! @findex pindex
! Make an entry in the program index for @address@hidden
! 
! @item @@tindex @var{data type}
! @findex tindex
! Make an entry in the data type index for @var{data address@hidden
! @end table
  
  @quotation Caution
  Do not use a colon in an index entry.  In Info, a colon separates the
  menu entry name from the node name, so a colon in the entry itself
! confuses Info.  @xref{Menu Parts, , The Parts of a Menu}, for more
! information about the structure of a menu entry.
  @end quotation
  
- 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 @code{@@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 @code{@@tindex} commands for them, and
- give that index a suitable title so the reader will understand.
- (@xref{Printing Indices & Menus}.)@refill
  
  @node Combining Indices
- @comment node-name,  next,  previous,  up
  @section Combining Indices
  @cindex Combining indices
  @cindex Indices, combining them
  
! 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 address@hidden
  
  You could put functions into the concept index by writing
--- 9578,9605 ----
  case-sensitive, so use upper and lower case as required for them.
  
+ @cindex Index font types
  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{@@code} font.  You may change the way part of an entry is
  printed with the usual Texinfo commands, such as @code{@@file} for
! file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
! font (@pxref{Fonts}).
  
  @quotation Caution
  Do not use a colon in an index entry.  In Info, a colon separates the
  menu entry name from the node name, so a colon in the entry itself
! confuses Info.  @xref{Menu Parts}, for more information about the
! structure of a menu entry.
  @end quotation
  
  
  @node Combining Indices
  @section Combining Indices
  @cindex Combining indices
  @cindex Indices, combining them
  
! Sometimes you will want to combine two disparate indices such as
! functions and concepts, perhaps because you have few enough entries
! that a separate index would look silly.
  
  You could put functions into the concept index by writing
***************
*** 9608,9618 ****
  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{@@address@hidden
  
  @menu
--- 9608,9618 ----
  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{@@code}.
  
  @menu
***************
*** 9706,9709 ****
--- 9706,9710 ----
  at the end of a book or creating an index menu in an Info address@hidden
  
+ 
  @node New Indices
  @section Defining New Indices
***************
*** 9717,9722 ****
  @code{@@defindex} and @code{@@defcodeindex} commands to define new
  indices.  These commands create new indexing @@-commands with which
! you mark index entries.  The @code{@@defindex }command is used like
! this:@refill
  
  @example
--- 9718,9723 ----
  @code{@@defindex} and @code{@@defcodeindex} commands to define new
  indices.  These commands create new indexing @@-commands with which
! you mark index entries.  The @code{@@defindex} command is used like
! this:
  
  @example
***************
*** 9725,9729 ****
  
  The name of an index should be a two letter word, such as @samp{au}.
! For example:@refill
  
  @example
--- 9726,9730 ----
  
  The name of an index should be a two letter word, such as @samp{au}.
! For example:
  
  @example
***************
*** 9733,9741 ****
  This defines a new index, called the @samp{au} index.  At the same
  time, it creates a new indexing command, @code{@@auindex}, that you
! can use to make index entries.  Use the new indexing command just as
! you would use a predefined indexing address@hidden
  
  For example, here is a section heading followed by a concept index
! entry and two @samp{au} index address@hidden
  
  @example
--- 9734,9742 ----
  This defines a new index, called the @samp{au} index.  At the same
  time, it creates a new indexing command, @code{@@auindex}, that you
! can use to make index entries.  Use this 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 @samp{au} index entries.
  
  @example
***************
*** 9748,9761 ****
  @noindent
  (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
! Texinfo constructs the new indexing command by concatenating the name
! of the index with @samp{index}; thus, defining an @samp{au} index
! leads to the automatic creation of an @code{@@auindex} address@hidden
  
  Use the @code{@@printindex} command to print the index, as you do with
! the predefined indices.  For example:@refill
  
  @example
  @group
! @@node Author Index, Subject Index, , Top
  @@unnumbered Author Index
  
--- 9749,9764 ----
  @noindent
  (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
! 
! In general, Texinfo constructs the new indexing command by
! concatenating the name of the index with @samp{index}; thus, defining
! an @samp{xy} index leads to the automatic creation of an
! @code{@@xyindex} command.
  
  Use the @code{@@printindex} command to print the index, as you do with
! the predefined indices.  For example:
  
  @example
  @group
! @@node Author Index
  @@unnumbered Author Index
  
***************
*** 9764,9774 ****
  @end example
  
! The @code{@@defcodeindex} is like the @code{@@defindex} command, except
! that, in the printed output, it prints entries in an @code{@@code} font
! instead of a roman font.  Thus, it parallels the @code{@@findex} command
! rather than the @code{@@cindex} address@hidden
  
! You should define new indices within or right after the end-of-header
! line of a Texinfo file, before any @code{@@synindex} or
  @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
  
--- 9767,9776 ----
  @end example
  
! The @code{@@defcodeindex} is like the @code{@@defindex} command,
! except that, in the printed output, it prints entries in an
! @code{@@code} font by default instead of a roman font.  
  
! You should define new indices before the end-of-header line of a
! Texinfo file, and (of course) before any @code{@@synindex} or
  @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).