home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / makeindx.zip / makeindx.doc < prev    next >
Text File  |  1990-09-18  |  29KB  |  856 lines
  1.  
  2.  
  3.  
  4. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  5.  
  6.  
  7.  
  8. NAME
  9.      makeindex - a general purpose,  formatter-independent  index
  10.      processor
  11.  
  12. SYNOPSIS
  13.      makeindex [-ilqrcg] [-s sty] [-o ind] [-t  log]  [-p  no]  [
  14.      idx0 idx1 idx2 ...]
  15.  
  16. DESCRIPTION
  17.      Makeindex is a general purpose hierarchical index generator;
  18.      it accepts one or more input files (often produced by a text
  19.      formatter such as TeX  (tex(1L))  or  troff(1)),  sorts  the
  20.      entries, and produces an output file which can be formatted.
  21.      The index can have up to three levels (0, 1, and 2) of subi-
  22.      tem  nesting.  The way in which words are flagged for index-
  23.      ing within the main document is specific  to  the  formatter
  24.      used;  this program does not automate the process of select-
  25.      ing these words.  As the output index is hierarchical,  mak-
  26.      eindex can be considered complimentary to the  awk (1)-based
  27.      make.index (1L) system of Bentley and  Kernighan,  which  is
  28.      specific  to  troff (1), generates non-hierarchical indices,
  29.      and employs a  much  simpler  syntax  for  indicating  index
  30.      entries.
  31.  
  32.      The formats of the input and output files are specified in a
  33.      style  file; by default, input is assumed to be a .idx file,
  34.      as generated by LaTeX.
  35.  
  36.      Unless specified explicitly, the  base  name  of  the  first
  37.      input  file  (idx0)  is used to determine the names of other
  38.      files.  For each input file name specified, a file  of  that
  39.      name is sought.  If this file is not found and the file name
  40.      has no extension, the extension .idx  is  appended.   If  no
  41.      file with this name is found, the program aborts.
  42.  
  43.      For important notes on how to select index keywords, see the
  44.      document  by Lamport cited below.  As an issue separate from
  45.      selecting index keywords, a systematic mechanism for placing
  46.      index  terms  in a document is suggested in ``Index Prepara-
  47.      tion and Processing'', a paper cited below.
  48.  
  49. OPTIONS
  50.      -i        Take input from stdin.  When this option is speci-
  51.                fied and -o is not, output is written to stdout.
  52.  
  53.      -l        Letter ordering; by default, word ordering is used
  54.                (see the ORDERING section).
  55.  
  56.      -q        Quiet  mode;  send  no  messages  to  stderr.   By
  57.                default,  progress  and error messages are sent to
  58.                stderr as well as to the transcript file.
  59.  
  60.  
  61.  
  62.  
  63. Sun Release 4.0      Last change: 11/11/1989                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  71.  
  72.  
  73.  
  74.      -r        Disable implicit page range formation; page ranges
  75.                must  be created by using explicit range operators
  76.                (see SPECIAL EFFECTS).  By default, three or  more
  77.                successive  pages are automatically abbreviated as
  78.                a range (e.g. 1-5).
  79.  
  80.      -c        Compress intermediate blanks (ignoring leading and
  81.                trailing  blanks and tabs).  By default, blanks in
  82.                the index key are retained.
  83.  
  84.      -g        By default makeindex's word ordering is that  sym-
  85.                bols   precede  numbers  which  precede  uppercase
  86.                letters  which  precede  lowercase  letters.   The
  87.                sequence  in  German  word  ordering  is  symbols,
  88.                lowercase   letters,   uppercase   letters,   then
  89.                numbers.   By  setting  the  new  option makeindex
  90.                sorts the entries considering that  word  ordering
  91.                according  to  the German rule DIN 5007.  Moreover
  92.                the -g option enables makeinde  to  recognize  the
  93.                German  TeX-commands  {"a,  "o, "u and "s} as {ae,
  94.                oe, ue and ss} during the sorting of the  entries.
  95.                If German sort is active, the quote character must
  96.                be redefined in a style file, e.g., redefine quote
  97.                as  '+'.   If -g is set and the quote character is
  98.                not redefined makeindex will produce an error mes-
  99.                sage and abort.
  100.  
  101.      -s sty    Employ sty as the style file  (no  default).   The
  102.                environment  variable  INDEXSTYLE defines the path
  103.                where the style file should be found.
  104.  
  105.      -o ind    Employ ind as the output index file.  By  default,
  106.                the  file  name is created by appending the exten-
  107.                sion .ind to the base name of the first input file
  108.                (idx0).
  109.  
  110.      -t log    Employ log as the transcript  file.   By  default,
  111.                the  file  name is created by appending the exten-
  112.                sion .ilg to the base name of the first input file
  113.                (idx0).
  114.  
  115.      -p num    Set the starting page number of the  output  index
  116.                file  to  be num (useful when the index file is to
  117.                be formatted separately).  The argument num may be
  118.                numerical or one of the following:
  119.  
  120.                any       The starting page  is  the  last  source
  121.                          page number plus 1.
  122.  
  123.                odd       The starting page is the first odd  page
  124.                          following the last source page number.
  125.  
  126.  
  127.  
  128.  
  129. Sun Release 4.0      Last change: 11/11/1989                    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  137.  
  138.  
  139.  
  140.                even      The starting page is the first even page
  141.                          following the last source page number.
  142.  
  143.                The source log file name is determined by  append-
  144.                ing  the  extension  .log  to the base name of the
  145.                first input file (idx0).  The last source page  is
  146.                obtained by searching backward in the log file for
  147.                the first instance of  a  number  included  within
  148.                paired  square brackets ([...]).  If a page number
  149.                is missing or  the  log  file  is  not  found,  no
  150.                attempt  will  be  made  to  set the starting page
  151.                number.
  152.  
  153. STYLE FILE
  154.      This file can reside anywhere in the  path  defined  by  the
  155.      environment  variable INDEXSTYLE.  A style file is a list of
  156.      <specifier,  attribute>  pairs.   There  are  two  types  of
  157.      specifiers:  input  and output.  Pairs do not have to appear
  158.      in any particular order.  A line begun by `%' is a  comment.
  159.      In  the following list of specifiers and arguments, <string>
  160.      is an arbitrary string delimited by double  quotes  ("..."),
  161.      <char> is a single letter embraced by single quotes ('...'),
  162.      and <number> is a nonnegative integer.  The  maximum  length
  163.      of a <string> is 1024.  A literal backslash or quote must be
  164.      escaped (by a backslash).  Anything  not  specified  in  the
  165.      style  file will be assigned a default value, which is shown
  166.      in the rightmost column.
  167.  
  168.  
  169.      Input Style Specifiers
  170.  
  171.      keyword  <string>        "\\indexentry"
  172.                               Command which tells makeindex  that
  173.                               its argument is an index entry.
  174.  
  175.      arg_open  <char>         '{'
  176.                               Opening  delimiter  for  the  index
  177.                               entry argument.
  178.  
  179.      arg_close  <char>        '}'
  180.                               Closing  delimiter  for  the  index
  181.                               entry argument.
  182.  
  183.      range_open  <char>       '('
  184.                               Opening  delimiter  indicating  the
  185.                               beginning   of   an  explicit  page
  186.                               range.
  187.  
  188.      range_close  <char>      ')'
  189.                               Closing  delimiter  indicating  the
  190.                               end of an explicit page range.
  191.  
  192.  
  193.  
  194.  
  195. Sun Release 4.0      Last change: 11/11/1989                    3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  203.  
  204.  
  205.  
  206.      level  <char>            '!'
  207.                               Delimiter denoting a new  level  of
  208.                               subitem.
  209.  
  210.      actual  <char>           '@'
  211.                               Symbol  indicating  that  the  next
  212.                               entry  is  to  appear in the output
  213.                               file.
  214.  
  215.      encap  <char>            '|'
  216.                               Symbol indicating that the rest  of
  217.                               the  argument list is to be used as
  218.                               the encapsulating command  for  the
  219.                               page number.
  220.  
  221.      quote  <char>            '"'
  222.  
  223.      escape  <char>           '\\'
  224.                               Symbol which escapes the  following
  225.                               letter, unless its preceding letter
  226.                               is escape.  Note: quote is used  to
  227.                               escape the letter which immediately
  228.                               follows it, but if it  is  preceded
  229.                               by escape, it is treated as a ordi-
  230.                               nary character.  These two  symbols
  231.                               must be distinct.
  232.  
  233.  
  234.  
  235.      Output Style Specifiers
  236.  
  237.      preamble  <string>       "\\begin{theindex}\n"
  238.                               Preamble of output file.
  239.  
  240.      postamble  <string>      "\n\n\\end{theindex}\n"
  241.                               Postamble of output file.
  242.  
  243.      setpage_prefix  <string> "\n  \\setcounter{page}{"
  244.                               Prefix of command  which  sets  the
  245.                               starting page number.
  246.  
  247.      setpage_suffix  <string> "}\n"
  248.                               Suffix of command  which  sets  the
  249.                               starting page number.
  250.  
  251.      group_skip  <string>     "\n\n  \\indexspace\n"
  252.                               Vertical  space  to   be   inserted
  253.                               before a new group begins.
  254.  
  255.      headings_flag  <string>  0
  256.                               Flag indicating  treatment  of  new
  257.                               group  headers,  which are inserted
  258.  
  259.  
  260.  
  261. Sun Release 4.0      Last change: 11/11/1989                    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  269.  
  270.  
  271.  
  272.                               when before a new  group  (symbols,
  273.                               numbers, and the 26 letters): posi-
  274.                               tive  values  cause  an   uppercase
  275.                               letter  to be inserted between pre-
  276.                               fix and suffix, and negative values
  277.                               cause  a  lowercase  letter  to  be
  278.                               inserted (default is 0, which  pro-
  279.                               duces no header).
  280.  
  281.      heading_prefix  <string> ""
  282.                               Header prefix to be inserted before
  283.                               a new letter begins.
  284.  
  285.      symhead_positive  <string>
  286.                               "Symbols"
  287.                               Heading for symbols to be  inserted
  288.                               if headings_flag is positive.
  289.  
  290.      symhead_negative  <string>
  291.                               "symbols"
  292.                               Heading for symbols to be  inserted
  293.                               if headings_flag is negative.
  294.  
  295.      numhead_positive  <string>
  296.                               "Numbers"
  297.                               Heading for numbers to be  inserted
  298.                               if headings_flag is positive.
  299.  
  300.      numhead_negative  <string>
  301.                               "numbers"
  302.                               Heading for numbers to be  inserted
  303.                               if headings_flag is negative.
  304.  
  305.      item_0  <string>         "\n  \\item "
  306.                               Command to be inserted between  two
  307.                               primary (level 0) items.
  308.  
  309.      item_1  <string>         "\n     \\subitem "
  310.                               Command to be inserted between  two
  311.                               secondary (level 1) items.
  312.  
  313.      item_2  <string>         "\n       \\subsubitem "
  314.                               Command to be inserted between  two
  315.                               level 2 items.
  316.  
  317.      item_01  <string>        "\n    \\subitem "
  318.                               Command to be  inserted  between  a
  319.                               level 0 item and a level 1 item.
  320.  
  321.      item_x1  <string>        "\n    \\subitem "
  322.                               Command to be  inserted  between  a
  323.                               level  0  item  and a level 1 item,
  324.  
  325.  
  326.  
  327. Sun Release 4.0      Last change: 11/11/1989                    5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  335.  
  336.  
  337.  
  338.                               where the level  0  item  does  not
  339.                               have associated page numbers.
  340.  
  341.      item_12  <string>        "\n    \\subsubitem "
  342.                               Command to be  inserted  between  a
  343.                               level 1 item and a level 2 item.
  344.  
  345.      item_x2  <string>        "\n    \\subsubitem "
  346.                               Command to be  inserted  between  a
  347.                               level  1  item  and a level 2 item,
  348.                               where the level  1  item  does  not
  349.                               have associated page numbers.
  350.  
  351.      delim_0  <string>        ", "
  352.                               Delimiter to be inserted between  a
  353.                               level  0  key  and  its  first page
  354.                               number (default: comma followed  by
  355.                               a blank).
  356.  
  357.      delim_1  <string>        ", "
  358.                               Delimiter to be inserted between  a
  359.                               level  1  key  and  its  first page
  360.                               number (default: comma followed  by
  361.                               a blank).
  362.  
  363.      delim_2  <string>        ", "
  364.                               Delimiter to be inserted between  a
  365.                               level  2  key  and  its  first page
  366.                               number (default: comma followed  by
  367.                               a blank).
  368.  
  369.      delim_n  <string>        ", "
  370.                               Delimiter to  be  inserted  between
  371.                               two  page  numbers for the same key
  372.                               in any level (default:  comma  fol-
  373.                               lowed by a blank).
  374.  
  375.      delim_r  <string>        "--"
  376.                               Delimiter to  be  inserted  between
  377.                               the   starting   and   ending  page
  378.                               numbers of a range.
  379.  
  380.      delim_t  <string>        ""
  381.                               Delimiter to be inserted at the end
  382.                               of a page list.  This delimeter has
  383.                               no effect on entries which have  no
  384.                               associated page list.
  385.  
  386.      encap_prefix  <string>   "\\"
  387.                               First part of prefix for  the  com-
  388.                               mand  which  encapsulates  the page
  389.                               number.
  390.  
  391.  
  392.  
  393. Sun Release 4.0      Last change: 11/11/1989                    6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  401.  
  402.  
  403.  
  404.      encap_infix  <string>    "{"
  405.                               Second part of prefix for the  com-
  406.                               mand  which  encapsulates  the page
  407.                               number.
  408.  
  409.      encap_suffix  <string>   "}".
  410.                               Suffix for the command which encap-
  411.                               sulates the page number.
  412.  
  413.      line_max  <number>       72
  414.                               Maximum length of  a  line  in  the
  415.                               output, beyond which a line wraps.
  416.  
  417.      indent_space  <string>   "\t\t"
  418.                               Space to be inserted in front of  a
  419.                               wrapped line (default: two tabs).
  420.  
  421.      indent_length  <number>  16
  422.                               Length  of  indent_space  (default:
  423.                               16, equivalent to 2 tabs).
  424.  
  425. TeX EXAMPLE
  426.      The following example shows a style  file  called  book.ist,
  427.      which  defines  an  index  for a book which can be formatted
  428.      independently of the main source:
  429.  
  430.           preamble
  431.           "\\documentstyle[12pt]{book}
  432.           \\begin{document}
  433.           \\begin{theindex}
  434.           {\\small\n"
  435.           postamble
  436.           "\n\n}
  437.           \\end{theindex}
  438.           \\end{document}\n"
  439.  
  440.      Assuming that a particular book style requires the index (as
  441.      well  as any chapters) to start from an odd page number, and
  442.      that the input file is named foo.idx, the following  command
  443.      line produces output in file foo-.ind:
  444.  
  445.           makeindex  -s book.ist  -o foo-.ind  -p odd  foo
  446.  
  447.      Here a  non-default  output  file  name  is  used  to  avoid
  448.      clobbering  the  output  for  the  book  itself  (presumably
  449.      foo.dvi, which would have been  the  default  name  for  the
  450.      index output file!).
  451.  
  452. TROFF EXAMPLE
  453.      A sample control file for creating an index, which  we  will
  454.      assume resides in the file sample.ist:
  455.  
  456.  
  457.  
  458.  
  459. Sun Release 4.0      Last change: 11/11/1989                    7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  467.  
  468.  
  469.  
  470.           keyword "IX:"
  471.           preamble
  472.           ".\\\" start of index output
  473.           .SH
  474.           .ce
  475.           \\s+2INDEX\\s-2
  476.           .2C
  477.           .de IS
  478.           .sp 0.5
  479.           \\s+2\\fB
  480.           .ce
  481.           ..
  482.           .de IE
  483.           .sp 0.5
  484.           \\s-2\\fP
  485.           ..
  486.           .de I1
  487.           .ti 0.25i
  488.           ..
  489.           .de 1I
  490.           .ti 0.25i
  491.           ..
  492.           .de I2
  493.           .ti 0.5i
  494.           ..
  495.           .de 2I
  496.           .ti 0.5i
  497.           .."
  498.           postamble "\n.\\\" end of index output"
  499.           setpage_prefix "\n.nr % 1\n"
  500.           setpage_suffix ""
  501.           group_skip "\n.sp"
  502.           headings_flag 1
  503.           heading_prefix "\n.IS\n"
  504.           heading_suffix "\n.IE"
  505.           item_0 "\n.br\n"
  506.           item_1 "\n.I1\n"
  507.           item_2 "\n.I2\n"
  508.           item_01 "\n.I1\n"
  509.           item_x1 "\n.1I\n"
  510.           item_12 "\n.I2\n"
  511.           item_x2 "\n.2I\n"
  512.           delim_0 ", "
  513.           delim_1 ", "
  514.           delim_2 ", "
  515.           delim_r "-"
  516.           delim_t "."
  517.           encap_prefix "\\fB"
  518.           encap_infix ""
  519.           encap_suffix "\\fP"
  520.           indent_space " "
  521.           indent_length 8\fP
  522.  
  523.  
  524.  
  525. Sun Release 4.0      Last change: 11/11/1989                    8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  533.  
  534.  
  535.  
  536.      The local macro package may require modification, as in this
  537.      example of an extension to the -ms macros (note that at some
  538.      sites, this macro should replace a pre-existing macro of the
  539.      same name):
  540.  
  541.           .
  542.           .de IX
  543.           .ie '\\n(.z'' .tm IX: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
  544.           .el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
  545.           ..
  546.  
  547.      (note that the string {\\n(PN} is separated from the rest of
  548.      the  line  by  a  tab.  If your local macro package does not
  549.      contain this extension, just  include  those  lines  at  the
  550.      beginning  of  your  file.   Here is a simple troff(1) input
  551.      file, which we will assume is named sample.txt:
  552.  
  553.           This is a sample file to test the \fImakeindex\fP(1L) program, and see
  554.           .IX {indexing!programs!C language}
  555.           .IX {makeindex@\fImakeindex\fP(1L)}
  556.           .bp
  557.           .rs
  558.           .IX {Knuth}
  559.           .IX {typesetting!computer-aided}
  560.           how well if functions in the \fItroff\fP(1) environment.
  561.  
  562.      Note that index entries are  indicated  by  the  .IX  macro,
  563.      which  causes  the  following  text  to be written to stdout
  564.      along with the current page number.  To create an input file
  565.      for  makeindex,  in  the  Bourne  shell  environment, do the
  566.      equivalent at your site of the command:
  567.  
  568.           psroff  -ms  -Tpsc  -t  sample.txt   >   /dev/null   2>
  569.           sample.tmp
  570.  
  571.      To filter out any genuine error messages, invoke grep(1):
  572.  
  573.           grep '^IX: ' sample.tmp > sample.idx
  574.      This leaves the input for makeindex in sample.inp; the  next
  575.      step is to invoke makeindex:
  576.  
  577.           makeindex -s sample.ist sample.idx
  578.  
  579.      which leaves troff(1)-ready output in the file sample.ind.
  580.  
  581. ORDERING
  582.      By default, makeindex assumes  word  ordering;   if  the  -l
  583.      option  is in effect, letter ordering is used.  In word ord-
  584.      ering, a blank precedes any letter in the alphabet,  whereas
  585.      in  letter  ordering,  it  does  not  count at all.  This is
  586.      illustrated by the following example:
  587.  
  588.  
  589.  
  590.  
  591. Sun Release 4.0      Last change: 11/11/1989                    9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  599.  
  600.  
  601.  
  602.           word order               letter order
  603.           sea lion                 seal
  604.           seal                sea lion
  605.  
  606.      Numbers are always sorted in numeric order.  For instance,
  607.  
  608.           9 (nine),  123
  609.           10 (ten), see Derek, Bo
  610.  
  611.      Letters are first sorted without regard to case; when  words
  612.      are  identical, the uppercase version precedes its lowercase
  613.      counterpart.
  614.  
  615.      A special symbol is defined here to  be  any  character  not
  616.      appearing in the union of digits and the English alphabetic.
  617.      Patterns starting  with  special  symbols  precede  numbers,
  618.      which  precede patterns starting with letters.  As a special
  619.      case, a string starting with a digit  but  mixed  with  non-
  620.      digits is considered to be a pattern starting with a special
  621.      character.
  622.  
  623. SPECIAL EFFECTS
  624.      Entries such as
  625.  
  626.           \indexentry{alpha}{1}
  627.           \indexentry{alpha!beta}{3}
  628.           \indexentry{alpha!beta!gamma}{10}
  629.      in the input file will be converted to
  630.  
  631.           \item alpha, 1
  632.              \subitem beta, 3
  633.                 \subsubitem gamma, 10
  634.      in the output index file.   Notice  that  the  level  symbol
  635.      (`!') is used above to delimit hierarchical levels.
  636.  
  637.      It is possible to make an item appear in a  designated  form
  638.      by using the actual (`@') operator.  For instance,
  639.  
  640.           \indexentry{alpha@{\it alpha\/}}{1}
  641.      will become
  642.  
  643.           \item {\it alpha\/}  1
  644.      after processing.  The pattern preceding `@' is used as sort
  645.      key,  whereas  the one following it is written to the output
  646.      file.  Note that two appearances of the same key,  one  with
  647.      and  one  without  the actual operator, are regarded as dis-
  648.      tinct entries.
  649.  
  650.      It is possible to encapsulate a page number  with  a  desig-
  651.      nated command using the encap (`|') operator:
  652.  
  653.  
  654.  
  655.  
  656.  
  657. Sun Release 4.0      Last change: 11/11/1989                   10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  665.  
  666.  
  667.  
  668.           \indexentry{alpha|bold}{1}
  669.      will be converted to
  670.  
  671.           \item alpha \bold{1}
  672.      where \bold{n} will expand to {\bf n}.  In this example, the
  673.      three  output  attributes associated with page encapsulation
  674.      encap_prefix, encap_infix, and encap_suffix,  correspond  to
  675.      backslash,  left brace, and right brace, respectively.  This
  676.      mechanism allows page numbers to be set in different  fonts.
  677.      For  example,  the  page  where  the definition of a keyword
  678.      appears can be in one font, the location of a primary  exam-
  679.      ple  can  be in another font, and other appearances in yet a
  680.      third font.
  681.  
  682.      The encap operator can also be used to create  cross  refer-
  683.      ences in the index:
  684.  
  685.           \indexentry{alpha|see{beta}}{1}
  686.      will become
  687.  
  688.           \item alpha \see{beta}{1}
  689.      in the output file, where
  690.  
  691.           \see{beta}{1}
  692.      will expand to
  693.  
  694.           {\it see\/} beta
  695.      Note that in a cross reference like  this  the  page  number
  696.      disappears.
  697.  
  698.      A pair of encap  concatenated  with  range_open  (`|(')  and
  699.      range_close (`|)') creates an explicit page range:
  700.  
  701.           \indexentry{alpha|(}{1}
  702.           \indexentry{alpha|)}{5}
  703.      will become
  704.  
  705.           \item alpha, 1-5
  706.      Intermediate pages indexed by the same key  will  be  merged
  707.      into  the  range implicitly.  This is especially useful when
  708.      an entire section  about  a  particular  subject  is  to  be
  709.      indexed,  in  which  case only the range opening and closing
  710.      operators need to be inserted at the beginning  and  end  of
  711.      the section.  Explicit page range formation can also include
  712.      an extra command to set the page range in a designated font:
  713.  
  714.           \indexentry{alpha|(bold}{1}
  715.           \indexentry{alpha|)}{5}
  716.      will become
  717.  
  718.           \item alpha, \bold{1--5}
  719.      Several potential problems  are  worth  mentioning.   First,
  720.  
  721.  
  722.  
  723. Sun Release 4.0      Last change: 11/11/1989                   11
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  731.  
  732.  
  733.  
  734.      entries like
  735.  
  736.           \indexentry{alpha|(}{1}
  737.           \indexentry{alpha|bold}{3}
  738.           \indexentry{alpha|)}{5}
  739.      will be interpreted as
  740.  
  741.           \item alpha, \bold{3}, 1--5
  742.      but  with  a  warning  message  in  the   transcript   about
  743.      encountering an inconsistent page encapsulator.  An explicit
  744.      range beginning in a Roman page number and ending in  Arabic
  745.      is  also  considered an error.  In this instance, (if possi-
  746.      ble) the range is broken into two subranges,  one  in  Roman
  747.      and the other in Arabic.  For instance,
  748.  
  749.           \indexentry{alpha|(}{i}
  750.           \indexentry{alpha}{iv}
  751.           \indexentry{alpha}{3}
  752.           \indexentry{alpha|)}{7}
  753.      will be turned into
  754.  
  755.           \item alpha, 1--iv, 3--7
  756.      with a warning message in the  transcript  file  complaining
  757.      about an illegal range formation.
  758.  
  759.      Finally, every special symbol mentioned in this section  may
  760.      be escaped by the quote operator (`"').  Thus
  761.  
  762.           \indexentry{alpha"@beta}{1}
  763.      will actually become
  764.  
  765.           \item alpha@beta,  1
  766.      as a result of executing makeindex.  The  quoting  power  of
  767.      quote  is eliminated if it is immediately preceded by escape
  768.      (`\').  For example,
  769.  
  770.           \indexentry{f\"ur}{1}
  771.      becomes
  772.  
  773.           \item f\"ur, 1
  774.      which represents an umlaut-accented `u' to the TeX family of
  775.      processors.
  776.  
  777. SEE ALSO
  778.      latex(1L), make.index (1L), qsort(3), tex(1L), troff(1L)
  779.      Index Preparation and Processing, Pehong Chen and Michael A.
  780.      Harrison.  Software: Practice and Experience, 18(9):897-915,
  781.      September 1988.
  782.      Automating Index Preparation, Pehong  Chen  and  Michael  A.
  783.      Harrison.   Technical  Report 87/347, Computer Science Divi-
  784.      sion, University of California, Berkeley, 1988.  This  is  a
  785.      LaTeX document supplied with the makeindex distribution.
  786.  
  787.  
  788.  
  789. Sun Release 4.0      Last change: 11/11/1989                   12
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  797.  
  798.  
  799.  
  800.      MakeIndex: An Index Processor  for  LaTeX,  Leslie  Lamport,
  801.      Feburary  1987.   This is a LaTeX document supplied with the
  802.      makeindex disstribution.
  803.      Tools for Printing Indices, Jon L. Bentley and Brian W. Ker-
  804.      nighan, Elextronic Publishing, 1(1), June 1988.  Also avail-
  805.      able as Computing Science Technical  Report  No.  128,  AT&T
  806.      Bell Laboratories, Murray Hill, NJ 07974, 1986.
  807.  
  808. AUTHOR
  809.      Pehong Chen, Chen &  Harrison  International  Systems,  Inc.
  810.      Palo Alto, California, USA (chen@renoir.berkeley.edu).
  811.      Manual page extensively revised and corrected, and  troff(1)
  812.      examples created by Rick P. C. Rodgers, UCSF School of Phar-
  813.      macy (rodgers@cca.ucsf.edu).
  814.  
  815. ACKNOWLEDGMENTS
  816.      Leslie Lamport  contributed  significantly  to  the  design.
  817.      Michael Harrison provided valuable comments and suggestions.
  818.      Nelson Beebe improved on the portable version significantly.
  819.      Andreas Brosig contributed to the German word ordering.  The
  820.      modification to the -ms macros was  derived  from  a  method
  821.      proposed by Ravi Sethi of AT&T Bell Laboratories.
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855. Sun Release 4.0      Last change: 11/11/1989                   13
  856.