


MAKEINDEX(1L)                                       MAKEINDEX(1L)


NNAAMMEE
       makeindex - a general purpose, formatter-independent index
       processor

SSYYNNOOPPSSIISS
       mmaakkeeiinnddeexx [[-c]] [[-g]] [[-i]] [[-l]] [[-o _i_n_d] [[-p _n_u_m] [[-q]]  [[-r]]
       [[-s _s_f_i_l_e] [[-t _l_o_g] [[-L]] [[-T]] [[_i_d_x_0 _i_d_x_1 _i_d_x_2...]

DDEESSCCRRIIPPTTIIOONN
       The  program  _m_a_k_e_i_n_d_e_x  is a general purpose hierarchical
       index generator; it accepts one or more input files (often
       produced  by  a  text  formatter  such as TeX (_t_e_x(1L)) or
       _t_r_o_f_f(1), sorts the entries, and produces an  output  file
       which  can  be  formatted.  The index can have up to three
       levels (0, 1, and 2) of subitem nesting.  The way in which
       words are flagged for indexing within the main document is
       specific to the formatter used; _m_a_k_e_i_n_d_e_x does  _n_o_t  auto-
       mate  the process of selecting these words.  As the output
       index is hierarchical, _m_a_k_e_i_n_d_e_x can be considered compli-
       mentary to the _a_w_k(1)-based _m_a_k_e_._i_n_d_e_x(1L) system of Bent-
       ley and Kernighan, which is specific to  _t_r_o_f_f(1),  gener-
       ates  non-hierarchical indices, and employs a much simpler
       syntax for indicating index entries.  For illustration  of
       use with _t_r_o_f_f and _T_e_X, see the section EXAMPLES below.

       The formats of the input and output files are specified in
       a style file; by default, input is assumed to  be  a  _._i_d_x
       file, as generated by LaTeX.

       Unless  specified  explicitly,  the base name of the first
       input file (_i_d_x_0) is used to determine the names of  other
       files.  For each input file name specified, a file of that
       name is sought.  If this file is not found  and  the  file
       name has no extension, the extension _._i_d_x is appended.  If
       no file with this name is found, _m_a_k_e_i_n_d_e_x aborts.

       If exactly one input file was given and no explicit  style
       file  was  specified  using --ss, _m_a_k_e_i_n_d_e_x uses a file with
       the extension _._m_s_t as default style file (when present).

       For important notes on how to select index  keywords,  see
       the document by Lamport cited below.  As an issue separate
       from selecting index keywords, a systematic mechanism  for
       placing  index  terms  in a document is suggested in _I_n_d_e_x
       _P_r_e_p_a_r_a_t_i_o_n _a_n_d _P_r_o_c_e_s_s_i_n_g, a paper cited below.

OOPPTTIIOONNSS
       --cc        Compress intermediate blanks  (ignoring  leading
                 and  trailing  blanks  and  tabs).   By default,
                 blanks in the index key are retained.

       --gg        Employ German word ordering  in  the  index,  in
                 accord  with  rules  set  forth in DIN 5007.  By
                 default, _m_a_k_e_i_n_d_e_x employs a  word  ordering  in



                         10 December 1991                       1





MAKEINDEX(1L)                                       MAKEINDEX(1L)


                 which precedence is: symbols, numbers, uppercase
                 letters, lowercase  letters.   The  sequence  in
                 German word ordering is: symbols, lowercase let-
                 ters, uppercase letters, numbers.  Additionally,
                 this  option  enables _m_a_k_e_i_n_d_e_x to recognize the
                 German TeX-commands {"a, "o, "u and "s} as  {ae,
                 oe,  ue  and  ss}  during  the  sorting  of  the
                 entries.  The quote character must be  redefined
                 in  a style file (for example, redefine quote as
                 '+').  If the quote character is not  redefined,
                 _m_a_k_e_i_n_d_e_x  will  produce  an  error  message and
                 abort.

       --ii        Take input from  _s_t_d_i_n.   When  this  option  is
                 specified  and  --oo  is not, output is written to
                 _s_t_d_o_u_t.

       --ll        Letter ordering; by default,  word  ordering  is
                 used (see the ORDERING section).

       --oo _i_n_d    Employ   _i_n_d  as  the  output  index  file.   By
                 default, the file name is created  by  appending
                 the extension _._i_n_d to the base name of the first
                 input file (_i_d_x_0).

       --pp _n_u_m    Set the starting page number of the output index
                 file to be _n_u_m (useful when the index file is to
                 be formatted separately).  The argument _n_u_m  may
                 be numerical or one of the following:

                 _a_n_y       The  starting  page is the last source
                           page number plus 1.

                 _o_d_d       The starting page  is  the  first  odd
                           page  following  the  last source page
                           number.

                 _e_v_e_n      The starting page is  the  first  even
                           page  following  the  last source page
                           number.

                 The last source page is  obtained  by  searching
                 backward  in the log file for the first instance
                 of a number included within paired square brack-
                 ets ([[...]]).  If a page number is missing or the
                 log file is not found, no attempt will  be  made
                 to set the starting page number.  The source log
                 file name is determined by appending the  exten-
                 sion  _._l_o_g  to  the base name of the first input
                 file (_i_d_x_0).

       --qq        Quiet mode; send  no  messages  to  _s_t_d_e_r_r.   By
                 default, progress and error messages are sent to
                 _s_t_d_e_r_r as well as to the transcript file.



                         10 December 1991                       2





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       --rr        Disable  implicit  page  range  formation;  page
                 ranges  must  be created by using explicit range
                 operators;  see  SPECIAL  EFFECTS   below.    By
                 default,  three  or  more  successive  pages are
                 automatically  abbreviated  as  a  range   (e.g.
                 1--5).

       --ss sty    Employ  _s_t_y as the style file (no default).  The
                 environment variable INDEXSTYLE defines the path
                 where the style file should be found.

       --tt log    Employ  _l_o_g as the transcript file.  By default,
                 the file name is created by appending the exten-
                 sion  _._i_l_g  to  the base name of the first input
                 file (_i_d_x_0).

       --LL        sort based on locale settings. Not available  on
                 all systems.

       --TT        special  support  for Thai documents. Not avail-
                 able on all systems.

SSTTYYLLEE FFIILLEE
       The style file informs _m_a_k_e_i_n_d_e_x about the format  of  the
       _._i_d_x input files and the intended format of the final out-
       put file; examples appear below.   This  file  can  reside
       anywhere  in  the path defined by the environment variable
       INDEXSTYLE.  The style file contains a list of <_s_p_e_c_i_f_i_e_r,
       _a_t_t_r_i_b_u_t_e>  pairs.   There  are  two  types of specifiers:
       input and output.  Pairs do not have to appear in any par-
       ticular  order.  A line begun by `%' is a comment.  In the
       following list of specifiers and arguments, <string> is an
       arbitrary  string  delimited  by  double  quotes  ("..."),
       <char> is  a  single  letter  embraced  by  single  quotes
       ('...'), and <number> is a nonnegative integer.  The maxi-
       mum length of a <string> is 2048.  A literal backslash  or
       quote  must  be  escaped  (by  a backslash).  Anything not
       specified in the style file will  be  assigned  a  default
       value, which is shown at the head of the rightmost column.

   IINNPPUUTT SSTTYYLLEE SSPPEECCIIFFIIEERRSS
       aaccttuuaall <char>            '@'
                                Symbol indicating that  the  next
                                entry  is to appear in the output
                                file.

       aarrgg__cclloossee <char>         '}'
                                Closing delimiter for  the  index
                                entry argument.

       aarrgg__ooppeenn <char>          '{'
                                Opening  delimiter  for the index
                                entry argument.




                         10 December 1991                       3





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       eennccaapp <char>             '|'
                                Symbol indicating that  the  rest
                                of  the  argument  list  is to be
                                used as the encapsulating command
                                for the page number.

       eessccaappee <char>            '\\'
                                Symbol  which escapes the follow-
                                ing letter, unless its  preceding
                                letter is eessccaappee.  Note: qquuoottee is
                                used to escape the  letter  which
                                immediately follows it, but if it
                                is  preceded  by  eessccaappee,  it  is
                                treated  as a ordinary character.
                                These two symbols  _m_u_s_t  be  dis-
                                tinct.

       kkeeyywwoorrdd <string>         "\\indexentry"
                                Command   which  tells  _m_a_k_e_i_n_d_e_x
                                that its  argument  is  an  index
                                entry.

       lleevveell <char>             '!'
                                Delimiter denoting a new level of
                                subitem.

       qquuoottee <char>             '"'
                                Note: qquuoottee is used to escape the
                                letter  which immediately follows
                                it, but  if  it  is  preceded  by
                                eessccaappee,  it is treated as a ordi-
                                nary character.  These  two  sym-
                                bols _m_u_s_t be distinct.

       rraannggee__cclloossee <char>       ')'
                                Closing  delimiter indicating the
                                end of an explicit page range.

       rraannggee__ooppeenn <char>        '('
                                Opening delimiter indicating  the
                                beginning  of  an  explicit  page
                                range.

   OOUUTTPPUUTT SSTTYYLLEE SSPPEECCIIFFIIEERRSS
       pprreeaammbbllee <string>        "\\begin{theindex}\n"
                                Preamble of output file.

       ppoossttaammbbllee <string>       "\n\n\\end{theindex}\n"
                                Postamble of output file.

       sseettppaaggee__pprreeffiixx <string>  "\n  \\setcounter{page}{"
                                Prefix of command which sets  the
                                starting page number.




                         10 December 1991                       4





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       sseettppaaggee__ssuuffffiixx <string>  "}\n"
                                Suffix  of command which sets the
                                starting page number.

       ggrroouupp__sskkiipp <string>      "\n\n  \\indexspace\n"
                                Vertical  space  to  be  inserted
                                before a new group begins.

       hheeaaddiinnggss__ffllaagg <string>   0
                                Flag  indicating treatment of new
                                group headers, which are inserted
                                when before a new group (symbols,
                                numbers,  and  the  26  letters):
                                positive  values  cause an upper-
                                case  letter   to   be   inserted
                                between  prefix  and  suffix, and
                                negative values cause a lowercase
                                letter to be inserted (default is
                                0, which produces no header).

       hheeaaddiinngg__pprreeffiixx <string>  ""
                                Header  prefix  to  be   inserted
                                before a new letter begins.

       ssyymmhheeaadd__ppoossiittiivvee <string>
                                "Symbols"
                                Heading   for   symbols   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is pos-
                                itive.

       ssyymmhheeaadd__nneeggaattiivvee <string>
                                "symbols"
                                Heading   for   symbols   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is neg-
                                ative.

       nnuummhheeaadd__ppoossiittiivvee <string>
                                "Numbers"
                                Heading   for   numbers   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is pos-
                                itive.

       nnuummhheeaadd__nneeggaattiivvee <string>
                                "numbers"
                                Heading   for   numbers   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is neg-
                                ative.

       iitteemm__00 <string>          "\n  \\item "
                                Command  to  be  inserted between
                                two primary (level 0) items.

       iitteemm__11 <string>          "\n     \\subitem "
                                Command to  be  inserted  between



                         10 December 1991                       5





MAKEINDEX(1L)                                       MAKEINDEX(1L)


                                two secondary (level 1) items.

       iitteemm__22 <string>          "\n       \\subsubitem "
                                Command  to  be  inserted between
                                two level 2 items.

       iitteemm__0011  <<ssttrriinngg>>        "\n    \\subitem "
                                Command to be inserted between  a
                                level  0 item and a level 1 item.

       iitteemm__xx11 <string>         "\n    \\subitem "
                                Command to be inserted between  a
                                level  0 item and a level 1 item,
                                where the level 0 item  does  not
                                have associated page numbers.

       iitteemm__1122 <string>         "\n    \\subsubitem "
                                Command  to be inserted between a
                                level 1 item and a level 2  item.

       iitteemm__xx22 <string>         "\n    \\subsubitem "
                                Command  to be inserted between a
                                level 1 item and a level 2  item,
                                where  the  level 1 item does not
                                have associated page numbers.

       ddeelliimm__00 <string>         ", "
                                Delimiter to be inserted  between
                                a  level 0 key and its first page
                                number (default:  comma  followed
                                by a blank).

       ddeelliimm__11 <string>         ", "
                                Delimiter  to be inserted between
                                a level 1 key and its first  page
                                number  (default:  comma followed
                                by a blank).

       ddeelliimm__22 <string>         ", "
                                Delimiter to be inserted  between
                                a  level 2 key and its first page
                                number (default:  comma  followed
                                by a blank).

       ddeelliimm__nn <string>         ", "
                                Delimiter  to be inserted between
                                two page numbers for the same key
                                in any level (default: comma fol-
                                lowed by a blank).

       ddeelliimm__rr <string>         "--"
                                Delimiter to be inserted  between
                                the starting and ending page num-
                                bers of a range.



                         10 December 1991                       6





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       ddeelliimm__tt <string>         ""
                                Delimiter to be inserted  at  the
                                end  of a page list.  This delim-
                                iter has  no  effect  on  entries
                                which  have  no  associated  page
                                list.

       eennccaapp__pprreeffiixx <string>    "\\"
                                First part of prefix for the com-
                                mand  which encapsulates the page
                                number.

       eennccaapp__iinnffiixx <string>     "{"
                                Second part  of  prefix  for  the
                                command  which  encapsulates  the
                                page number.

       eennccaapp__ssuuffffiixx <string>    "}".
                                Suffix  for  the  command   which
                                encapsulates the page number.

       lliinnee__mmaaxx <number>        72
                                Maximum  length  of a line in the
                                output,  beyond  which   a   line
                                wraps.

       iinnddeenntt__ssppaaccee <string>    "\t\t"
                                Space  to be inserted in front of
                                a  wrapped  line  (default:   two
                                tabs).

       iinnddeenntt__lleennggtthh <number>   16
                                Length  of iinnddeenntt__ssppaaccee (default:
                                16, equivalent to 2 tabs).

       ssuuffffiixx__22pp <string>       ""
                                Delimiter to  replace  the  range
                                delimiter  and  the  second  page
                                number of a two page  list.  When
                                present,  it  overrides  ddeelliimm__rr.
                                Example: "f.".

       ssuuffffiixx__33pp <string>       ""
                                Delimiter to  replace  the  range
                                delimiter  and  the  second  page
                                number of a three page list. When
                                present, it overrides ddeelliimm__rr and
                                ssuuffffiixx__mmpp.  Example: "ff.".

       ssuuffffiixx__mmpp <string>       ""
                                Delimiter to  replace  the  range
                                delimiter  and  the  second  page
                                number of a  multiple  page  list
                                (three   or   more  pages).  When



                         10 December 1991                       7





MAKEINDEX(1L)                                       MAKEINDEX(1L)


                                present,  it  overrides  ddeelliimm__rr.
                                Example: "f.".

EEXXAAMMPPLLEESS
   TTeeXX EEXXAAMMPPLLEE
       The  following example shows a style file called _b_o_o_k_._i_s_t,
       which defines an index for a book which can  be  formatted
       independently of the main source:

              pprreeaammbbllee
              ""\\\\ddooccuummeennttssttyyllee[[1122pptt]]{{bbooookk}}
              \\\\bbeeggiinn{{ddooccuummeenntt}}
              \\\\bbeeggiinn{{tthheeiinnddeexx}}
              {{\\\\ssmmaallll\\nn""
              ppoossttaammbbllee
              ""\\nn\\nn}}
              \\\\eenndd{{tthheeiinnddeexx}}
              \\\\eenndd{{ddooccuummeenntt}}\\nn"

       Assuming  that  a particular book style requires the index
       (as well as any chapters) to start from an odd  page  num-
       ber, and that the input file is named _f_o_o_._i_d_x, the follow-
       ing command line produces output in file _f_o_o_t_m_p_._i_n_d:

              mmaakkeeiinnddeexx  --ss bbooookk..iisstt  --oo ffoooottmmpp..iinndd  --pp oodddd  ffoooo

       Here a non-default output file name is used to avoid clob-
       bering the output for the book itself (presumably _f_o_o_._d_v_i,
       which would have been the default name for the index  out-
       put file!).

   TTRROOFFFF EEXXAAMMPPLLEE
       A sample control file for creating an index, which we will
       assume resides in the file _s_a_m_p_l_e_._i_s_t:

              kkeeyywwoorrdd ""IIXX::""
              pprreeaammbbllee
              ""..\\\\\\"" ssttaarrtt ooff iinnddeexx oouuttppuutt
              \\""..\\\\\\"" eenntteerr ttwwoo ccoolluummnn mmooddee
              ..22CC
              ..SSHH
              ..ccee
              IINNDDEEXX
              ..XXSS
              IINNDDEEXX
              ..XXEE
              ..RR
              ..ppss 99pp
              ..vvss 1111pp
              ..sspp
              ..ddee II11
              ..ttii 00..2255ii
              ....
              ..ddee II22



                         10 December 1991                       8





MAKEINDEX(1L)                                       MAKEINDEX(1L)


              ..ttii 00..55ii
              ....""
              ppoossttaammbbllee ""\\nn..\\\\\\"" eenndd ooff iinnddeexx oouuttppuutt""
              sseettppaaggee__pprreeffiixx ""\\nn..nnrr %% ""
              sseettppaaggee__ssuuffffiixx """"
              ggrroouupp__sskkiipp ""\\nn..sspp 11..00""
              hheeaaddiinnggss__ffllaagg 11
              hheeaaddiinngg__pprreeffiixx ""\\nn..IISS\\nn""
              hheeaaddiinngg__ssuuffffiixx ""\\nn..IIEE""
              iitteemm__00 ""\\nn..bbrr\\nn""
              iitteemm__11 ""\\nn..II11\\nn""
              iitteemm__22 ""\\nn..II22\\nn""
              iitteemm__0011 ""\\nn..II11\\nn""
              iitteemm__xx11 ""\\nn..II11\\nn""
              iitteemm__1122 ""\\nn..II22\\nn""
              iitteemm__xx22 ""\\nn..II22\\nn""
              ddeelliimm__00 "",, ""
              ddeelliimm__11 "",, ""
              ddeelliimm__22 "",, ""
              ddeelliimm__rr ""--""
              ddeelliimm__tt ""..""
              eennccaapp__pprreeffiixx ""\\\\ffBB""
              eennccaapp__iinnffiixx """"
              eennccaapp__ssuuffffiixx ""\\\\ffPP""
              iinnddeenntt__ssppaaccee """"
              iinnddeenntt__lleennggtthh 00

       The local macro package may require  modification,  as  in
       this  example of an extension to the --mmss macros (note that
       at some sites, this macro should  _r_e_p_l_a_c_e  a  pre-existing
       macro of the same name):

              ..
              ..ddee IIXX
              ..iiee ''\\\\nn((..zz'''' ..ttmm IIXX:: \\\\$$11 \\\\$$22 \\\\$$33 \\\\$$44 \\\\$$55 \\\\$$66 \\\\$$77 \\\\$$88 \\\\$$99 {{\\\\nn((PPNN}}
              ..eell \\\\!!..IIXX \\\\$$11 \\\\$$22 \\\\$$33 \\\\$$44 \\\\$$55 \\\\$$66 \\\\$$77 \\\\$$88 \\\\$$99 {{\\\\nn((PPNN}}
              ....

       (note  that the string {\\\\nn((PPNN} is separated from the rest
       of the line by a tab.  If your local  macro  package  does
       not  contain  this  extension, just include those lines at
       the beginning of your file.  Here  is  a  simple  _t_r_o_f_f(1)
       input file, which we will assume is named _s_a_m_p_l_e_._t_x_t:

              TThhiiss iiss aa ssaammppllee ffiillee ttoo tteesstt tthhee \\ffIImmaakkeeiinnddeexx\\ffPP((11LL))
              pprrooggrraamm,, aanndd sseeee
              ..IIXX {{iinnddeexxiinngg!!pprrooggrraammss!!CC llaanngguuaaggee}}
              ..IIXX {{mmaakkeeiinnddeexx@@\\ffIImmaakkeeiinnddeexx\\ffPP((11LL))}}
              ..bbpp
              ..rrss
              ..IIXX {{KKnnuutthh}}
              ..IIXX {{ttyyppeesseettttiinngg!!ccoommppuutteerr--aaiiddeedd}}
              hhooww wweellll iitt ffuunnccttiioonnss iinn tthhee \\ffIIttrrooffff\\ffPP((11)) eennvviirroonnmmeenntt..




                         10 December 1991                       9





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       Note  that  index  entries are indicated by the ..IIXX macro,
       which causes the following text to be  written  to  _s_t_d_o_u_t
       along with the current page number.

   CCRREEAATTIINNGG TTHHEE IINNDDEEXX FFIILLEE IINN TTHHEE BBOOUURRNNEE SSHHEELLLL
       To create an input file for _m_a_k_e_i_n_d_e_x, iinn tthhee BBoouurrnnee sshheellll
       environment, do the equivalent at your site  of  the  com-
       mand:

       ppssrrooffff --mmss --TTppsscc --tt ssaammppllee..ttxxtt >> //ddeevv//nnuullll 22>> ssaammppllee..ttmmpp

       Some  sites  will  require  _d_i_t_r_o_f_f instead of _p_s_r_o_f_f.  To
       filter out any genuine error messages, invoke _g_r_e_p(1):

              ggrreepp ''^^IIXX:: '' ssaammppllee..ttmmpp >> ssaammppllee..iiddxx

   CCRREEAATTIINNGG TTHHEE IINNDDEEXX FFIILLEE UUSSIINNGG UUCCSSFF EENNHHAANNCCEEDD TTRROOFFFF//TTRRAANNSSCCRRIIPPTT
       With UCSF Enhanced  troff/TRANSCRIPT,  the  --II  option  of
       _p_s_r_o_f_f(1L)  can produce both formatter output and an index
       file:

              ppssrrooffff --mmss --II ssaammppllee..iinnpp --TTppsscc ssaammppllee..ttxxtt

       If it is wished to suppress the formatter output:

              ppssrrooffff --mmss --II ssaammppllee..iinnpp --TTppsscc --tt ssaammppllee..ttxxtt >> //ddeevv//nnuullll

   CCOOMMPPLLEETTIINNGG TTHHEE IINNDDEEXX
       Any of the above procedures leaves the input for _m_a_k_e_i_n_d_e_x
       in _s_a_m_p_l_e_._i_n_p.  The next step is to invoke _m_a_k_e_i_n_d_e_x:

              mmaakkeeiinnddeexx --ss ssaammppllee..iisstt ssaammppllee..iiddxx

       This  leaves _t_r_o_f_f(1)-ready output in the file _s_a_m_p_l_e_._i_n_d.

OORRDDEERRIINNGG
       By default, _m_a_k_e_i_n_d_e_x assumes _w_o_r_d  _o_r_d_e_r_i_n_g;  if  the  --ll
       option  is  in  effect,  _l_e_t_t_e_r _o_r_d_e_r_i_n_g is used.  In word
       ordering, a blank precedes any  letter  in  the  alphabet,
       whereas  in  letter  ordering,  it  does not count at all.
       This is illustrated by the following example:

              _w_o_r_d _o_r_d_e_r                      _l_e_t_t_e_r _o_r_d_e_r
              sea lion                        seal
              seal                            sea lion

       Numbers are always sorted in numeric order.  For instance,

              9 (nine),  123
              10 (ten), see Derek, Bo

       Letters  are  first  sorted  without  regard to case; when
       words are identical, the uppercase  version  precedes  its
       lowercase counterpart.



                         10 December 1991                      10





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       A  special  symbol is defined here to be any character not
       appearing in the union of digits and  the  English  alpha-
       betic  characters.  Patterns starting with special symbols
       precede numbers, which precede patterns starting with let-
       ters.   As  a special case, a string starting with a digit
       but mixed with non-digits is considered to  be  a  pattern
       starting with a special character.

SSPPEECCIIAALL EEFFFFEECCTTSS
       Entries such as

              \\iinnddeexxeennttrryy{{aallpphhaa}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa!!bbeettaa}}{{33}}
              \\iinnddeexxeennttrryy{{aallpphhaa!!bbeettaa!!ggaammmmaa}}{{1100}}

       in the input file will be converted to

              \\iitteemm aallpphhaa,, 11
                 \\ssuubbiitteemm bbeettaa,, 33
                    \\ssuubbssuubbiitteemm ggaammmmaa,, 1100

       in  the  output  index file.  Notice that the lleevveell symbol
       (`!') is used above to delimit hierarchical levels.

       It is possible to make an item appear in a designated form
       by using the aaccttuuaall (`@') operator.  For instance,

              \\iinnddeexxeennttrryy{{aallpphhaa@@{{\\iitt aallpphhaa\\//}}}}{{11}}

       will become

              \\iitteemm {{\\iitt aallpphhaa\\//}},,  11

       after  processing.   The  pattern preceding `@' is used as
       sort key, whereas the one following it is written  to  the
       output  file.   Note that two appearances of the same key,
       one with and one without the aaccttuuaall operator, are regarded
       as _d_i_s_t_i_n_c_t entries.

       The item, subitem, and subsubitem fields may have individ-
       ual sort keys:

              \\iinnddeexxeennttrryy{{aaaa@@{{\\iitt aaaa\\//}}!!bbbb@@{{\\iitt bbbb\\//}}!!cccc@@{{\\iitt cccc\\//}}}}{{11}}

       This will be converted to

              \\iitteemm {{\\iitt aaaa}},, 11
                 \\ssuubbiitteemm {{\\iitt bbbb}},, 33
                    \\ssuubbssuubbiitteemm {{\\iitt cccc}},, 1100

       It is possible to encapsulate a page number with a  desig-
       nated command using the eennccaapp (`|') operator:

              \\iinnddeexxeennttrryy{{aallpphhaa||bboolldd}}{{11}}



                         10 December 1991                      11





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       will be converted to

              \\iitteemm aallpphhaa,, \\bboolldd{{11}}

       where,  with  a suitable definition for TeX, \\bboolldd{{nn}} will
       expand to {{\\bbff nn}}.  In  this  example,  the  three  output
       attributes     associated    with    page    encapsulation
       eennccaapp__pprreeffiixx, eennccaapp__iinnffiixx, and eennccaapp__ssuuffffiixx, correspond to
       backslash,  left  brace,  and  right  brace, respectively.
       This mechanism allows page numbers to be set in  different
       fonts.   For  example,  the page where the definition of a
       keyword appears can be in one font, the location of a pri-
       mary example can be in another font, and other appearances
       in yet a third font.

       The eennccaapp operator can also be used to create cross refer-
       ences in the index:

              \\iinnddeexxeennttrryy{{aallpphhaa||sseeee{{bbeettaa}}}}{{11}}

       will become

              \\iitteemm aallpphhaa,, \\sseeee{{bbeettaa}}{{11}}

       in the output file, where

              \\sseeee{{bbeettaa}}{{11}}

       will expand to

              {{\\iitt sseeee\\//}} bbeettaa

       Note  that  in a cross reference like this the page number
       disappears.

       A pair of eennccaapp concatenated with  rraannggee__ooppeenn  (`|(')  and
       rraannggee__cclloossee (`|)') creates an explicit page range:

              \\iinnddeexxeennttrryy{{aallpphhaa||((}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{55}}

       will become

              \\iitteemm aallpphhaa,, 11----55

       Intermediate  pages indexed by the same key will be merged
       into the range implicitly.  This is especially useful when
       an  entire  section  about  a  particular subject is to be
       indexed, in which case only the range opening and  closing
       operators  need to be inserted at the beginning and end of
       the section.   Explicit  page  range  formation  can  also
       include an extra command to set the page range in a desig-
       nated font:




                         10 December 1991                      12





MAKEINDEX(1L)                                       MAKEINDEX(1L)


              \\iinnddeexxeennttrryy{{aallpphhaa||((bboolldd}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{55}}

       will become

              \\iitteemm aallpphhaa,, \\bboolldd{{11----55}}

       Several potential problems are worth  mentioning.   First,
       entries like

              \\iinnddeexxeennttrryy{{aallpphhaa||((}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa||bboolldd}}{{33}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{55}}

       will be interpreted as

              \\iitteemm aallpphhaa,, \\bboolldd{{33}},, 11----55

       but with a warning message in the transcript about encoun-
       tering an inconsistent  page  encapsulator.   An  explicit
       range  beginning in a Roman page number and ending in Ara-
       bic is also considered an error.  In  this  instance,  (if
       possible)  the  range is broken into two subranges, one in
       Roman and the other in Arabic.  For instance,

              \\iinnddeexxeennttrryy{{aallpphhaa||((}}{{ii}}
              \\iinnddeexxeennttrryy{{aallpphhaa}}{{iivv}}
              \\iinnddeexxeennttrryy{{aallpphhaa}}{{33}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{77}}

       will be turned into

              \\iitteemm aallpphhaa,, ii----iivv,, 33----77

       with a warning message in the transcript file  complaining
       about an illegal range formation.

       Finally,  every  special  symbol mentioned in this section
       may be escaped by the qquuoottee operator (`"').  Thus

              \\iinnddeexxeennttrryy{{aallpphhaa""@@bbeettaa}}{{11}}

       will actually become

              \\iitteemm aallpphhaa@@bbeettaa,,  11

       as a result of executing _m_a_k_e_i_n_d_e_x.  The quoting power  of
       qquuoottee  is  eliminated  if  it  is  immediately preceded by
       eessccaappee (`\').  For example,

              \\iinnddeexxeennttrryy{{ff\\""uurr}}{{11}}

       becomes




                         10 December 1991                      13





MAKEINDEX(1L)                                       MAKEINDEX(1L)


              \\iitteemm ff\\""uurr,, 11

       which represents an umlaut-accented `u' to the TeX  family
       of processors.

       From  version  2.11  of  _m_a_k_e_i_n_d_e_x, the qquuoottee operator may
       quote _a_n_y character in the range 1 ... 255.   Character  0
       is excluded because it is used internally in the _m_a_k_e_i_n_d_e_x
       source code as a string  terminator.   With  this  change,
       sort  keys  can  be  created  for all eight-bit characters
       except 0.  The sorting order is

              punctuation characters (in ASCII order),
              digits,
              control characters (1 ... 31),
              space (32),
              letters (ignoring case),
              characters 127 ... 255.

       Here is an example showing the indexing of  all  printable
       ASCII  characters  other than letters and digits, assuming
       the default TeX format.  For convenience, the page  number
       references are the corresponding ASCII ordinal values.

              \\iinnddeexxeennttrryy{{"" @@""  ((ssppaaccee))}}{{3322}}
              \\iinnddeexxeennttrryy{{""!!@@""!! ((eexxccllaammaattiioonn ppooiinntt))}}{{3333}}
              \\iinnddeexxeennttrryy{{""""@@"""" ((qquuoottaattiioonn mmaarrkk))}}{{3344}}
              \\iinnddeexxeennttrryy{{""##@@""\\## ((sshhaarrpp ssiiggnn))}}{{3355}}
              \\iinnddeexxeennttrryy{{""$$@@""\\$$ ((ddoollllaarr ssiiggnn))}}{{3366}}
              \\iinnddeexxeennttrryy{{""%%@@""\\%% ((ppeerrcceenntt ssiiggnn))}}{{3377}}
              \\iinnddeexxeennttrryy{{""&&@@""\\&& ((aammppeerrssaanndd))}}{{3388}}
              \\iinnddeexxeennttrryy{{""<<@@""$$<<$$ ((lleefftt aannggllee bbrraacckkeett))}}{{6600}}
              \\iinnddeexxeennttrryy{{""==@@""== ((eeqquuaallss))}}{{6611}}
              \\iinnddeexxeennttrryy{{"">>@@""$$>>$$ ((rriigghhtt aannggllee bbrraacckkeett))}}{{6622}}
              \\iinnddeexxeennttrryy{{""??@@""?? ((qquueerryy))}}{{6633}}
              \\iinnddeexxeennttrryy{{""@@@@""@@ ((aatt ssiiggnn))}}{{6644}}
              \\iinnddeexxeennttrryy{{""[[@@""[[ ((lleefftt ssqquuaarree bbrraacckkeett))}}{{9911}}
              \\iinnddeexxeennttrryy{{""\\@@""\\vveerrbb==\\== ((bbaacckkssllaasshh))}}{{9922}}
              \\iinnddeexxeennttrryy{{""]]@@""]] ((rriigghhtt ssqquuaarree bbrraacckkeett))}}{{9933}}
              \\iinnddeexxeennttrryy{{""^^@@""\\vveerrbb==^^== ((ccaarreett))}}{{9944}}
              \\iinnddeexxeennttrryy{{""__@@""\\vveerrbb==__== ((uunnddeerrssccoorree))}}{{9955}}
              \\iinnddeexxeennttrryy{{""``@@""\\vveerrbb==~~== ((ggrraavvee aacccceenntt))}}{{9966}}
              \\iinnddeexxeennttrryy{{""{{@@""\\""{{ ((lleefftt bbrraaccee))}}{{112233}}
              \\iinnddeexxeennttrryy{{""||@@""\\vveerrbb==""||== ((vveerrttiiccaall bbaarr))}}{{112244}}
              \\iinnddeexxeennttrryy{{""}}@@""\\""}} ((rriigghhtt bbrraaccee))}}{{112255}}
              \\iinnddeexxeennttrryy{{""~~@@""\\vveerrbb==~~== ((ttiillddee))}}{{112266}}

       Characters  in the actual fields following the `@' charac-
       ter which have special significance to TeX must be  repre-
       sented  as  control sequences, or as math mode characters.
       Note particularly how the entries for the  at  sign,  left
       and  right  braces,  and the vertical bar, are coded.  The
       index file output by _m_a_k_e_i_n_d_e_x for this example looks like
       this:



                         10 December 1991                      14





MAKEINDEX(1L)                                       MAKEINDEX(1L)


              \\bbeeggiinn{{tthheeiinnddeexx}}

                \\iitteemm !! ((eexxccllaammaattiioonn ppooiinntt)),, 3333
                \\iitteemm "" ((qquuoottaattiioonn mmaarrkk)),, 3344
                \\iitteemm \\## ((sshhaarrpp ssiiggnn)),, 3355
                \\iitteemm \\$$ ((ddoollllaarr ssiiggnn)),, 3366
                \\iitteemm \\%% ((ppeerrcceenntt ssiiggnn)),, 3377
                \\iitteemm \\&& ((aammppeerrssaanndd)),, 3388
                \\iitteemm $$<<$$ ((lleefftt aannggllee bbrraacckkeett)),, 6600
                \\iitteemm == ((eeqquuaallss)),, 6611
                \\iitteemm $$>>$$ ((rriigghhtt aannggllee bbrraacckkeett)),, 6622
                \\iitteemm ?? ((qquueerryy)),, 6633
                \\iitteemm @@ ((aatt ssiiggnn)),, 6644
                \\iitteemm [[ ((lleefftt ssqquuaarree bbrraacckkeett)),, 9911
                \\iitteemm \\vveerrbb==\\== ((bbaacckkssllaasshh)),, 9922
                \\iitteemm ]] ((rriigghhtt ssqquuaarree bbrraacckkeett)),, 9933
                \\iitteemm \\vveerrbb==^^== ((ccaarreett)),, 9944
                \\iitteemm \\vveerrbb==__== ((uunnddeerrssccoorree)),, 9955
                \\iitteemm \\vveerrbb==~~== ((ggrraavvee aacccceenntt)),, 9966
                \\iitteemm \\{{ ((lleefftt bbrraaccee)),, 112233
                \\iitteemm \\vveerrbb==||== ((vveerrttiiccaall bbaarr)),, 112244
                \\iitteemm \\}} ((rriigghhtt bbrraaccee)),, 112255
                \\iitteemm \\vveerrbb==~~== ((ttiillddee)),, 112266

                \\iinnddeexxssppaaccee

                \\iitteemm   ((ssppaaccee)),, 3322

              \\eenndd{{tthheeiinnddeexx}}

FFIILLEESS
       _m_a_k_e_i_n_d_e_x             executable file

       _$_T_E_X_M_F_M_A_I_N_/_t_e_x_/_p_l_a_i_n_/_m_i_s_c_/_i_d_x_m_a_c_._t_e_x
                             TeX macro file used by _m_a_k_e_i_n_d_e_x

       _$_T_E_X_M_F_M_A_I_N_/_t_e_x_/_l_a_t_e_x_/_b_a_s_e_/_m_a_k_e_i_d_x_._s_t_y
                             TeX macro file used by _m_a_k_e_i_n_d_e_x

SSEEEE AALLSSOO
       ditroff(1L),   latex(1L),   make.index   (1L),   qsort(3),
       tex(1L), troff(1L)

       _U_C_S_F _E_n_h_a_n_c_e_d _t_r_o_f_f_/_T_R_A_N_S_C_R_I_P_T _-_- _A_n _O_v_e_r_v_i_e_w,  R.  P.  C.
       Rodgers and Conrad Huang, LSMB Technical Report 90-2, UCSF
       School of Pharmacy, San Francisco, 1990.

       _I_n_d_e_x _P_r_e_p_a_r_a_t_i_o_n _a_n_d _P_r_o_c_e_s_s_i_n_g, Pehong Chen and  Michael
       A.  Harrison,  _S_o_f_t_w_a_r_e_:  _P_r_a_c_t_i_c_e  _a_n_d _E_x_p_e_r_i_e_n_c_e, 1199(9),
       897-915, September 1988.

       _A_u_t_o_m_a_t_i_n_g _I_n_d_e_x _P_r_e_p_a_r_a_t_i_o_n, Pehong Chen and  Michael  A.
       Harrison.  Technical Report 87/347, Computer Science Divi-
       sion, University of California, Berkeley,  1987  (a  LaTeX



                         10 December 1991                      15





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       document supplied with _m_a_k_e_i_n_d_e_x).

       _M_a_k_e_I_n_d_e_x_:  _A_n  _I_n_d_e_x _P_r_o_c_e_s_s_o_r _f_o_r _L_a_T_e_X, Leslie Lamport,
       February 1987 (a LaTeX document supplied with  _m_a_k_e_i_n_d_e_x).

       _T_o_o_l_s  _f_o_r  _P_r_i_n_t_i_n_g  _I_n_d_i_c_e_s, Jon L. Bentley and Brian W.
       Kernighan, _E_l_e_c_t_r_o_n_i_c _P_u_b_l_i_s_h_i_n_g _-_- _O_r_i_g_i_n_a_t_i_o_n_,  _D_i_s_s_e_m_i_-
       _n_a_t_i_o_n_,  _a_n_d _D_e_s_i_g_n, 1(1), 3-18, June 1988 (also available
       as: Computing Science Technical Report No. 128, AT&T  Bell
       Laboratories, Murray Hill, NJ 07974, 1986).

AAUUTTHHOORR
       Pehong  Chen,  Chen & Harrison International Systems, Inc.
       Palo Alto, California, USA <chen@renoir.berkeley.edu>.
       Manual  page  extensively  revised  and   corrected,   and
       _t_r_o_f_f(1)  examples  created  by  Rick  P. C. Rodgers, UCSF
       School of Pharmacy <rodgers@cca.ucsf.edu>.

AACCKKNNOOWWLLEEDDGGMMEENNTTSS
       Leslie Lamport contributed significantly  to  the  design.
       Michael  Harrison  provided  valuable comments and sugges-
       tions.  Nelson Beebe improved on the portable version, and
       maintains the source distribution for the TeX Users Group.
       Andreas Brosig contributed to the  German  word  ordering.
       The  modification  to  the  --mmss  macros was derived from a
       method proposed by Ravi Sethi of AT&T  Bell  Laboratories.
       The  _L_O_G and _C_O_N_T_R_I_B files in the _m_a_k_e_i_n_d_e_x source distri-
       bution record other contributions.





























                         10 December 1991                      16


