


MAKEINDEX(1L)                                       MAKEINDEX(1L)


NNAAMMEE
       makeindex - a general purpose, formatter-independent index
       processor

SSYYNNOOPPSSIISS
       mmaakkeeiinnddeexx [[-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...]

DDEESSCCRRIIPPTTIIOONN
       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 --ss, _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.

OOPPTTIIOONNSS
       --cc        Compress intermediate blanks  (ignoring  leading
                 and  trailing  blanks  and  tabs).   By default,
                 blanks in the index key are retained.

       --gg        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.

       --ii        Take input from  _s_t_d_i_n.   When  this  option  is
                 specified  and  --oo  is not, output is written to
                 _s_t_d_o_u_t.

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

       --oo _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).

       --pp _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).

       --qq        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)


       --rr        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).

       --ss 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.

       --tt 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).

       --LL        sort based on locale settings. Not available  on
                 all systems.

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

SSTTYYLLEE FFIILLEE
       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.

   IINNPPUUTT SSTTYYLLEE SSPPEECCIIFFIIEERRSS
       aaccttuuaall <char>            '@'
                                Symbol indicating that  the  next
                                entry  is to appear in the output
                                file.

       aarrgg__cclloossee <char>         '}'
                                Closing delimiter for  the  index
                                entry argument.

       aarrgg__ooppeenn <char>          '{'
                                Opening  delimiter  for the index
                                entry argument.




                         10 December 1991                       3





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       eennccaapp <char>             '|'
                                Symbol indicating that  the  rest
                                of  the  argument  list  is to be
                                used as the encapsulating command
                                for the page number.

       eessccaappee <char>            '\\'
                                Symbol  which escapes the follow-
                                ing letter, unless its  preceding
                                letter is eessccaappee.  Note: qquuoottee is
                                used to escape the  letter  which
                                immediately follows it, but if it
                                is  preceded  by  eessccaappee,  it  is
                                treated  as a ordinary character.
                                These two symbols  _m_u_s_t  be  dis-
                                tinct.

       kkeeyywwoorrdd <string>         "\\indexentry"
                                Command   which  tells  _m_a_k_e_i_n_d_e_x
                                that its  argument  is  an  index
                                entry.

       lleevveell <char>             '!'
                                Delimiter denoting a new level of
                                subitem.

       qquuoottee <char>             '"'
                                Note: qquuoottee is used to escape the
                                letter  which immediately follows
                                it, but  if  it  is  preceded  by
                                eessccaappee,  it is treated as a ordi-
                                nary character.  These  two  sym-
                                bols _m_u_s_t be distinct.

       rraannggee__cclloossee <char>       ')'
                                Closing  delimiter indicating the
                                end of an explicit page range.

       rraannggee__ooppeenn <char>        '('
                                Opening delimiter indicating  the
                                beginning  of  an  explicit  page
                                range.

   OOUUTTPPUUTT SSTTYYLLEE SSPPEECCIIFFIIEERRSS
       pprreeaammbbllee <string>        "\\begin{theindex}\n"
                                Preamble of output file.

       ppoossttaammbbllee <string>       "\n\n\\end{theindex}\n"
                                Postamble of output file.

       sseettppaaggee__pprreeffiixx <string>  "\n  \\setcounter{page}{"
                                Prefix of command which sets  the
                                starting page number.




                         10 December 1991                       4





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       sseettppaaggee__ssuuffffiixx <string>  "}\n"
                                Suffix  of command which sets the
                                starting page number.

       ggrroouupp__sskkiipp <string>      "\n\n  \\indexspace\n"
                                Vertical  space  to  be  inserted
                                before a new group begins.

       hheeaaddiinnggss__ffllaagg <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).

       hheeaaddiinngg__pprreeffiixx <string>  ""
                                Header  prefix  to  be   inserted
                                before a new letter begins.

       ssyymmhheeaadd__ppoossiittiivvee <string>
                                "Symbols"
                                Heading   for   symbols   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is pos-
                                itive.

       ssyymmhheeaadd__nneeggaattiivvee <string>
                                "symbols"
                                Heading   for   symbols   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is neg-
                                ative.

       nnuummhheeaadd__ppoossiittiivvee <string>
                                "Numbers"
                                Heading   for   numbers   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is pos-
                                itive.

       nnuummhheeaadd__nneeggaattiivvee <string>
                                "numbers"
                                Heading   for   numbers   to   be
                                inserted if hheeaaddiinnggss__ffllaagg is neg-
                                ative.

       iitteemm__00 <string>          "\n  \\item "
                                Command  to  be  inserted between
                                two primary (level 0) items.

       iitteemm__11 <string>          "\n     \\subitem "
                                Command to  be  inserted  between



                         10 December 1991                       5





