;
                                TEXT2DB.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               4k (31)   F0B6  1.0        Cameron Cotrill 7/89     Z3COM12

  1- Syntax/Options  2- Usage  3- Configuration                               

   TEXT2DB is  a  Z-system  tool  that  takes  most  of  the  drudgery  out of 
generating MENU and HELP screens in Z80 assembly  language programs.   

   TEXT2DB reads bytes from  an ASCII text Input File (INFILE) and  sends them
to an Output File (OUTFILE) reformatted  as data statements suitable for input
to an assembler.  The most significant bit of incoming bytes is masked so that
WordStar document files may be used as input.   Several control characters are
intercepted  and  a  user-configurable  string  emitted  instead.   A  trigger 
character may be used to  mark locations in  the text file  where  a label  is 
required in the  output  file.   This  simplifies screen creation for programs 
like ZCNFG.  Inspired by Joe Wright's ZTEXT vs 2.1.
:1

  Syntax   TEXT2DB [DIR:]INFILE[.TXT] [OUTFILE[.DB]] [/o]

   Note: OUTFILE is always written to the same DIR: as INFILE.

 Options   Saaa - Set 3 character alpha prefix for synthetic labels.
           Snnn - Set starting label number [0..255]
           Saaannn - Set both alpha prefix and starting label number.

   The  option letter "S" is  required  but  is not  part  of the  first label 
specification.   'A' may be a space, but will be changed to a period (.) since
assemblers do not like spaces in labels.  The numeric portion is terminated by
a space; 'n' or 'nn' will be filled with leading zeros in the synthetic label.
:2

 Usage - 1/7 

   TEXT2DB is  a 'filter' type  program which  reads text from  an input file, 
modifies it, and writes it to an output file.   The modification  in this case 
is replacement of control characters with  appropriate mnemonics and insertion 
of punctuation and assembly mnemonics  to create  lines of assembly code.  For 
example, the input lines

	This is line one,
	and this is line two.

would be converted to:

	db	tab,'This is line one,',CR,LF
	db	tab,'and this is line two.',CR,LF
 Usage - 2/7 

   With TEXT2DB, you use your text editor  (Document mode if it's WordStar) to 
make the screen.   When it meets your  requirements,  just  run TEXT2DB on it.  
The resulting  file of DB  statements can then  be  edited  into  the assembly 
source  file (or  included  with  an  INCLUDE  statement,  depending  on  your 
assembler).

   That is a simple case.   More tedious  yet  is  the  preparation of  a MENU 
screen which includes fields that get  changed  while the program is  running.  
In this case,  you will need  a label at each appropriate place in the list of 
DB statements. In addition, the labeled DB statement must contain as its first
data the field to be changed.  Again, you can do this manually.   All you have 
to do is re-edit the file of DB statements. 
 Usage - 3/7 

For example,

	db	tab,'This is line '
label1:	db	'one,',CR,LF
	db	tab,'and this is line '
label2:	db	'two.',CR,LF

is equivalent to the original example.   Now, however,  the program can change 
the contents of  the  data  fields 'one,' and 'two.' by  using  the  labels to 
reference them.  TEXT2DB can also handle this labeling chore!   The menus used 
with ZCNFG to alter TEXT2DB use this  strategy;  the screen data for  them was 
generated with TEXT2DB.
 Usage - 4/7 

   TEXT2DB must have some way of knowing  where to put the labels,  and how to 
generate them so that they will not  conflict with  other labels  in the final 
assembly source file you are working on.

   The location of labels is indicated in the input  text file by  a 'trigger'
character which YOU include  in the text.   The default character used  is the
accent character, "`" (60H). The original example, marked this way to indicate
the location of labels is:

	This is line `one,
	and this is line `two.

   The character used as a trigger is configurable, using ZCNFG.   If the ` is
not suitable,  you may select another character that is  unlikely to be a part 
of the input text.   If the character MUST  be included in  the  text (and not 
treated as a trigger), simply type it twice.   `` will be recognized as a ` to 
be included in the output  without causing  a label to be generated,  i.e. the 
trigger character acts as its own 'escape' character.
 Usage - 5/7 

   The labels inserted in the output file are called Synthetic Labels, and are
generated by TEXT2DB from  an  initial  6  character  template.   The label is 
initially Aaannn,  where the 'A' stands for an  Alphabetic character,  and the 
'aa' stands for 2 alpha-numeric characters and the 'nnn'  stands for 3 decimal 
digits.   Each time a label is used, the 'nnn' part is incremented so that the 
next label will  be  (systematically)  unique.   The  default  first  label is 
SCR000:.   You may,  with ZCNFG,  change this default  as you  wish within the 
above guidelines. 
 Usage - 6/7 

   The length of the  DB statements in the output file is  controlled by three
considerations:
	1) Human readability - will it fit on your screen or printer
	   page, and don't fold lines in the middle of a word(!).
	2) Assembler limitations - there is usually some limit to the
	   length of an input line for the assembler.
	3) Synthetic labels - clearly, assembler syntax requires that
	   a label be on a new line. Thus, a break in the text must
	   occur where indicated by the trigger character.

   The Nominal line  length  (default is 50 characters) and  the  Maximum line
length apply to the first  two considerations.   Both  are  configurable  with 
ZCNFG.   The line is folded (terminated,  and a new line started) on the first
space encountered beyond the nominal line length value.   If no  spaces occur, 
then the line is unconditionally  folded when  it reaches the  Maximum length. 
The Maximum line length is usually set to a larger value than the Nominal line
length.   Its default value is  128 characters,  consistent with wide carriage 
printers and most assemblers.
 Usage - 7/7 

   One of the configuration options is  a choice  between  folding  the output
line Before/After the next space.   This is a format option that is up to you.
If After is chosen,  then the space will be at the END of the folded line;  if 
Before then the space will be the first character in the next line of data.

   Before closing the output file,  one final  DB statement is added  to it by
TEXT2DB - a statement whose data is a string terminator:

	DB	0

   The default argument is, as shown, binary zero.   This assumes your program 
is written to process null-terminated strings.   This argument is configurable 
with ZCNFG; a popular alternate (used with BDOS function 9) is '$'.  Note that
the enclosing quotes must be included when  using ZCNFG to specify this value. 
The configuration value you supply becomes  the  literal  argument  to  the DB 
statement and must follow the syntax rules of your assembler.
:3

 Configuration 

   You will probably try TEXT2DB without  bothering  with configuration.   OK,
but THEN go  through  the  configuration!   You don't  have to change anything
unless you want to, but the configuration will introduce you to all the things
you CAN change easily;  and the help  screens associated with  each  menu give 
further insight into what these parameters can do for you.  It's the next best
thing to a formal ZCPR3 style HELP file.

Put the following files in the same directory.

	TEXT2DB.COM	(or whatever you renamed it to)
	TEXT2DB.CFG	(DON'T change the name of this one!)
	ZCNFG.COM

Then start the configuration session with:

	ZCNFG TEXT2DB	(or whatever you renamed it to)
