;
                                TEXT2DB.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               4k (32)   8157  1.3        Al Hawley 10/91          Z3COM21

  1- Syntax/Options  2- Usage  3- Configuration  4- Notes                     

   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   [DIR:]INFILE[.TXT] [OUTFILE[.DB]] [/o...]

 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.
           /Tx       Set 'x' as the Trigger character for a label

	OUTFILE is always written to the same DIR: as INFILE.
 Command-Line Options - 1/6 

   There are two command line options  - /SAaannn and /Tx.  For the /S option,
the option letter (S) is required but is not part of the first label specific-
ation.   Both parts are optional;  /SAaa  and  /Snnn  are quite acceptable and
assign the Alpha and numeric portions of the first label.  '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' are quite
acceptable and will be filled with leading zeros in the synthetic label.

   The  /T  option  specifies a character  'x'  that will mark the location of
fields to be referenced by synthetic labels.   When this  option is present in
the command line it supersedes the default character selected during configur-
ation.
 Command-Line Options - 2/6 

OPTIONS EMBEDDED IN THE INPUT FILE (new in V1.1)

   Lines in INFILE that start with a period  (no leading white space!) are not
subject to the TEXT2DB process.   Instead,  they  are  treated  as  comment or
control lines. Two special characters are recognized after the initial period,
'/' and ';'.   The '/' marks an option to be processed, and a ';' as the first
character of a token marks the rest of the line as a  comment to be  passed on
to OUTFILE. For example, the first two lines in T2DBHELP.TXT are:

.This is an INFILE for the TEXT2DB Help screen.
./SHLP001 /T~ -first label and trigger character for this file

   The first line is a comment within the input file  which simply serves as a
note from the author.   This line is totally ignored by  TEXT2DB;  it produces
nothing in the output file.
 Command-Line Options - 3/6 

   The second line contains two options which we  recognize:  they  could have
been included on the command line which invokes TEXT2DB,  and their  effect is
the same.   These embedded options supersede any  given on the command line or
defaults established by ZCNFG.   The explanatory text that follows the options
is ignored as an internal comment.   These two options, when embedded this way
lend  portability to TXT files intended as  input  to TEXT2DB.   Regardless of
configuration defaults,  TEXT2DB will  correctly  process such a file with the
simplest possible command line.

   Later, there is another control line:

.;Current program name goes into next labeled field

   The  ';' is interpreted as the start of a  REAL  comment to be passed on to
the output file. The remainder of the line (including the ';') will be present
on a line by itself in OUTFILE.  This option has no counterpart on the command
line because ZCPR would interpret the ';' as the end of the command.
 Command-Line Options - 4/6 

   Two other options have no counterparts on the command line:

   /E  Inserts a ' DB 0' line at the current position in OUTFILE.
   /I  Inserts the balance of the line LITERALLY in OUTFILE.

   A little reflection will reveal that the  /I  option  can  perform the same
jobs done by the ';' and /E.

   /I;Current program name goes into next labeled field
and
   /I	DB	0

are perfectly acceptable  alternatives to the previous comment line and the /E
option. There is one difference.   The /E will output the currently configured
equivalents for 'DB' and the data which ends a string  (like "'$'"  instead of
0). 

   The /I option gives you the  ability to  include  assembly  language source
statements in the output file, albeit a little awkwardly. 
 Command-Line Options - 5/6 

   Such a sequence might be:

./I	DB	0		;Terminate previous string
./I	CALL	FLGTST		;sets flag for SPSTR
./I	CALL	SPSTR		;Switched inline print from SYSLIB
.DB statements used by SPSTR follow

   Such a sequence is actually used in  one  version  of  LUX  to  display the
portions of the help screen that are important to the current working environ-
ment, suppressing irrelevant items.  Note that the first line above could have
been "./E ", and the first two lines could be shortened to:

./E/I	CALL	FLGTST		;sets flag for SPSTR

    Once a /I or ';' has been encountered, the balance of the line may contain
arbitrary text including strings that otherwise would be options.  Interpreta-
tion of any special characters is turned off for the remainder of the line. 
 Command-Line Options - 6/6 

   There is another difference between command line options  (S and T) and the
