
			DOC2COM / D2COLOR Version 1.31
			      Table of contents

	1.00  Introduction .................................. p. 1
	2.00  Requirements .................................. p. 1
	3.00  Using DOC2COM to create a self-display file ... p. 1
	  3.10  Additional command line parameters .......... p. 2
	    3.11  A word about data security ................ p. 3
	4.00  Browsing the self-display file ................ p. 4
	5.00  Guidelines for the text file .................. p. 4
	  5.10	Providing for special colors ................ p. 5
	6.00  Using D2COLOR to set screen colors ............ p. 6
	  6.10	Setting special colors ...................... p. 6
	7.00  Possible problems ............................. p. 7
	8.00  Shareware Registration Guidelines ............. p. 8

      Wanna start quick? Read sections 1.00 and 3.00, then go to it!

			Alt-P = Print this document
			   F1 = Help

       DOC2COM / D2COLOR 1.31 copyright 1991, 1994 by Jerry DePyper
   Use of these programs without the author's permission is prohibited.

				- 1 -

	1.00  Introduction
	==================

	Did you ever create a documentation or informational text file
	for people to look at or print?  DOC2COM can make a self-browsing
	file out of it.  DOC2COM uses the text file as a base for
	creating a '.com' file that can be executed as a callable DOS
	program.  I designed it so I could create manual.com and
	readme.com files (like this one) to distribute with my shareware
	program packages.

	DOC2COM accomplishes its task by appending your text file
	contents to some machine code logic for displaying, scrolling,
	etc, and by calculating some basic internal variable values.
	It then writes the whole thing out as a .com file in one
	effortless step.


	2.00  Requirements
	==================

	1. MS-DOS or PC-DOS 2.0 or later
	2. IBM or compatible
	3. 25 x 80 display mode
	4. RAM memory = 2500 to 4000 bytes + text file size
	(In other words, almost any IBM-compatible system will do.)



	3.00  Using DOC2COM to create a self-display file
	=================================================

	Using DOC2COM is easy. In its simplest form, the command line
	looks like this:

			DOC2COM docfile

	where 'docfile' is the input ASCII text file.  In this case,
	DOC2COM would create an	executable '.com' file in the current
	directory using the same name as 'docfile', but with a .com
	extension. The input text file must not have the .com extension,
	and any already existing file with the same name and a .com
	extension will be overwritten without warning.
	
	That's all you need to know to create self-displaying text
	files. If you want some more details, read on. If not, go to
	it! (But please come back here sometime to read section 8.00
	about registering your copy with me.)
				- 2 -

	3.10  Additional command line parameters
	========================================

	For more control, you may include one or more optional
	command line parameters. The complete command line syntax is:
	
	    DOC2COM docfile [comfile] [/e] [/n] [/s] [/p-nn] [/0|1|2]
						      
	where 'comfile' is the name of the .com self-displaying file
	created by DOC2COM. By including this parameter, you may
	give a name to your self-displaying file independently of the
	input text file's name. You may also specify a different
	drive and path where it will be created.

	'/e' is a switch that means all extended ASCII characters in
	the text file will be displayed by the self-displaying file.
	If this switch is omitted, only text characters will appear.
	The text you are reading, and the double-dash lines used for
	emphasis, (i.e. anything you can type from the keyboard), are
	examples of true text characters. A good example of non-text
	characters (extended ASCII) are the following figures:

	ͻ	   
	                                          	   
	                                          	   
	                                          	   
	                                          	   
	                                          	   
	                                          	   
	Ķ	   
	                                          	   
	                                          	   
	                                          	   
	ͼ	   

	I wanted them to display, so I entered this command:

			doc2com readme.doc /e
	
	to create the readme file you are browsing.

	----------------

	'/n' = No text encryption.
	(See "3.11  A word about data security" below.)

	'/s' = disable shadows: As of version 1.3, the little pop-up
	windows now cast 'shadows', which give the self-displaying file
	a more polished look on color systems. You may disable these
	shadows with the '/s' switch.

                               - 3 -

        '/p-nn' is a switch that allows you to adjust the page counter.
	(See 4.00 below for page jumping in the self-display file.)
	By default, all text documents start on page #1, and increment
	the page counter at every form-feed (page-break) character.
	Sometimes, however, you may have some header information,
	like the table of contents above, that you don't want to count
	as a page. Many times a document file will even start with
	a form-feed character, which will cause the page counter to
	increment before you even get started. Well, anyway, this
	switch allows you some control over the internal page numbering
	of the self-display file.

	For example, because of the table of contents, what I
	considered as page #1 of this readme document was really the
	2nd page. To tell DOC2COM to adjust the page counter by -1,
	I included the /p switch as follows:

			doc2com readme.doc /e /p-1

	----------------

	The 4th command line switch, also new in version 1.3, is used
	to control how many features the self-display file will have,
	and therefore, how much overhead will be added to the text
	file in making the self-display file. This switch can be set
	to one of three settings: /0, /1, or /2. If not used, the full-
	feature setting /2 is assumed. Here is how the three settings
	compare:

	|---------|------------------------|--------------------------------|
	| Setting |	  Overhead	   |	       Features 	    |
	|	  | (Bytes added to Text)  |				    |
	|=========|========================|================================|
	|   /0	  |	   1700	   |  Scroll Up, Down, PgUp, PgDn   |
	|	  |			   |  Home, End, Help		    |
	|---------|------------------------|--------------------------------|
	|   /1	  |	   2500	   |  Above plus jump to specific   |
	|	  |			   |  line ("L") or page ("P")      |
	|---------|------------------------|--------------------------------|
	|   /2	  |	   3300	   |  Above plus print text (Alt-P) |
	|(default)|			   |  or create text file (Alt-F)   |
	|---------|------------------------|--------------------------------|

	So, for little simple files, you may choose /0 or /1 to keep the
	size of the .com file down. Not that 3300 bytes added is much
	overhead, but this also gives you more control over the functionality
	of the self-display files you create, as the following notes.



	3.11  A word about data security
	================================

	It's one thing for you to distribute a self-displaying text file.
	It may be quite another to give your users the ability to clone your
	original document. To address this security issue, DOC2COM now stores
	all text in the self-display file in encrypted form. So, if you use
	switch setting /0 or /1 to prevent the explicit cloning or printing
	of the original document, you literally make it view-only text.

	As noted above, the /n switch will turn encryption off.

				- 4 -

	4.00  Browsing the self-display file
	====================================

	You can see from the readme.com file you are now browsing how
	these self-displaying programs will behave.  After you typed
	'readme' to invoke this, you may have instinctively started using
	the cursor movement keys to move around. Or, if you hit some
	other keys, you quickly saw from the little pop-up message which
	keys to use.  And did you notice the horizontal page dividers?
	They correspond to the presence of the form-feed character (0C hex)
	in the text file, which is the same character that would cause a
	new page to print if you routed the text file to a printer.

	Unless you specify switch /0, the self-display file will allow
	the viewer to jump directly to any page or line of the document
	via the 'P' and 'L' keys respectively. This is especially nice
	in larger files such as a self-displaying manual or instructional
	document.

	Unless you use switch /0 or /1, the viewer may also use the 'Alt-F''
	keystroke to create a clone of the original text file, or 'Alt-P'
	to route it to his printer. For example, you may print out this
	readme text at any time via 'Alt-P', then use the resulting document
	as a reference manual for using DOC2COM and D2COLOR. In the same
	manner, you may use 'Alt-F' to create a copy of the document I used
	to create this self-display readme.com.
	

	5.00  Guidelines for the text file
	==================================

	Generally speaking, the guidelines for creating a good text file
	for DOC2COM to use are the same as for producing a file that can
	easily be printed on a variety of printers:

	1. Keep line length to 80 columns or less.
	2. Eliminate special word-processing characters or format strings.
	   (Most word processers have a 'text file' mode that does this.)

	With version 1.3 of DOC2COM, when the viewer uses 'Alt-F' or
	'Alt-P', he may no longer get exactly what you put in the original
	document, as was the case in version 1.2. Instead, he will get
	what he sees. For example, if there are extended ASCII characters
	in your text document, these will be reproduced in the cloned file
	and/or sent to the printer only if you used the /e switch to allow
	them to display. Be aware that these extended ASCII box and shade
	characters are not recognized by some printers. You can test your
	printer by using 'Alt-P' to print this text with its box characters.
	If you want to play it safe, use dashes, etc, instead of extended
	ASCII. Likewise, the 'trigger' characters as discussed below will
	not show up in a document cloned or printed via 'Alt-F' or 'Alt-P'.


				- 5 -

	5.10  Providing for special colors
	==================================

	Generally, the files produced by DOC2COM will display all text in
	the same screen color, which can be changed through D2COLOR (see
	section 6.00 below). As you see in this readme file, however, you
	can also highlight some words by setting the screen color for
	them differently. This is accomplished by means of 'trigger'
	characters which you embed in the text, and which will signal
	DOC2COM to change the screen color. These 'trigger' characters
	and their associated color attributes are then specified through
	D2COLOR as well (see section 6.10 below).

	The display algorithm in the self-display file scans all text a
	line at a time, from left to right. When it encounters a trigger
	character, it begins displaying all text to the right of it in
	the alternate color associated with that trigger, until it
	encounters another trigger, or it comes to the end of the line.
	The next line will revert to the default color, unless it, too,
	has a trigger character.
	
	You will usually want to choose as trigger characters something
	which is not used, or used rarely in the body of your document.
	For example, I don't use the curly bracket characters '{' and '}'
	much, so I chose to use them as trigger characters. Namely, the
	left bracket '{' I designate to set to a bright blue color on
	a blue background (hex 1B), and the right bracket '}' to reset
	to my normal white on blue (hex 17). By embedding them at the
	right places in my text, I can highlight a word or a line. Thus,
	this text:
		An example of {highlighting until the end of the line
		An example of a single {highlighted} word

	displays as
		An example of highlighting until the end of the line
		An example of a single highlighted word
	
	If you want to actually display one of these characters, rather
	than use it as a trigger, simply enter it twice. So, in my case,
	I had to key in '{{highlighted}}' above in order to get the
	curly brackets to display.

	(Hint:	If you want to see just what my original document looked
		like, make a copy of this readme.com, then use D2COLOR to
 		disable all trigger characters.)

	Up to 16 distinct trigger characters may be designated. You can
	also use non-text (or exended ASCII) characters as triggers,
	if your word processor or text editor can handle them. To learn
	how to specify any chosen characters as triggers, see 6.10 below. 

				- 6 -

	6.00  Using D2COLOR to set screen colors
	========================================

	I am now distributing D2COLOR.COM along with DOC2COM as a quick
	patch utility to set the screen colors for DOC2COM or any self-
	displaying .com files created by DOC2COM. D2COLOR is version-
	specific; that is, version 1.31 of D2COLOR will only work with
	DOC2COM 1.3 and 1.31 and self-display files created by DOC2COM
	1.3 and 1.31.

	Using D2COLOR is also simple. Use the following command:

			D2COLOR comfile

	where 'comfile' is DOC2COM.COM or the self-displaying .com
	file created by DOC2COM. You will be presented with a screen
	showing you all the various screen colors available, and their
	respective hexadecimal values. At the bottom you may pick from
	any of these hex values to set the display colors for the main
	body of text to be displayed, for the various pop-up windows,
	and for the text keyed in by the viewer in answer to prompts.
	
	Hit F1 to save any color changes, or the Escape key to quit
	without saving, or F2 to toggle to the trigger color screen.
	

	6.10  Setting special colors
	==============================

	If you embedded special 'trigger' characters in your document
	as outlined in section 5.10 above, you may specify what they
	are, and what screen colors they will trigger, on screen #2
	of D2COLOR. (Use F2 to toggle between the two screens.)
	
	In the upper positions, simply key in the special trigger
	characters. Immediately below each one, key in the hex values
	corresponding to the color desired.

	To key in a non-text trigger character (one that has no
	corresponding key on the keyboard), hold down tha 'Alt' key,
	and type the decimal value of that character using the number
	pad keys. For example, the Yen symbol '' ASCII character has
	a value of 157 decimal. So you hold down the 'Alt' key while
	typing '157' on the number pad, and there it is!  ASCII
	characters range in value from 0 to 255. Many DOS and other
	reference material can be consulted to find out which
	character is associated with each value.
	
	Do NOT use the carriage-return (value=13), line-feed (10),
	form-feed (12), tab (9), or escape key (27) as triggers, as
	they already have special significance to the program.

	----------------

	When experimenting with different color combinations, I
	recommend trying a variety of monitor types (e.g. color,
	monochrome, LCD), if you can, to view your color schemes
	on these various systems.
				- 7 -


	7.00  Possible problems
	=======================

	'Insufficient memory, or text file too big'
		DOS limits .com files to 64K or smaller. So the text file
		must be no larger than about 62000 or 63000 bytes, depending
		upon whether you used switches /0 or /1.  If it is smaller,
		and you still get this message, you may have a severe memory
		problem.  DOC2COM only needs from 2500 to 4000 bytes plus
		enough RAM for the text file.
	'Error: file not found'
		The input text file was not found. Check your spelling.
	'File error, AL = __h'
		AL = 03h - Path not found. Make sure the drive and path
			   specified really exist.
		AL = 04h - Too many files open. Another application didn't
			   correctly close a bunch of files. If you shelled
			   to DOS from within another program, go back and
			   quit that program to force its files to close.
			   If a previous program cancelled, it may have left
			   files open, too. In this case, you may have to
			   re-boot to free up these file handles.
		AL = 05h - Access denied. The .com file you tried to create
			   already exists as a read-only (and possibly
			   hidden) file.


				- 8 -

	8.00  Shareware Registration Guidelines
	=======================================

	The DOC2COM/D2COLOR system is protected from unauthorized use
	by U.S. copyright law. Anyone interested may evaluate these
	programs free of charge. I also encourage you to pass them
	along to others, especially to BBSs, distribution centers, and
	user groups. If you like them, you should register with me in
	the spirit of shareware by sending me $25.00 (check or money
	order payable to Gerald DePyper) in return for my efforts.
	
	As of October 1992, you may register with me through Compu-
	Serv Forum SWREG (GO SWREG). Look for Registration ID 308.
	
	A one-time registration of DOC2COM/D2COLOR entitles you to
	distribute royalty-free all self-display files that you create
	on an unlimited basis. You also get phone support plus free or
	reduced cost upgrades and/or bug fixes when they may occur.
	You may make as many copies as you need for backup or other
	purposes, as long as you limit DOC2COM to a single machine. For
	example, you may want to make several clones of DOC2COM, using
	D2COLOR to set screen colors differently on each.

	If you are a starving shareware author, I won't make you pay.
	But please register with me, and when you start making some
	money on your programs, let me make a little on mine, too.

	If you are a large business, would like to run DOC2COM on
	multiple machines, or if you would like some customized features,
	please contact me for a custom agreement.

	In any case, I need to know who you are (name, address, etc.),
	and where you got DOC2COM (name, address, of BBS, etc.), so
	that I can distribute upgrade notices and bug fixes.

	Please send information, money, questions and comments to:

		Gerald DePyper
		901 Argyle, #5A
		Chicago, IL 60640
		Phone:	312/907-8935
 		CompuServ ID: 71041,703

	P.S.(A Note From the Author)
	Please don't be a computer-holic. A computer is, after all, only
	a machine. Jesus is Lord. Keep everything else in perspective.
	Have fun!

