home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR2 / CDH50.ZIP / CDH.TXT < prev   
Text File  |  1993-12-23  |  20KB  |  508 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                                       CDH
  10.                          Change Directory with History
  11.                                   Version 5.0
  12.  
  13.                                   Dave Kruger
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.                       Copyright (C) 1990-1993 Dave Kruger
  54.  
  55.      2                                                                   2
  56.  
  57.  
  58.      COPYRIGHT STATEMENT
  59.      ===================
  60.  
  61.      CDH Copyright (C) 1990-1993 by Dave Kruger.
  62.      All rights reserved.
  63.  
  64.      CDH is free, but it is a copyrighted work and may be distributed only
  65.      pursuant to this license.
  66.  
  67.      Permission is hereby granted to reproduce and disseminate so long as:
  68.  
  69.      (1)  No remuneration of any kind is received in exchange
  70.  
  71.      (2)  Distribution is without ANY modification to the contents of
  72.           CDH.EXE or the accompanying documentation.
  73.  
  74.      No copy of CDH may be distributed without including a copy of this
  75.      license.
  76.  
  77.      Any other use is prohibited without express, written permission in
  78.      advance.
  79.  
  80.  
  81.      DISCLAIMER
  82.      ==========
  83.  
  84.      The information contained in this document is subject to change
  85.      without notice.  This software and documentation are provided free of
  86.      charge and without warranty of any kind.  No responsibility is
  87.      accepted for errors contained in this documentation, or for
  88.      incidental or consequential damages in connection with the
  89.      furnishing, performance, or use of the software or documentation.
  90.  
  91.  
  92.      TRADEMARKS
  93.      ==========
  94.  
  95.      MS-DOS is a registered trademark of Microsoft Corporation.
  96.  
  97.      Windows is a trademark of Microsoft Corporation.
  98.  
  99.      Lotus and 1-2-3 are registered trademarks of Lotus Development
  100.      Corporation
  101.  
  102.      Turbo C is a registered trademark of Borland International, Inc.
  103.  
  104.      4DOS is a registered trademark of JP Software Inc.
  105.  
  106.      UNIX is a registered trademark of UNIX System Laboratories Inc.
  107.  
  108.      3                                                                   3
  109.  
  110.  
  111.                                     CONTENTS
  112.                                     ========
  113.  
  114.                       Introduction.......................3
  115.                       Installation.......................4
  116.                       Synopsis...........................4
  117.                       Description........................4
  118.                       Options............................5
  119.                       Environment Variables..............6
  120.                       Examples...........................6
  121.                       Enhancing Usability................7
  122.                         4DOS and Aliases.................7
  123.                         Batch Files......................8
  124.                         Environment Variables............8
  125.                       Hardware Requirements..............9
  126.                       Diagnostics........................9
  127.                       Bugs and Enhancements..............9
  128.                       Version and History...............10
  129.  
  130.  
  131.      INTRODUCTION
  132.      ============
  133.  
  134.      This manual documents version 5.0 of the CDH (Change Directory with
  135.      History) utility.
  136.  
  137.      CDH replaces CHDIR, the standard MS-DOS change directory command.
  138.      CDH provides similar functionality to CHDIR, but also includes a
  139.      directory history facility.
  140.  
  141.      CDH maintains a record of the last 23 directories visited in a plain
  142.      text file called the history file.  You can change to a directory in
  143.      the history file by referring to it by its numeric position in the
  144.      file, or by specifying any part of its name that differentiates it
  145.      from other directory names in the history file.
  146.  
  147.      CDH also supports a CDPATH environment variable.  If the wanted
  148.      directory is not a subdirectory of the current directory, the paths
  149.      in the CDPATH are searched to find the wanted directory.
  150.  
  151.      CDH differs functionally from MS-DOS's CHDIR command as follows:
  152.  
  153.      1.   If you invoke CDH without an argument, it changes to the
  154.           directory specified by the HOME environment variable.
  155.  
  156.      2.   Unlike CHDIR, CDH changes directories across drives.  For
  157.           example, if the current directory is C:\TMP, and you enter the
  158.           command CDH D:\TC, CDH changes the current directory to \TC and
  159.           also changes the current drive to D:.  This is equivalent to
  160.           entering the two MS-DOS commands: CD D:\TC and D:.
  161.  
  162.      3.   CDH searches the CDPATH environment variable if the wanted
  163.           directory is not in the current directory.
  164.  
  165.      4                                                                   4
  166.  
  167.  
  168.      INSTALLATION
  169.      ============
  170.  
  171.      The only installation necessary to use CDH is to copy the CDH.EXE
  172.      file to a directory in your PATH.
  173.  
  174.      You can customise the installation by defining environment variables,
  175.      aliases, modifying COMMAND.COM, and so on; these are explained in the
  176.      ENHANCING USABILITY section below.
  177.  
  178.  
  179.      SYNOPSIS
  180.      ========
  181.  
  182.      CDH [<dir>] [-?] [-H] [-L] [-V] [-] [-<pattern>] [-<number>]
  183.  
  184.  
  185.      DESCRIPTION
  186.      ===========
  187.  
  188.      The brackets in the synopsis above indicate that the argument is
  189.      optional, therefore, all arguments are optional.  CDH takes a single
  190.      argument only, or no argument at all.  There are two types of
  191.      arguments: minus (-) options and directory names.  Arguments preceded
  192.      by a "-" cause the current directory to change depending on what
  193.      follows the "-".  Anything else is assumed to be a directory name
  194.      that you want to change to.  Case is not significant for any
  195.      argument; CDH sees no difference between -V and -v.  Similarly, the
  196.      following <pattern>s are treated identically: -SnEg, -SNEG, and -sneG.
  197.  
  198.      If you invoke CDH without any arguments, it changes to the directory
  199.      specified in the HOME environment variable (if set) or to the root
  200.      directory on the current drive.
  201.  
  202.      The last 23 directories visited are recorded, in plain text, in the
  203.      history file.  You can specify the name of the history file with the
  204.      CDHISTFILE environment variable.  If CDHISTFILE is not set (or is set
  205.      to an invalid path), the directory history is written to C:\CDHIST. 
  206.      If you change to a directory that is not in the history file, CDH
  207.      inserts the new directory at position zero in the history file and
  208.      moves all existing directories up by one position.  If the history
  209.      file already contains 23 entries, CDH inserts the new directory at
  210.      position zero in the history file, moves all existing directories up
  211.      by one position, and deletes the oldest directory from the history
  212.      file.
  213.  
  214.      You can edit the history file with any text editor, for example, EDIT
  215.      or EDLIN.  You might want to edit the history file, for example, to
  216.      delete entries for directories that no longer exist, or to delete
  217.      references to directories on floppy drives.  The directory history is
  218.      stored in uppercase in the history file.
  219.  
  220.      5                                                                   5
  221.  
  222.  
  223.      You can access a directory in the history file by referring to its
  224.      numeric position in the file, using -<number> as an argument, for
  225.      example, CDH -15; or you can specify any part of a directory name
  226.      using -<pattern> as an argument, for example, CDH -NEG.  Note,
  227.      however, that <pattern>s must be at least two letters long to avoid
  228.      confusion with other "-" options.
  229.  
  230.      When you invoke CDH with a valid directory name (<dir>) as an
  231.      argument, CDH changes to <dir>.  <dir> can be in the current
  232.      directory or in any directory in the CDPATH.
  233.  
  234.  
  235.      OPTIONS
  236.      =======
  237.  
  238.      <dir>      Changes to directory <dir>.  If <dir> does not exist in
  239.                 the current directory, CDH searches the directories
  240.                 specified in the CDPATH environment variable.  If <dir> is
  241.                 invalid after these searches, CDH prints an error message.
  242.  
  243.      -?         Prints a usage message like the synopsis above.
  244.  
  245.      -H         Prints an extended help message.
  246.  
  247.      -L         Lists the contents of the history file and the numeric
  248.                 position of each entry in the file.  This option is useful
  249.                 to determine whether a particular directory is in the
  250.                 history file, and to find its relative position.  You can
  251.                 then use CDH -<number> to change to the directory if it is
  252.                 in the history file (the -<number> option is described
  253.                 below).
  254.  
  255.      -V         Prints the version number of the CDH that you are using.
  256.  
  257.      -          Changes to the previous directory in the history file.
  258.  
  259.      -<pattern> Changes to the first directory in the history file that
  260.                 contains <pattern> anywhere in its path name.  If no entry
  261.                 contains <pattern>, CDH prints an error message.
  262.  
  263.      -<number>  Changes to the directory that is at the <number>th
  264.                 position in the history file.  You can find out the
  265.                 relative number of the directories in the history file by
  266.                 using the -L option described above.  If you enter a
  267.                 number greater than that reported with the -L option, CDH
  268.                 assumes that it is a <pattern>, and searches the history
  269.                 file for a directory that has <number> in its path name.
  270.  
  271.      6                                                                   6
  272.  
  273.  
  274.      ENVIRONMENT VARIABLES
  275.      =====================
  276.  
  277.      By default, CDH calls the history file CDHIST, and creates it in the
  278.      root directory of the C drive.  If you don't like these defaults, you
  279.      can set the CDHISTFILE environment variable to the path and file name
  280.      you prefer.  If the value of CDHISTFILE is invalid, CDH uses the
  281.      default values.
  282.  
  283.      When you invoke CDH with no arguments, it checks for the existence of
  284.      the HOME environment variable.  If HOME is set to a valid path name,
  285.      CDH changes to that directory.  If HOME is not set, CDH changes to
  286.      the root directory of the current drive.  If HOME is set to an
  287.      invalid path, CDH prints an error message and the current directory
  288.      is not changed.
  289.  
  290.      The CDPATH environment variable is a list of pathnames separated by
  291.      semicolons, similar to the standard MS-DOS PATH.  If the directory
  292.      specified by a <dir> argument does not exist in the current
  293.      directory, CDH searches each directory in the CDPATH in turn and
  294.      changes to <dir> if it is found to be a subdirectory in any of them.
  295.      See below for an example of using the CDPATH.
  296.  
  297.      The best place to set these environment variables is in your
  298.      AUTOEXEC.BAT file so they are set each time you boot your computer.
  299.  
  300.  
  301.      EXAMPLES
  302.      ========
  303.  
  304.      CDH -L    Lists directories in the history file.  The examples that
  305.                follow assume that this command reports the following:
  306.  
  307.                     3 D:\TC\INCLUDE
  308.                     2 C:\USR\DAK\C
  309.                     1 C:\TMP
  310.                     0 C:\123\WKS
  311.  
  312.                The examples also assume that the CDPATH environment
  313.                variable is set as follows:
  314.  
  315.                 CDPATH=C:\USR\DAK;D:\TC;C\
  316.  
  317.                The current directory is C:\123\WKS.
  318.  
  319.      CDH -     This command changes to the C:\TMP directory.
  320.  
  321.      7                                                                   7
  322.  
  323.  
  324.      CDH QUIN  Assuming that QUIN is not a subdirectory of C:\TMP, CDH
  325.                searches the directories in the CDPATH and changes to
  326.                QUINCE, which is a subdirectory of C:\USR\DAK.  A CDH -L
  327.                command would now report the following:
  328.  
  329.                     4 D:\TC\INCLUDE
  330.                     3 C:\USR\DAK\C
  331.                     2 C:\123\WKS
  332.                     1 C:\TMP
  333.                     0 C:\USR\DAK\QUINCE
  334.  
  335.      CDH -In   Changes to first directory in history file that contains
  336.                the pattern IN.  The current directory would now be
  337.                D:\TC\INCLUDE.  Note that case is not significant in search
  338.                patterns, and that the current directory is ignored in
  339.                history searches.
  340.  
  341.      CDH -4    Changes to the fourth directory in the history list, that
  342.                is, C:\USR\DAK\C.  (After the last example, entry zero in
  343.                the history file was D:\TC\INCLUDE, and all other entries
  344.                were moved up one position, therefore, C:\USR\DAK\C was
  345.                then entry four in the history file.)
  346.  
  347.  
  348.      ENHANCING USABILITY
  349.      ===================
  350.  
  351.      As pointed out above, installation is as simple as copying CDH.EXE to
  352.      a directory in the PATH.  However, there are some things you can do
  353.      to enhance CDH's usability.  None of these are necessary, but they
  354.      can make CDH even more useful.
  355.  
  356.      4DOS and Aliases:
  357.      -----------------
  358.  
  359.      4DOS, by JP Software, is a replacement for the standard MS-DOS
  360.      command processor, COMMAND.COM.  It is the single most useful
  361.      enhancement you can apply to MS-DOS.  While maintaining 100%
  362.      compatibility with COMMAND.COM, 4DOS provides many useful and
  363.      powerful enhancements.  (4DOS, Version 5.0 does provide a directory
  364.      history function, but the history is lost at each reboot.)  If you
  365.      don't have 4DOS yet, you should--it's the best thing to happen to
  366.      MS-DOS since hard disk support.  (I don't have any affiliation with
  367.      JP Software.  I am merely a very satisfied, registered user.)
  368.  
  369.      4DOS provides an alias function that allows you to create your own
  370.      commands or to effectively change the names of existing commands.  I
  371.      use the following 4DOS aliases with CDH:
  372.  
  373.           ALIAS CD=C:\BIN\CDH
  374.           ALIAS B=C:\BIN\CDH -
  375.           ALIAS DL=C:\BIN\CDH -L
  376.  
  377.      8                                                                   8
  378.  
  379.  
  380.      No matter how I try, I cannot get into the habit of typing CDH
  381.      instead of CD, hence the first alias above.  "B" changes "Back" to
  382.      the previous directory; "DL" is mnemonic for "Directory List".
  383.  
  384.      Several other programs provide an alias function, including ANARKEY
  385.      (where they are called AKAs), CED (synonyms), and the standard
  386.      MS-DOS utility, DOSKEY (macros).  All three allow you to bypass the
  387.      internal CD command with an alias.  Refer to the documentation that
  388.      comes with these products for information about defining aliases.
  389.  
  390.      Batch Files:
  391.      ------------
  392.  
  393.      If you don't have access to an alias facility and you are using a
  394.      version of MS-DOS prior to 5.0, you can write small batch files to
  395.      provide the same functionality.  The above three aliases can be
  396.      implemented in batch files as follows:
  397.  
  398.           CD.BAT              B.BAT               DL.BAT
  399.           ------              -----               ------
  400.           @echo off           @echo off           @echo off
  401.           c:\bin\cdh.exe %1   c:\bin\cdh.exe -    c:\bin\cdh.exe -l
  402.  
  403.      The problem here though, is that the CD command is internal to
  404.      COMMAND.COM, and will always be executed before CD.BAT.  To
  405.      successfully implement CD.BAT you must use a binary editor to edit
  406.      COMMAND.COM and change CD to CX (or another two letters).  You can
  407.      use FED (an excellent utility) to do this.  Search for "CD" and look
  408.      for an occurrence that is near "CHDIR", "MKDIR", and "RMDIR".  I'll
  409.      leave the details for you to figure out, but it's only an issue when
  410.      you want to use "CD" to refer to CDH and you don't have an alias
  411.      facility.
  412.  
  413.      NOTE:     IF YOU DECIDE TO ALTER COMMAND.COM, DO NOT OPERATE ON THE
  414.                ORIGINAL VERSION OF THE FILE.  ALWAYS MAKE SUCH CHANGES ON
  415.                A COPY OF THE FILE ONLY.
  416.  
  417.      Environment Variables:
  418.      ----------------------
  419.  
  420.      There are three environment variables of significance to CDH.
  421.  
  422.      The HOME environment variable is useful if you are in the habit of
  423.      storing your personal files in subdirectories of a "home" directory
  424.      (I use C:\USR\DAK).  Setting the HOME environment variable to this
  425.      directory provides the easiest way of returning to your work area.
  426.  
  427.      The CDHISTFILE environment variable allows you to store the history
  428.      in a location other than the root directory of the C drive, and to
  429.      give the file a name of your choosing.  (By the way, you might've
  430.      wondered why I chose "C:\CDHIST" and not just "\CDHIST" as the
  431.      default name for the history file.  The answer is this: if I chose
  432.      "\CDHIST", CDH would create a history file in the root directory of
  433.      every drive you visited.  By choosing "C:\CDHIST", there is only one
  434.      history file, regardless of the number of disk drives or partitions.)
  435.  
  436.      9                                                                   9
  437.  
  438.  
  439.      By far the most powerful environment variable is CDPATH.  This
  440.      provides an easy way to access subdirectories in a particular
  441.      directory tree.  For example, you might prefer to install all your
  442.      Windows applications in a subdirectory of the WINDOWS directory, for
  443.      example, C:\WINDOWS\APPS.  By including this directory in the CDPATH,
  444.      you can change to the application's directory by using its name only.
  445.      If you use a "home" directory, you could include it in the CDPATH
  446.      also.  Finally, the root directory is another candidate for CDPATH.
  447.      Here is a command to set a typical CDPATH environment variable:
  448.  
  449.           set CDPATH=C:\WINDOWS\APPS;C:\USR\DAK;C:\
  450.  
  451.      With this command in effect, you could change to the Lotus 123 for
  452.      Windows directory (for example, C:\WINDOWS\APPS\123W) by typing:
  453.      CDH 123W.
  454.  
  455.  
  456.      HARDWARE REQUIREMENTS
  457.      ======================
  458.  
  459.      It is feasible to use CDH without a hard disk.  Realistically,
  460.      however, a hard disk is the minimum requirement.  If you do not have
  461.      a hard disk, or your hard disk is not drive C, you must use the
  462.      CDHISTFILE environment variable to specify the name of the history
  463.      file.
  464.  
  465.      There is no real advantage in placing CDH.EXE in a RAM drive.  It has
  466.      to access the hard disk to read the history file anyway, so there is
  467.      very little performance benefit.  Placing the history file in the RAM
  468.      disk is also of little use, because you lose your directory history
  469.      each time you boot your computer.
  470.  
  471.  
  472.      DIAGNOSTICS
  473.      ===========
  474.  
  475.      CDH returns exit code 0 if the argument is valid or the directory
  476.      change is successful.  Otherwise it prints a diagnostic message and
  477.      returns exit code 1.
  478.  
  479.  
  480.      BUGS AND ENHANCEMENTS
  481.      =====================
  482.  
  483.      As far as I can tell, CDH is bug-free.  However, I am always
  484.      interested in hearing about people's experiences.  If you find a bug,
  485.      or have an enhancement request, please tell me about it.  Write to:
  486.  
  487.           Dave Kruger
  488.           PO Box 293
  489.           Bentleigh, 3204
  490.           Victoria, Australia
  491.  
  492.           Internet:  dak@hparc0.aus.hp.com
  493.  
  494.      10                                                                 10
  495.  
  496.  
  497.      VERSION AND HISTORY
  498.      ===================
  499.  
  500.      Version 5.0, the current version, is the first released version.
  501.      Previous versions represented incremental implementation of the
  502.      version 5.0 functionality, or bug fixes resulting from beta testing.
  503.      The first fully working version was version 2.0, 20 March 1990.
  504.  
  505.      CDH was written in Turbo C by Dave Kruger.  It is based on a UNIX ksh
  506.      script written by an unknown author, but modified by Alan Barnes and
  507.      Tim Segall at Hewlett-Packard's Australian Software Operation.
  508.