same ones in an embedded control line.   Characters in  the  command  line are
always capitalized by the CCP. Within a control line, however, case is signif-
icant for all but the option selector character itself.  Synthetic labels will
contain lower case  letters if  that's  what  you  specifiy in  the aaa field.
Likewise,  the case of the trigger character may be UC or LC when specified in
a control line but only UC  (for  alpha  characters)  when  specified from the
command line.
:2
 Usage - 1/5 

   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/5 

   Why would one want to do something so  simple?   The answer,  of course, is
that you wouldn't bother with a special program for  a case this simple.   But
suppose you wish to make a series of formatted  HELP  screens  (or even one!).
You will spend hours getting the spacing and line  lengths  right  by re-doing
(and reassembling) the DB statements.   With  TEXT2DB,  you just 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  state-
ments 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/5 

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.  Likewise,  the on-line HELP screen in TXT2DB was made 
this way.  The text file processed by TXT2DB is T2DBHELP.TXT in TXT2DB11.LBR.
 Usage - 4/5 

   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.   Note that, since the
trigger character is normally not  sent to the  outfile,  it  interferes  with
'what you see is what you get'.  For this reason, it is best to get the format
right first, then insert the trigger characters as needed.
 Usage - 5/5 

   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. 
:3
 Configuration Options - 1/2 

   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.
 Configuration Options - 2/2 

   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.
 Configuration - 1/2 

   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)
	TEXT2DB13.CFG	(DON'T change the name of this one!)
	ZCNFG.COM       (Use only Version 2.1 or higher)

Then start the configuration session with:

	ZCNFG TEXT2DB	(or whatever you renamed it to)
 Configuration - 2/2 
 
   Obviously, ZCNFG need only be on your ZCPR search  path.   The CFG file may
also be in a remote directory;  just add the argument  DIR:TEXT2DB to the last
command line and let ZCNFG  find it.   The full syntax of a ZCNFG command line 
is given in ZCNFG's help screen and documentation.
:4
 TEXT2DB Notes - 1/3 

   a. Vs 1.3 updates (10/15/91, Al Hawley):
      - Changed space filled strings in configuration block to null terminated
        strings in a fixed size field, and added  a mnemonic for Form Feed.  A
        new CFG file was  generated  which  uses  the  two  new  functions  in
        ZCNFG21.  The change to null terminated strings results in deletion of
        a block of code that  performed  that function at run time.   FormFeed
        now emits a 'DB FF' statement in the  output  file.   This  version is
        configurable only with ZCNFG21.   Earlier  versions will give an error
        message for the new functions.
      - Fixed a bug that prevented specifying  a numeric part of the synthetic
        label as 000 from the command line.   Changed the numeric counter from
        a byte to a word,  allowing  synthetic labels to have a  numeric  part
        from 000 to 999.  If labels ever get incremented that high,  they will
        wrap back to zero.   1000 synthetic labels  should  meet any realistic
        requirement!
 TEXT2DB Notes - 2/3 
    
   b. Vs 1.2 updates (10/6/91, Al Hawley - unreleased beta version):
      - Fixed a bug pointed out by Howard Goldstein  -  sometimes the  program
        aborts with a  BDOS/ZSDOS  non-existing  drive error.   This  one  was
        present in version 1.0,  waiting patiently for the right conditions to
        arise. 
      - Bumped the version to 1.2.   Although there are no  changes to the CFG
        file its name was  changed,  reflecting the  new  version  number,  to
        TXT2DB12.CFG.
 TEXT2DB Notes - 3/3 

   c. Vs 1.1 updates (10/2/91, Al Hawley):
      - Added new options:
	/Tx  to set the trigger character for synthetic labels
	/I   to send balance of line to output file literally
	/E   to send a string termination statement to output file
	;    as first character of a token, sends balance of the
	     line to output, including the ;. (a comment line for 
	     the assembler)
        Only the  /T  option operates from the  command line.  The  others are
        recognized only in a line starting with  '.'  AND  at the  start  of a
        token.   A token is a string of  non-space  characters surrounded with
        white space.   For this  parser,  white  space is not  required before
        a '/' option designator but is accepted.
      - Revised .DOC file and HELP screen to reflect the new options.
      - Made the help  screen  'smart' to give an  example  of the use of some 
        of the new capabilities.
      - Added the  Version number to the  CFG  file  name so that future  mods
        will demand a new  CFG file.   Actually there is no change in the  CFG
        file itself from the release version.  Just the name.
      - Bumped the version number to V1.1 and released for BETA test.