MAKEINDEX(1L)                                       MAKEINDEX(1L)


                                two secondary (level 1) items.

       iitteemm__22 <string>          "\n       \\subsubitem "
                                Command  to  be  inserted between
                                two level 2 items.

       iitteemm__0011  <<ssttrriinngg>>        "\n    \\subitem "
                                Command to be inserted between  a
                                level  0 item and a level 1 item.

       iitteemm__xx11 <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.

       iitteemm__1122 <string>         "\n    \\subsubitem "
                                Command  to be inserted between a
                                level 1 item and a level 2  item.

       iitteemm__xx22 <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.

       ddeelliimm__00 <string>         ", "
                                Delimiter to be inserted  between
                                a  level 0 key and its first page
                                number (default:  comma  followed
                                by a blank).

       ddeelliimm__11 <string>         ", "
                                Delimiter  to be inserted between
                                a level 1 key and its first  page
                                number  (default:  comma followed
                                by a blank).

       ddeelliimm__22 <string>         ", "
                                Delimiter to be inserted  between
                                a  level 2 key and its first page
                                number (default:  comma  followed
                                by a blank).

       ddeelliimm__nn <string>         ", "
                                Delimiter  to be inserted between
                                two page numbers for the same key
                                in any level (default: comma fol-
                                lowed by a blank).

       ddeelliimm__rr <string>         "--"
                                Delimiter to be inserted  between
                                the starting and ending page num-
                                bers of a range.



                         10 December 1991                       6





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       ddeelliimm__tt <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.

       eennccaapp__pprreeffiixx <string>    "\\"
                                First part of prefix for the com-
                                mand  which encapsulates the page
                                number.

       eennccaapp__iinnffiixx <string>     "{"
                                Second part  of  prefix  for  the
                                command  which  encapsulates  the
                                page number.

       eennccaapp__ssuuffffiixx <string>    "}".
                                Suffix  for  the  command   which
                                encapsulates the page number.

       lliinnee__mmaaxx <number>        72
                                Maximum  length  of a line in the
                                output,  beyond  which   a   line
                                wraps.

       iinnddeenntt__ssppaaccee <string>    "\t\t"
                                Space  to be inserted in front of
                                a  wrapped  line  (default:   two
                                tabs).

       iinnddeenntt__lleennggtthh <number>   16
                                Length  of iinnddeenntt__ssppaaccee (default:
                                16, equivalent to 2 tabs).

       ssuuffffiixx__22pp <string>       ""
                                Delimiter to  replace  the  range
                                delimiter  and  the  second  page
                                number of a two page  list.  When
                                present,  it  overrides  ddeelliimm__rr.
                                Example: "f.".

       ssuuffffiixx__33pp <string>       ""
                                Delimiter to  replace  the  range
                                delimiter  and  the  second  page
                                number of a three page list. When
                                present, it overrides ddeelliimm__rr and
                                ssuuffffiixx__mmpp.  Example: "ff.".

       ssuuffffiixx__mmpp <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  ddeelliimm__rr.
                                Example: "f.".

