home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / vrac / addhlp.zip / ADDHELP.TXT < prev    next >
Text File  |  1994-09-03  |  9KB  |  264 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                  ADDHELP.EXE : adds help
  9.  
  10.                   screens to .COM files
  11.  
  12.           
  13.  
  14.                  version 1.0  August 1994
  15.  
  16.  
  17.                   written by John Nurick
  18.  
  19.                 70162.2472@compuserve.com
  20.  
  21.  
  22.  
  23.  
  24.       Description
  25.       ===========
  26.  
  27.       ADDHELP.EXE modifies .COM files so that they display a help
  28.       message when invoked with the standard '/?' parameter, just
  29.       like standard internal and external DOS commands.
  30.  
  31.       This manual also gives instructions for adding a `/?' help
  32.       screen to a batch file.
  33.  
  34.  
  35.  
  36.  
  37.       Contents
  38.       ========
  39.  
  40.            Background..........................................2
  41.  
  42.            Using ADDHELP.EXE...................................2
  43.  
  44.           Instructions ....................................2
  45.           Limitations and Caveats .........................3
  46.           Patching ........................................4
  47.           Self-checking programs and anti-virus systems ...4
  48.           Help Message Hints ..............................4
  49.           
  50.            Adding Help to Batch Files..........................5
  51.  
  52.            Disclaimer..........................................5
  53.  
  54.                                     
  55.  
  56.       ADDHELP.EXE INSTRUCTIONS                                     2
  57.  
  58.  
  59.       Background
  60.       ==========
  61.  
  62.       There are so many useful little utility programs that it is
  63.       almost impossible to remember what they all do, let alone the
  64.       command line parameters and switches they need. A few offer
  65.       help if you invoke them with no parameters, or with a
  66.       particular parameter (e.g. /?, /h, h, ?, -h, /help). Others,
  67.       especially TSRs and mini-programs created from DEBUG scripts,
  68.       may ignore such parameters and do unexpected things to your
  69.       system.
  70.  
  71.            DOS 5.0 made a start in clearing up this mess. All
  72.       standard DOS 5.x and 6.x commands, internal and external,
  73.       display a brief explanation of their use and syntax if they
  74.       are invoked with the /? switch. ADDHELP.EXE lets you bring
  75.       most .COM utilities from other sources, including the ones
  76.       you create from DEBUG scripts, into line with this convention.
  77.  
  78.  
  79.  
  80.       Using ADDHELP.EXE
  81.       =================
  82.  
  83.       ADDHELP will modify practially any .COM file so that it will
  84.       display help information when invoked with /?. Almost all 
  85.       programs will work absolutely as normal after modification:
  86.       see *Limitations and Caveats* below.
  87.  
  88.            ADDHELP.EXE takes a .COM file and an file of ASCII help
  89.       text and creates a new .COM file with code to display the help 
  90.       message or run the original program. ADDHELP can also dis-
  91.       mantle a file it has modified and recreate the original .COM 
  92.       and help text files.
  93.  
  94.       Syntax:
  95.          ADDHELP /A[dd]      STANDARD.COM HELP.TXT MODIFIED.COM
  96.          ADDHELP /E[xtract]  MODIFIED.COM HELP.TXT STANDARD.COM
  97.          ADDHELP             (display syntax message)
  98.          ADDHELP /?          (Display help screens)
  99.  
  100.          STANDARD.COM   [pathname of] program without help facility
  101.          HELP.TXT       file containing help text
  102.          MODIFIED.COM   [pathname of] program with help facility
  103.  
  104.  
  105.  
  106.                                     
  107.  
  108.       ADDHELP.EXE INSTRUCTIONS                                     3
  109.  
  110.  
  111.       Instructions
  112.  
  113.       (1)  Suppose you want to add a /? help facility to the utility
  114.            STANDARD.COM (see "Limitations and caveats" below for
  115.            information on what kinds of program may not be suitable
  116.            for ADDHELP).
  117.  
  118.       (2)  Prepare an ASCII text file containing the help information.
  119.            Let's call it HELP.TXT. This should not exceed 20 to 23
  120.            lines, to allow room for the DOS prompt. If it displays
  121.            nicely with the command TYPE HELP.TXT, it will work.
  122.  
  123.       (3)  Issue the command
  124.             ADDHELP /A STANDARD.COM HELP.TXT MODIFIED.COM
  125.            ADDHELP will display progress messages (or error
  126.            messages!). If all goes well, MODIFIED.COM will behave
  127.            *exactly* like STANDARD.COM except that when you issue
  128.            the command MODIFIED /? it will display your help screen.
  129.  
  130.  
  131.       Suggested working practices
  132.  
  133.       Keep the original .COM files in one directory or disk, and put
  134.       the modified ones in another, and the help screen files possibly
  135.       in a third. Alternatively, rename the original file first, e.g.:
  136.            REN STANDARD.COM *.C_M
  137.            ADDHELP /A STANDARD.C_M STANDARD.HLP STANDARD.COM
  138.              
  139.  
  140.       Limitations and Caveats
  141.  
  142.       The original and modified files ("STANDARD.COM" and "MODI-
  143.       FIED.COM") must have different filespecs. If they are in the
  144.       same directory they must have different names, but if you
  145.       specify different drives or directories they can have the same
  146.       name. You must specify the full name (including extension) of
  147.       each file. With this exception, ADDHELP output files will over-
  148.       write existing files of the same name without warning.
  149.  
  150.            ADDHELP has worked on every .COM file on which it has
  151.       been tested. But it has not been tested on and is not recom-
  152.       mended for .COM files which act as loaders for large programs
  153.       (e.g. WIN.COM in Microsoft Windows or WS.COM and WORD.COM in
  154.       some versions of WordStar and Microsoft Word). ADDHELP will
  155.       not create a file if it would exceed the 64k .COM limit.
  156.  
  157.            Do not use ADDHELP on programs that modify their own .COM
  158.       files in the course of ordinary activity. See "Patching"
  159.       below.
  160.  
  161.                                     
  162.  
  163.       ADDHELP.EXE INSTRUCTIONS                                     4
  164.  
  165.  
  166.            .EXE files cannot be modified in the same way as .COM
  167.       files. To confuse matters, files with a .COM extension can
  168.       sometimes be in .EXE format. ADDHELP can identify most .EXE
  169.       format files and will refuse to modify them.
  170.  
  171.  
  172.       Patching
  173.  
  174.       Special care is needed when patching a program modified by
  175.       ADDHELP (e.g. to change colours or hot keys).
  176.  
  177.            MODIFIED.COM contains all the code and data that is in
  178.       STANDARD.COM, but not all of it is in exactly the same
  179.       locations in the file. Consequently, attempts to patch bytes
  180.       at particular locations may have unpredictable results. This
  181.       is true whether you are patching with a disk editor, a
  182.       separate configuration program, or (and especially) a self-
  183.       modifying program.
  184.  
  185.            You can avoid this problem by using the ADDHELP /Extract
  186.       command line switch, which extracts code and data from MODI-
  187.       FIED.COM to restore copies of STANDARD.COM and HELP.TXT. These
  188.       can then be altered as necessary before being re-combined into
  189.       a new version of MODIFIED.COM by running ADDHELP in the usual
  190.       way.
  191.  
  192.            The copies of STANDARD.COM and HELP.TXT produced by
  193.       ADDHELP /E are identical to the originals, except that if the
  194.       original STANDARD.COM was shorter than 32 bytes, the extracted
  195.       reconstructed version will be padded out to 32 bytes.
  196.  
  197.  
  198.       Self-checking programs and anti-virus systems
  199.  
  200.       Some programs check themselves when they run to detect unau-
  201.       thorised changes such as those made by a virus. They should
  202.       also detect the changes made by ADDHELP. If this happens,
  203.       there is nothing for it but go back to using STANDARD.COM.
  204.  
  205.       If you use an anti-virus system that keeps track of legal
  206.       executable files, you will have to register MODIFIED.COM with
  207.       the virus checker.
  208.  
  209.  
  210.       Help Message Hints
  211.  
  212.       Use any editor or word processor that can produce plain ASCII
  213.       files to create your help text. To save disk space, keep the
  214.       text as short as you reasonably can, and make sure it fits in
  215.       23 lines or fewer so that the beginning does not scroll off
  216.       the screen. It is a good idea to include copyright details of 
  217.       the original program and the fact that it has been modified by
  218.       ADDHELP.
  219.  
  220.                                     
  221.  
  222.       ADDHELP.EXE INSTRUCTIONS                                     5
  223.  
  224.  
  225.       Adding Help to Batch Files
  226.       ==========================
  227.  
  228.       It is easy to make a batch file display a help message in
  229.       response to the /? parameter. For example:
  230.  
  231.            @echo off
  232.            rem DEMO.BAT
  233.            if "%1"=="/?" goto HELP
  234.            rem Put batch file commands here!
  235.            echo Hello World!.
  236.            pause
  237.            rem End of batch file commands
  238.            goto END
  239.            :HELP
  240.            rem Put echo commands for help message here
  241.            echo.
  242.            echo DEMO.BAT
  243.            echo    Demonstrates use of /? help switch in a batch
  244.            file.
  245.            echo    Syntax: DEMO      (runs main batch code)
  246.            echo            DEMO /?   (displays help message)
  247.            echo.
  248.            :END
  249.  
  250.  
  251.       Disclaimer
  252.       ==========
  253.  
  254.       The author gives no undertaking or warranty as to the per-
  255.       formance of ADDHELP.EXE or its suitability for any purpose
  256.       whatever, and accepts no liability for any loss or damage
  257.       resulting directly or indirectly from its use.
  258.  
  259.       On the other hand, he doesn't ask anything from its users
  260.       either, except perhaps to be told of any bugs they find or 
  261.       improvements they make.
  262.  
  263.       ALWAYS KEEP BACKUPS OF EVERYTHING!!!
  264.