






			     ADDHELP.EXE : adds help

			      screens to .COM files

		  

			     version 1.0  August 1994


			      written by John Nurick

			    70162.2472@compuserve.com




	  Description
	  ===========

	  ADDHELP.EXE modifies .COM files so that they display a help
	  message when invoked with the standard '/?' parameter, just
	  like standard internal and external DOS commands.

	  This manual also gives instructions for adding a `/?' help
	  screen to a batch file.




	  Contents
	  ========

	       Background..........................................2

	       Using ADDHELP.EXE...................................2

		  Instructions ....................................2
		  Limitations and Caveats .........................3
		  Patching ........................................4
		  Self-checking programs and anti-virus systems ...4
		  Help Message Hints ..............................4
		  
	       Adding Help to Batch Files..........................5

	       Disclaimer..........................................5

									

	  ADDHELP.EXE INSTRUCTIONS                                     2


	  Background
	  ==========

	  There are so many useful little utility programs that it is
	  almost impossible to remember what they all do, let alone the
	  command line parameters and switches they need. A few offer
	  help if you invoke them with no parameters, or with a
	  particular parameter (e.g. /?, /h, h, ?, -h, /help). Others,
	  especially TSRs and mini-programs created from DEBUG scripts,
	  may ignore such parameters and do unexpected things to your
	  system.

	       DOS 5.0 made a start in clearing up this mess. All
	  standard DOS 5.x and 6.x commands, internal and external,
	  display a brief explanation of their use and syntax if they
	  are invoked with the /? switch. ADDHELP.EXE lets you bring
	  most .COM utilities from other sources, including the ones
	  you create from DEBUG scripts, into line with this convention.



	  Using ADDHELP.EXE
	  =================

	  ADDHELP will modify practially any .COM file so that it will
	  display help information when invoked with /?. Almost all 
	  programs will work absolutely as normal after modification:
	  see *Limitations and Caveats* below.

	       ADDHELP.EXE takes a .COM file and an file of ASCII help
	  text and creates a new .COM file with code to display the help 
	  message or run the original program. ADDHELP can also dis-
	  mantle a file it has modified and recreate the original .COM 
	  and help text files.

	  Syntax:
	     ADDHELP /A[dd]      STANDARD.COM HELP.TXT MODIFIED.COM
	     ADDHELP /E[xtract]  MODIFIED.COM HELP.TXT STANDARD.COM
	     ADDHELP             (display syntax message)
	     ADDHELP /?          (Display help screens)

	     STANDARD.COM   [pathname of] program without help facility
	     HELP.TXT       file containing help text
	     MODIFIED.COM   [pathname of] program with help facility



									

	  ADDHELP.EXE INSTRUCTIONS                                     3


	  Instructions

	  (1)  Suppose you want to add a /? help facility to the utility
	       STANDARD.COM (see "Limitations and caveats" below for
	       information on what kinds of program may not be suitable
	       for ADDHELP).

	  (2)  Prepare an ASCII text file containing the help information.
	       Let's call it HELP.TXT. This should not exceed 20 to 23
	       lines, to allow room for the DOS prompt. If it displays
	       nicely with the command TYPE HELP.TXT, it will work.

	  (3)  Issue the command
		    ADDHELP /A STANDARD.COM HELP.TXT MODIFIED.COM
	       ADDHELP will display progress messages (or error
	       messages!). If all goes well, MODIFIED.COM will behave
	       *exactly* like STANDARD.COM except that when you issue
	       the command MODIFIED /? it will display your help screen.


	  Suggested working practices

	  Keep the original .COM files in one directory or disk, and put
	  the modified ones in another, and the help screen files possibly
	  in a third. Alternatively, rename the original file first, e.g.:
	       REN STANDARD.COM *.C_M
	       ADDHELP /A STANDARD.C_M STANDARD.HLP STANDARD.COM
		     

	  Limitations and Caveats

	  The original and modified files ("STANDARD.COM" and "MODI-
	  FIED.COM") must have different filespecs. If they are in the
	  same directory they must have different names, but if you
	  specify different drives or directories they can have the same
	  name. You must specify the full name (including extension) of
	  each file. With this exception, ADDHELP output files will over-
	  write existing files of the same name without warning.

	       ADDHELP has worked on every .COM file on which it has
	  been tested. But it has not been tested on and is not recom-
	  mended for .COM files which act as loaders for large programs
	  (e.g. WIN.COM in Microsoft Windows or WS.COM and WORD.COM in
	  some versions of WordStar and Microsoft Word). ADDHELP will
	  not create a file if it would exceed the 64k .COM limit.

	       Do not use ADDHELP on programs that modify their own .COM
	  files in the course of ordinary activity. See "Patching"
	  below.

									

	  ADDHELP.EXE INSTRUCTIONS                                     4


	       .EXE files cannot be modified in the same way as .COM
	  files. To confuse matters, files with a .COM extension can
	  sometimes be in .EXE format. ADDHELP can identify most .EXE
	  format files and will refuse to modify them.


	  Patching

	  Special care is needed when patching a program modified by
	  ADDHELP (e.g. to change colours or hot keys).

	       MODIFIED.COM contains all the code and data that is in
	  STANDARD.COM, but not all of it is in exactly the same
	  locations in the file. Consequently, attempts to patch bytes
	  at particular locations may have unpredictable results. This
	  is true whether you are patching with a disk editor, a
	  separate configuration program, or (and especially) a self-
	  modifying program.

	       You can avoid this problem by using the ADDHELP /Extract
	  command line switch, which extracts code and data from MODI-
	  FIED.COM to restore copies of STANDARD.COM and HELP.TXT. These
	  can then be altered as necessary before being re-combined into
	  a new version of MODIFIED.COM by running ADDHELP in the usual
	  way.

	       The copies of STANDARD.COM and HELP.TXT produced by
	  ADDHELP /E are identical to the originals, except that if the
	  original STANDARD.COM was shorter than 32 bytes, the extracted
	  reconstructed version will be padded out to 32 bytes.


	  Self-checking programs and anti-virus systems

	  Some programs check themselves when they run to detect unau-
	  thorised changes such as those made by a virus. They should
	  also detect the changes made by ADDHELP. If this happens,
	  there is nothing for it but go back to using STANDARD.COM.

	  If you use an anti-virus system that keeps track of legal
	  executable files, you will have to register MODIFIED.COM with
	  the virus checker.


	  Help Message Hints

	  Use any editor or word processor that can produce plain ASCII
	  files to create your help text. To save disk space, keep the
	  text as short as you reasonably can, and make sure it fits in
	  23 lines or fewer so that the beginning does not scroll off
	  the screen. It is a good idea to include copyright details of 
	  the original program and the fact that it has been modified by
	  ADDHELP.

									

	  ADDHELP.EXE INSTRUCTIONS                                     5


	  Adding Help to Batch Files
	  ==========================

	  It is easy to make a batch file display a help message in
	  response to the /? parameter. For example:

	       @echo off
	       rem DEMO.BAT
	       if "%1"=="/?" goto HELP
	       rem Put batch file commands here!
	       echo Hello World!.
	       pause
	       rem End of batch file commands
	       goto END
	       :HELP
	       rem Put echo commands for help message here
	       echo.
	       echo DEMO.BAT
	       echo    Demonstrates use of /? help switch in a batch
	       file.
	       echo    Syntax: DEMO      (runs main batch code)
	       echo            DEMO /?   (displays help message)
	       echo.
	       :END


	  Disclaimer
	  ==========

	  The author gives no undertaking or warranty as to the per-
	  formance of ADDHELP.EXE or its suitability for any purpose
	  whatever, and accepts no liability for any loss or damage
	  resulting directly or indirectly from its use.

	  On the other hand, he doesn't ask anything from its users
	  either, except perhaps to be told of any bugs they find or 
	  improvements they make.

	  ALWAYS KEEP BACKUPS OF EVERYTHING!!!