EEXXAAMMPPLLEESS
   TTeeXX EEXXAAMMPPLLEE
       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:

              pprreeaammbbllee
              ""\\\\ddooccuummeennttssttyyllee[[1122pptt]]{{bbooookk}}
              \\\\bbeeggiinn{{ddooccuummeenntt}}
              \\\\bbeeggiinn{{tthheeiinnddeexx}}
              {{\\\\ssmmaallll\\nn""
              ppoossttaammbbllee
              ""\\nn\\nn}}
              \\\\eenndd{{tthheeiinnddeexx}}
              \\\\eenndd{{ddooccuummeenntt}}\\nn"

       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:

              mmaakkeeiinnddeexx  --ss bbooookk..iisstt  --oo ffoooottmmpp..iinndd  --pp oodddd  ffoooo

       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!).

   TTRROOFFFF EEXXAAMMPPLLEE
       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:

              kkeeyywwoorrdd ""IIXX::""
              pprreeaammbbllee
              ""..\\\\\\"" ssttaarrtt ooff iinnddeexx oouuttppuutt
              \\""..\\\\\\"" eenntteerr ttwwoo ccoolluummnn mmooddee
              ..22CC
              ..SSHH
              ..ccee
              IINNDDEEXX
              ..XXSS
              IINNDDEEXX
              ..XXEE
              ..RR
              ..ppss 99pp
              ..vvss 1111pp
              ..sspp
              ..ddee II11
              ..ttii 00..2255ii
              ....
              ..ddee II22



                         10 December 1991                       8





