                          Babel Installation Guide
 
                               20 February 2004


        When you install the babel system you have first to decide
        whether you want to make a new format file. If you don't, you
        miss some of the functionality of the babel system, but you
        can then skip steps 2 through 6 . If you do want to build a
        new format, start with step 1.

        When you want to produce the full listing of all the source
        files in the babel system run babel.drv through LaTeX, then
        use MakeIndex to produce babel.ind using the command:
        makeindex -s bbind.ist babel
        and use MakeIndex to produce babel.gls using the command:
        makeindex -s bbglo.ist -o babel.gls babel.glo
        Then run LaTeX on babel.drv again.

        1 Make sure that you have the Docstrip (version 2) program
          available (it is part of the LaTeX2e distribution);  then
          run the file babel.ins through TeX. 
          This strips all the .dtx files of the comments and produces
          fast loadable versions of the files. 
          The installation files that are part of the babel
          distribution all contain \usedir{tex/generic/babel}
          commands. The effect of this is that TeX will attempt to
          write the files it produces into your TDS compliant
          directory tree. If you have a different tree you should
          either change these commands or comment them out. Using the
          file docstrip.cfg you can instruct docstrip about the `root'
          of the TDS tree. On my Win95 TeX-Live installation I have:
\BaseDirectory{D:/TeX-Local/texmf}
%\BaseDirectory{D:/TeX-Live/texmf}
\UseTDS
          whereas on my Linux installation I use:
\BaseDirectory{/usr/local/TeX}
%\BaseDirectory{/usr/TeX/texmf}
\UseTDS
          If all of these are correct and TeX still complains about
          not being able to store the files it is possible that the
          file texmf.cnf prohibits writing into the system trees.
          Look for the line with openout_any; if it's value is 'p'
          (paranoid) change it to 'r' (restricted).
          If all of the above doesn't work for you (or you commented
          out the \usedir lines) you will have to move the resulting 
          .ldf, .sty, .def, .cfg and .fd files yourself into a
          directory where TeX can find them. 
          Do that now.
          On some operating systems you might get an error message
          such as:

! I can't write on file `./catalan.sty'.
<to be read again>
           \edef
l.455           }

Please type another output file name:

          In such a case you have run into a maximum number of open
          files limit in your computer. You can get around this by
          telling docstrip to open less files at a time (from bug
          report Babel/2592, answer by David Carlisle):

          As long as you have a reasonably new copy of docstrip, 
          you can make a docstrip.cfg file at your site to tell 
          docstrip that you have operating system limits on the
          number of open files.
          Make a file docstrip.cfg with the two lines:
 
\maxfiles{8}
\maxoutfiles{8}
 
          and docstrip will keep below 8 the number of files it has
          open. (You may need to experiment to see how large your 
          system lets you make these numbers, the default is 16)
          See docstrip.dtx 
          % \subsection{Setting maximum numbers of streams}
          for more details.

          Docstrip also produces two files called babel.drv and
          user.drv. You can use babel.drv to produce the full
          documented source listing of the babel system. (Which is
          also provided as babel.dvi) You can use user.drv to produce
          a short document that describes the features of each
          language specific file.

        2 Make sure you have the hyphenation patterns available for
          the languages that you intend to use. If you don't have
          them, you may be able to find them in CTAN, in the directory:
          /tex-archive/language/hyphenation.
          If you happen to have a set of patterns that is not
          available there you could make it available by either
          putting it in the /incoming directory or sending it to me.

        3 The docstripping process will have produced a file called
          hyphen.cfg. This file will be loaded when you build a
          LaTeX format. To build a plain format with the babel system
          preloaded you can use the file bplain.tex as a wrapper for
          plain.tex. When you run it through iniTeX plain.tex will be
          loaded, as well as hyphen.cfg. When you type \dump at the 
          end you will get bplain.fmt which you can use as your
          plain TeX format. Renaming hyphen.tex to something else is
          not permitted by Don Knuth.

        4 Check the hyphenation patterns that you have available and
          want to load into the format. For each language that you
          want to hyphenate correctly you need a hyphenation pattern.
          List them all in the file `language.dat'. The file that is
          in the distribution serves as an example of what you have to
          put in there.
          The files containing hyphenation patterns should be found
          somewhere on TeX's `input path'. What that means depends on
          the implementation of TeX you use:
          - With emTeX there is an environment variable TEXINPUT in
            which you can list the directories to search through,
            adding a ! to a directory will make emTeX do a recursive
            search through the directory tree.
          - With Unix TeX the `system directories' do not need to be
            specified in the environment variable TEXINPUTS; there
            adding a double / to a directory name means recursive
            searching of the directory tree.

        5 Run iniTeX, telling it to load your favorite macro package
          (ie plain or latex).
          When you build a LaTeX format iniTeX will find the file
          hyphen.cfg (provided that you have stored it in the
          correct place).
          When you build a plain TeX format using the supplied file
          bplain.tex iniTeX will also find hyphen.cfg. 

          *Beware*: some implementations of TeX only look in the
          current directory when the \openin primitive is used. If
          your TeX does that you need to put the file `languages.dat'
          in the same directory where you build your format.

        6 When the iniTeX run in step 5 stops with a message about
          not enough memory (trie_size = ...) and "you can ask a
          wizard to enlarge me" You have tried to load more
          hyphenation patterns into TeX's memory then it has room for.
          In that case you can either remove one or more languages
          from the file language.dat or be your own wizard and enlarge
          TeX. I can not tell you how to do that for all
          implementations of TeX as it differs with each
          implementation. Your distribution should contain a
          description of what to. 
          - With emTeX you can influence the size of some of the
            memory arrays with command line switches (/mt:65000 for
            the trie_size).
          - With Unix TeX you have to change a file called tex.ch and
            rebuild TeX using the supplied Makefile. The change you
            need to make is to enlarge the trie_size and
            trie_op_size. 
          - With Web2C TeX (version 7 and newer) you can change the
            value of the trie_size in the file web2c/texmf.cnf.

--- Copyright 2004 Johannes Braams.  All rights reserved ---
