home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / texmf / config / EVpath.doc < prev    next >
Text File  |  1995-05-28  |  8KB  |  267 lines
  1.  
  2. EVpath - short documentation
  3. ============================
  4.  
  5.  Written by Giuseppe Ghibò
  6.  © 1994 by Giuseppe Ghibò <ghibo@galileo.polito.it>
  7.  
  8.  
  9. -----------
  10. Description
  11. -----------
  12.  
  13. 1) Environment variables may have any length.
  14.    ------------------------------------------
  15.  
  16.    The environment variable used to specify a path may have
  17.    any length (according to the size of the memory specified into
  18.    Alloc_EnvPath()).
  19.  
  20.    Of course if we specify the environment variable with the
  21.    AmigaDOS command SetEnv, the length of the var is truncated to 255 chars,
  22.    but we can set the Environment variable using for instance an Editor; in
  23.    such case we may have variables of arbitrary length.
  24.  
  25. 2) Recursively path searching.
  26.    ---------------------------
  27.  
  28.    If we append a * or a ** after a path element name, then such name
  29.    is searched recursively for sub-directories. The char * is for
  30.    one-level directory searching, while the ** is for searching into all
  31.    the sub-dirs. Note that ** allow only a maximum of 10 level
  32.    subdirectories (should be enough, but it can be modified changing
  33.    the macro MAX_RECURS_DIR into the file EVPaths.c).
  34.  
  35.    Searching of subdirectories is executed when the function
  36.    Init_EnvPath() is called and it is performed only _ONCE_ for every time
  37.    we run the program, so if we append the ** to a directory which contains
  38.    many (note `many' not `a few') non-reorganized sub-dirs, this can
  39.    _slightly_ slow down the startup of the program. Of course isn't a good
  40.    idea   to use path such as:
  41.  
  42.     .,dh0:**,dh1:**,dh2:**
  43.  
  44.    although this could give an idea of how much time is needed to scan
  45.    all the sub-directories of the whole hard disk (you can try this path
  46.    using TeXWhereIs).
  47.  
  48.    For instance suppose to have the following path:
  49.  
  50.     TeX:texinputs**,TeX:macros*
  51.  
  52.    In such example, then the path list will became, for instance
  53.  
  54.     TeX:texinputs
  55.     TeX:texinputs/one
  56.     TeX:texinputs/one/one
  57.     TeX:texinputs/one/one/two
  58.     TeX:texinputs/one/one/two/three
  59.     TeX:texinputs/one/one/two/three/four
  60.     .
  61.     .
  62.     .
  63.     TeX:texinputs/two
  64.     TeX:texinputs/two/one
  65.     TeX:texinputs/two/one/two
  66.     .
  67.     .
  68.     .
  69.     TeX:texinputs/macro
  70.     TeX:texinputs/macro/one
  71.     TeX:texinputs/macro/two
  72.     TeX:texinputs/macro
  73.     
  74. One of the most advantage of using the chars * and ** is that we don't have
  75. to change the var contents every time we install a new macro package. Since
  76. there are many macro packages for TeX, it is a good idea to keep
  77. each macro package into his own directory. For instance the LaTeX 2e
  78. macro packages contains also many sub-tools, and is a good idea to
  79. keep each tool into his own directory (easy to update) rather than to
  80. put thousands of files into TeX:texinputs/. For instance with
  81.  
  82.     TeX:texinputs/LaTeX2e*
  83.  
  84. we match
  85.  
  86.     TeX:texinputs/LaTeX2e
  87.     TeX:texinputs/LaTeX2e/tools
  88.     TeX:texinputs/LaTeX2e/graphics
  89.     TeX:texinputs/LaTeX2e/babel
  90.  
  91. and so on.
  92.  
  93. Note that there is also some synonymous for * and **:
  94.  
  95.     ---------------------------------
  96.     | Char |       searching        |
  97.     ---------------------------------
  98.     |  *   | one-level directories  |
  99.     | **   | all sub-directories    |
  100.     | #?   | one-level directories  |
  101.     | #?>  | all sub-directories    |
  102.     | *>   | all sub-directories    |
  103.     ---------------------------------
  104.  
  105. Note also that chars * and ** (or synonymous) don't specifies wildcards;
  106. e.g. specifying TeX:macro/ltx*my we don't include every directory
  107. which matches the string `ltx*my'.
  108.  
  109. Specifing TeX:texinputs** or TeX:texinputs/** is exactly the same thing, as
  110. well TeX:texinputs or TeX:texinputs/.
  111.  
  112. 3) Recursively environment variable searching
  113.    ------------------------------------------
  114.  
  115.    In the path of an environment variables, we may also specify
  116.    the name of another environment variable. For instance specifying the
  117.    following path
  118.  
  119.     .,TeX:texinputs,$MYPATH,TeX:macros
  120.  
  121.    then the contents of the environment variable MYPATH will be added
  122.    to the path list. Note that MYPATH could cointain another environment
  123.    variable and so on. Up to 5 level of environment variables recursion are
  124.    allowed (should be enough, but this value can also be changed changing
  125.    the macro MAX_RECURS_VAR in EVpaths.c).
  126.    Closed loop and duplicated entries are ignored. For instance
  127.  
  128.     setenv VARONE   one,"$"VARTWO
  129.     setenv VARTWO   two,"$"VARTHREE
  130.     setenv VARTHREE three,"$"VARFOUR
  131.     setenv VARFOUR  four,"$"VARFIVE
  132.     setenv VARFIVE  five,"$"VARSIX
  133.     setenv VARSIX   six,"$"SEVEN
  134.     setenv SEVEN    seven
  135.  
  136.    In such case if we use the variable VARONE, then we obtain the following
  137.    path list
  138.         one
  139.         two
  140.         three
  141.         four
  142.         five
  143.  
  144.    i.e. since recursive searching of environment variables is limited to 5,
  145.    the two other variables `VARSIX' and `VARSEVEN' are simply ignored.
  146.    Note that enclosing of $ between quotes is needed because otherwise the
  147.    Shell expand the env variable (if it exists). This mean that quotes aren't
  148.    needed if we use an editor to set the argument of an environment
  149.    variable.
  150.    Closed loop are also ignored, for instance if we consider
  151.  
  152.     setenv TEXINPUTS .,tex:texinputs,"$"MFINPUTS
  153.     setenv MFINPUTS  .,mf:mfinputs,"$"TEXINPUTS
  154.  
  155.    if we use TEXINPUTS then the path list will contain
  156.  
  157.     tex:texinputs
  158.     mf:mfinputs
  159.  
  160.    otherwise if we use MFINPUTS the path list will contain
  161.  
  162.     mf:mfinputs
  163.     tex:texinputs
  164.  
  165.    What we can do with a such features? We may specify path
  166.    using TWO environment variables. For instance suppose that
  167.    the variable TEXINPUTS contains:
  168.  
  169.     .,$MYPATH,TeX:texinputs,TeX:LaTeX,TeX:LaTeX2e*
  170.  
  171.    then we may set for instance the env var MYPATH to `mymacro' and then run
  172.    TeX or MF. Suppose now we want to use the files contained into the
  173.    directory `mymacro2'. In such case we have just to change the var
  174.    MYPATH without to change the whole contents of TEXINPUTS.
  175.  
  176. 4) Path separators
  177.    ---------------
  178.  
  179.    Path separators recognized are
  180.  
  181.     , ; SPACES TABs LFs FFs
  182.  
  183.    or any combinations of them. For instance we may have the following
  184.    path
  185.  
  186.     TeX:texinputs,        TeX:macros**
  187.     TeX:latex2e*;     CWeb:macros
  188.     MF:inputs*
  189.     ^L^L
  190.  
  191.     MyTeX:mymacros
  192.  
  193.    and so on.
  194.  
  195. 5) Names containing , ; or SPACES or TABS
  196.    --------------------------------------
  197.  
  198.    If a path name contains a space or , or ; we must to enclose such
  199.    name into quotes. For instance:
  200.  
  201.     "The LaTeX", "this,,  ,,,,dirs"
  202.     "Another;;;;;;;one"
  203.  
  204.    Note that if a quote is leaved open then the path is taken as a
  205.    whole path until a LF or FF is encountered.
  206.  
  207. 6) Current dir.
  208.    ------------
  209.  
  210.    To include the current dir into the path we may use one of the
  211.    following symbols:
  212.  
  213.     .    ""    "."
  214.  
  215.    Note that Unix like syntax such as:
  216.  
  217.     ./mypath        -> directory `mypath' in the current dir
  218.  
  219.    and
  220.  
  221.     ../mypath    -> directory `mymath' in the parent dir.
  222.  
  223.    are supported too.
  224.  
  225. 7) Default path.
  226.    -------------
  227.  
  228.    If the path of the environment variable superseed the default path
  229.    we may include the default path at an arbitrary position. For
  230.    instance:
  231.  
  232.     default path = "MF:inputs,MF:ams/fonts/symbols"
  233.  
  234.         MFINPUTS = .,MF:mfinputs,?,CTAN:mfinputs
  235.  
  236.    then the resulting path list will be:
  237.  
  238.     `'    (current dir)
  239.     `MF:mfinputs'
  240.     `MF:inputs'        (from default path)
  241.     `MF:ams/fonts/symbols'    (from default path)
  242.     `CTAN:mfinputs'
  243.  
  244. 8) Duplicated entries are ignored. For instance using the following path
  245.  
  246.     .,".","",TeX:inputs,MF:inputs,TeX:inputs,MF:inputs
  247.     
  248.    the path list will contain only the following entries:
  249.  
  250.     `'    (current)
  251.     TeX:inputs
  252.     MF:inputs
  253.  
  254.    this means that a file isn't searched into the current dir
  255.    or in the directory TeX:inputs or MF:inputs only _ONCE_. Note that
  256.    although TeX:inputs/ and TeX:inputs are treated in the same way,
  257.    they aren't recognized as same for the purpose to avoid duplicated
  258.    entries.
  259.  
  260. 9) Compatibility with OS 1.3.
  261.    --------------------------
  262.  
  263.    EVPaths routines are fully compatible with OS 1.3. Since
  264.    many TeX related programs still works with OS 1.3 it was a pity to
  265.    loose the OS 1.3 compatibility only for the presence of the
  266.    EVPaths routines...
  267.