MAKEINDEX(1L)                                       MAKEINDEX(1L)


              ..ttii 00..55ii
              ....""
              ppoossttaammbbllee ""\\nn..\\\\\\"" eenndd ooff iinnddeexx oouuttppuutt""
              sseettppaaggee__pprreeffiixx ""\\nn..nnrr %% ""
              sseettppaaggee__ssuuffffiixx """"
              ggrroouupp__sskkiipp ""\\nn..sspp 11..00""
              hheeaaddiinnggss__ffllaagg 11
              hheeaaddiinngg__pprreeffiixx ""\\nn..IISS\\nn""
              hheeaaddiinngg__ssuuffffiixx ""\\nn..IIEE""
              iitteemm__00 ""\\nn..bbrr\\nn""
              iitteemm__11 ""\\nn..II11\\nn""
              iitteemm__22 ""\\nn..II22\\nn""
              iitteemm__0011 ""\\nn..II11\\nn""
              iitteemm__xx11 ""\\nn..II11\\nn""
              iitteemm__1122 ""\\nn..II22\\nn""
              iitteemm__xx22 ""\\nn..II22\\nn""
              ddeelliimm__00 "",, ""
              ddeelliimm__11 "",, ""
              ddeelliimm__22 "",, ""
              ddeelliimm__rr ""--""
              ddeelliimm__tt ""..""
              eennccaapp__pprreeffiixx ""\\\\ffBB""
              eennccaapp__iinnffiixx """"
              eennccaapp__ssuuffffiixx ""\\\\ffPP""
              iinnddeenntt__ssppaaccee """"
              iinnddeenntt__lleennggtthh 00

       The local macro package may require  modification,  as  in
       this  example of an extension to the --mmss macros (note that
       at some sites, this macro should  _r_e_p_l_a_c_e  a  pre-existing
       macro of the same name):

              ..
              ..ddee IIXX
              ..iiee ''\\\\nn((..zz'''' ..ttmm IIXX:: \\\\$$11 \\\\$$22 \\\\$$33 \\\\$$44 \\\\$$55 \\\\$$66 \\\\$$77 \\\\$$88 \\\\$$99 {{\\\\nn((PPNN}}
              ..eell \\\\!!..IIXX \\\\$$11 \\\\$$22 \\\\$$33 \\\\$$44 \\\\$$55 \\\\$$66 \\\\$$77 \\\\$$88 \\\\$$99 {{\\\\nn((PPNN}}
              ....

       (note  that the string {\\\\nn((PPNN} 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:

              TThhiiss iiss aa ssaammppllee ffiillee ttoo tteesstt tthhee \\ffIImmaakkeeiinnddeexx\\ffPP((11LL))
              pprrooggrraamm,, aanndd sseeee
              ..IIXX {{iinnddeexxiinngg!!pprrooggrraammss!!CC llaanngguuaaggee}}
              ..IIXX {{mmaakkeeiinnddeexx@@\\ffIImmaakkeeiinnddeexx\\ffPP((11LL))}}
              ..bbpp
              ..rrss
              ..IIXX {{KKnnuutthh}}
              ..IIXX {{ttyyppeesseettttiinngg!!ccoommppuutteerr--aaiiddeedd}}
              hhooww wweellll iitt ffuunnccttiioonnss iinn tthhee \\ffIIttrrooffff\\ffPP((11)) eennvviirroonnmmeenntt..




                         10 December 1991                       9





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       Note  that  index  entries are indicated by the ..IIXX macro,
       which causes the following text to be  written  to  _s_t_d_o_u_t
       along with the current page number.

   CCRREEAATTIINNGG TTHHEE IINNDDEEXX FFIILLEE IINN TTHHEE BBOOUURRNNEE SSHHEELLLL
       To create an input file for _m_a_k_e_i_n_d_e_x, iinn tthhee BBoouurrnnee sshheellll
       environment, do the equivalent at your site  of  the  com-
       mand:

       ppssrrooffff --mmss --TTppsscc --tt ssaammppllee..ttxxtt >> //ddeevv//nnuullll 22>> ssaammppllee..ttmmpp

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

              ggrreepp ''^^IIXX:: '' ssaammppllee..ttmmpp >> ssaammppllee..iiddxx

   CCRREEAATTIINNGG TTHHEE IINNDDEEXX FFIILLEE UUSSIINNGG UUCCSSFF EENNHHAANNCCEEDD TTRROOFFFF//TTRRAANNSSCCRRIIPPTT
       With UCSF Enhanced  troff/TRANSCRIPT,  the  --II  option  of
       _p_s_r_o_f_f(1L)  can produce both formatter output and an index
       file:

              ppssrrooffff --mmss --II ssaammppllee..iinnpp --TTppsscc ssaammppllee..ttxxtt

       If it is wished to suppress the formatter output:

              ppssrrooffff --mmss --II ssaammppllee..iinnpp --TTppsscc --tt ssaammppllee..ttxxtt >> //ddeevv//nnuullll

   CCOOMMPPLLEETTIINNGG TTHHEE IINNDDEEXX
       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:

              mmaakkeeiinnddeexx --ss ssaammppllee..iisstt ssaammppllee..iiddxx

       This  leaves _t_r_o_f_f(1)-ready output in the file _s_a_m_p_l_e_._i_n_d.

OORRDDEERRIINNGG
       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  --ll
       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.

SSPPEECCIIAALL EEFFFFEECCTTSS
       Entries such as

              \\iinnddeexxeennttrryy{{aallpphhaa}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa!!bbeettaa}}{{33}}
              \\iinnddeexxeennttrryy{{aallpphhaa!!bbeettaa!!ggaammmmaa}}{{1100}}

       in the input file will be converted to

              \\iitteemm aallpphhaa,, 11
                 \\ssuubbiitteemm bbeettaa,, 33
                    \\ssuubbssuubbiitteemm ggaammmmaa,, 1100

       in  the  output  index file.  Notice that the lleevveell symbol
       (`!') is used above to delimit hierarchical levels.

       It is possible to make an item appear in a designated form
       by using the aaccttuuaall (`@') operator.  For instance,

              \\iinnddeexxeennttrryy{{aallpphhaa@@{{\\iitt aallpphhaa\\//}}}}{{11}}

       will become

              \\iitteemm {{\\iitt aallpphhaa\\//}},,  11

       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 aaccttuuaall 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:

              \\iinnddeexxeennttrryy{{aaaa@@{{\\iitt aaaa\\//}}!!bbbb@@{{\\iitt bbbb\\//}}!!cccc@@{{\\iitt cccc\\//}}}}{{11}}

       This will be converted to

              \\iitteemm {{\\iitt aaaa}},, 11
                 \\ssuubbiitteemm {{\\iitt bbbb}},, 33
                    \\ssuubbssuubbiitteemm {{\\iitt cccc}},, 1100

       It is possible to encapsulate a page number with a  desig-
       nated command using the eennccaapp (`|') operator:

              \\iinnddeexxeennttrryy{{aallpphhaa||bboolldd}}{{11}}



                         10 December 1991                      11





MAKEINDEX(1L)                                       MAKEINDEX(1L)


       will be converted to

              \\iitteemm aallpphhaa,, \\bboolldd{{11}}

       where,  with  a suitable definition for TeX, \\bboolldd{{nn}} will
       expand to {{\\bbff nn}}.  In  this  example,  the  three  output
       attributes     associated    with    page    encapsulation
       eennccaapp__pprreeffiixx, eennccaapp__iinnffiixx, and eennccaapp__ssuuffffiixx, 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 eennccaapp operator can also be used to create cross refer-
       ences in the index:

              \\iinnddeexxeennttrryy{{aallpphhaa||sseeee{{bbeettaa}}}}{{11}}

       will become

              \\iitteemm aallpphhaa,, \\sseeee{{bbeettaa}}{{11}}

       in the output file, where

              \\sseeee{{bbeettaa}}{{11}}

       will expand to

              {{\\iitt sseeee\\//}} bbeettaa

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

       A pair of eennccaapp concatenated with  rraannggee__ooppeenn  (`|(')  and
       rraannggee__cclloossee (`|)') creates an explicit page range:

              \\iinnddeexxeennttrryy{{aallpphhaa||((}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{55}}

       will become

              \\iitteemm aallpphhaa,, 11----55

       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)


              \\iinnddeexxeennttrryy{{aallpphhaa||((bboolldd}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{55}}

       will become

              \\iitteemm aallpphhaa,, \\bboolldd{{11----55}}

       Several potential problems are worth  mentioning.   First,
       entries like

              \\iinnddeexxeennttrryy{{aallpphhaa||((}}{{11}}
              \\iinnddeexxeennttrryy{{aallpphhaa||bboolldd}}{{33}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{55}}

       will be interpreted as

              \\iitteemm aallpphhaa,, \\bboolldd{{33}},, 11----55

       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,

              \\iinnddeexxeennttrryy{{aallpphhaa||((}}{{ii}}
              \\iinnddeexxeennttrryy{{aallpphhaa}}{{iivv}}
              \\iinnddeexxeennttrryy{{aallpphhaa}}{{33}}
              \\iinnddeexxeennttrryy{{aallpphhaa||))}}{{77}}

       will be turned into

              \\iitteemm aallpphhaa,, ii----iivv,, 33----77

       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 qquuoottee operator (`"').  Thus

              \\iinnddeexxeennttrryy{{aallpphhaa""@@bbeettaa}}{{11}}

       will actually become

              \\iitteemm aallpphhaa@@bbeettaa,,  11

       as a result of executing _m_a_k_e_i_n_d_e_x.  The quoting power  of
       qquuoottee  is  eliminated  if  it  is  immediately preceded by
       eessccaappee (`\').  For example,

              \\iinnddeexxeennttrryy{{ff\\""uurr}}{{11}}

       becomes




                         10 December 1991                      13





MAKEINDEX(1L)                                       MAKEINDEX(1L)


              \\iitteemm ff\\""uurr,, 11

       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 qquuoottee 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.

              \\iinnddeexxeennttrryy{{"" @@""  ((ssppaaccee))}}{{3322}}
              \\iinnddeexxeennttrryy{{""!!@@""!! ((eexxccllaammaattiioonn ppooiinntt))}}{{3333}}
              \\iinnddeexxeennttrryy{{""""@@"""" ((qquuoottaattiioonn mmaarrkk))}}{{3344}}
              \\iinnddeexxeennttrryy{{""##@@""\\## ((sshhaarrpp ssiiggnn))}}{{3355}}
              \\iinnddeexxeennttrryy{{""$$@@""\\$$ ((ddoollllaarr ssiiggnn))}}{{3366}}
              \\iinnddeexxeennttrryy{{""%%@@""\\%% ((ppeerrcceenntt ssiiggnn))}}{{3377}}
              \\iinnddeexxeennttrryy{{""&&@@""\\&& ((aammppeerrssaanndd))}}{{3388}}
              \\iinnddeexxeennttrryy{{""<<@@""$$<<$$ ((lleefftt aannggllee bbrraacckkeett))}}{{6600}}
              \\iinnddeexxeennttrryy{{""==@@""== ((eeqquuaallss))}}{{6611}}
              \\iinnddeexxeennttrryy{{"">>@@""$$>>$$ ((rriigghhtt aannggllee bbrraacckkeett))}}{{6622}}
              \\iinnddeexxeennttrryy{{""??@@""?? ((qquueerryy))}}{{6633}}
              \\iinnddeexxeennttrryy{{""@@@@""@@ ((aatt ssiiggnn))}}{{6644}}
              \\iinnddeexxeennttrryy{{""[[@@""[[ ((lleefftt ssqquuaarree bbrraacckkeett))}}{{9911}}
              \\iinnddeexxeennttrryy{{""\\@@""\\vveerrbb==\\== ((bbaacckkssllaasshh))}}{{9922}}
              \\iinnddeexxeennttrryy{{""]]@@""]] ((rriigghhtt ssqquuaarree bbrraacckkeett))}}{{9933}}
              \\iinnddeexxeennttrryy{{""^^@@""\\vveerrbb==^^== ((ccaarreett))}}{{9944}}
              \\iinnddeexxeennttrryy{{""__@@""\\vveerrbb==__== ((uunnddeerrssccoorree))}}{{9955}}
              \\iinnddeexxeennttrryy{{""``@@""\\vveerrbb==~~== ((ggrraavvee aacccceenntt))}}{{9966}}
              \\iinnddeexxeennttrryy{{""{{@@""\\""{{ ((lleefftt bbrraaccee))}}{{112233}}
              \\iinnddeexxeennttrryy{{""||@@""\\vveerrbb==""||== ((vveerrttiiccaall bbaarr))}}{{112244}}
              \\iinnddeexxeennttrryy{{""}}@@""\\""}} ((rriigghhtt bbrraaccee))}}{{112255}}
              \\iinnddeexxeennttrryy{{""~~@@""\\vveerrbb==~~== ((ttiillddee))}}{{112266}}

       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)


              \\bbeeggiinn{{tthheeiinnddeexx}}

                \\iitteemm !! ((eexxccllaammaattiioonn ppooiinntt)),, 3333
                \\iitteemm "" ((qquuoottaattiioonn mmaarrkk)),, 3344
                \\iitteemm \\## ((sshhaarrpp ssiiggnn)),, 3355
                \\iitteemm \\$$ ((ddoollllaarr ssiiggnn)),, 3366
                \\iitteemm \\%% ((ppeerrcceenntt ssiiggnn)),, 3377
                \\iitteemm \\&& ((aammppeerrssaanndd)),, 3388
                \\iitteemm $$<<$$ ((lleefftt aannggllee bbrraacckkeett)),, 6600
                \\iitteemm == ((eeqquuaallss)),, 6611
                \\iitteemm $$>>$$ ((rriigghhtt aannggllee bbrraacckkeett)),, 6622
                \\iitteemm ?? ((qquueerryy)),, 6633
                \\iitteemm @@ ((aatt ssiiggnn)),, 6644
                \\iitteemm [[ ((lleefftt ssqquuaarree bbrraacckkeett)),, 9911
                \\iitteemm \\vveerrbb==\\== ((bbaacckkssllaasshh)),, 9922
                \\iitteemm ]] ((rriigghhtt ssqquuaarree bbrraacckkeett)),, 9933
                \\iitteemm \\vveerrbb==^^== ((ccaarreett)),, 9944
                \\iitteemm \\vveerrbb==__== ((uunnddeerrssccoorree)),, 9955
                \\iitteemm \\vveerrbb==~~== ((ggrraavvee aacccceenntt)),, 9966
                \\iitteemm \\{{ ((lleefftt bbrraaccee)),, 112233
                \\iitteemm \\vveerrbb==||== ((vveerrttiiccaall bbaarr)),, 112244
                \\iitteemm \\}} ((rriigghhtt bbrraaccee)),, 112255
                \\iitteemm \\vveerrbb==~~== ((ttiillddee)),, 112266

                \\iinnddeexxssppaaccee

                \\iitteemm   ((ssppaaccee)),, 3322

              \\eenndd{{tthheeiinnddeexx}}

FFIILLEESS
       _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

SSEEEE AALLSSOO
       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, 1199(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).

AAUUTTHHOORR
       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>.

AACCKKNNOOWWLLEEDDGGMMEENNTTSS
       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  --mmss  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


