home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / ZSUS / Z3HELP-5.LBR / T.LBR / TEXT2DB.HZP / TEXT2DB.HLP
Text File  |  2000-06-30  |  8KB  |  167 lines
  1. ;
  2.                                 TEXT2DB.COM                                   
  3.  
  4.              Size (recs) CRC   Version    Author/Latest Issue      Disk
  5.                4k (31)   F0B6  1.0        Cameron Cotrill 7/89     Z3COM12
  6.  
  7.   1- Syntax/Options  2- Usage  3- Configuration                               
  8.  
  9.    TEXT2DB is  a  Z-system  tool  that  takes  most  of  the  drudgery  out of 
  10. generating MENU and HELP screens in Z80 assembly  language programs.   
  11.  
  12.    TEXT2DB reads bytes from  an ASCII text Input File (INFILE) and  sends them
  13. to an Output File (OUTFILE) reformatted  as data statements suitable for input
  14. to an assembler.  The most significant bit of incoming bytes is masked so that
  15. WordStar document files may be used as input.   Several control characters are
  16. intercepted  and  a  user-configurable  string  emitted  instead.   A  trigger 
  17. character may be used to  mark locations in  the text file  where  a label  is 
  18. required in the  output  file.   This  simplifies screen creation for programs 
  19. like ZCNFG.  Inspired by Joe Wright's ZTEXT vs 2.1.
  20. :1
  21.  
  22.   Syntax   TEXT2DB [DIR:]INFILE[.TXT] [OUTFILE[.DB]] [/o]
  23.  
  24.    Note: OUTFILE is always written to the same DIR: as INFILE.
  25.  
  26.  Options   Saaa - Set 3 character alpha prefix for synthetic labels.
  27.            Snnn - Set starting label number [0..255]
  28.            Saaannn - Set both alpha prefix and starting label number.
  29.  
  30.    The  option letter "S" is  required  but  is not  part  of the  first label 
  31. specification.   'A' may be a space, but will be changed to a period (.) since
  32. assemblers do not like spaces in labels.  The numeric portion is terminated by
  33. a space; 'n' or 'nn' will be filled with leading zeros in the synthetic label.
  34. :2
  35.  
  36.  Usage - 1/7 
  37.  
  38.    TEXT2DB is  a 'filter' type  program which  reads text from  an input file, 
  39. modifies it, and writes it to an output file.   The modification  in this case 
  40. is replacement of control characters with  appropriate mnemonics and insertion 
  41. of punctuation and assembly mnemonics  to create  lines of assembly code.  For 
  42. example, the input lines
  43.  
  44.     This is line one,
  45.     and this is line two.
  46.  
  47. would be converted to:
  48.  
  49.     db    tab,'This is line one,',CR,LF
  50.     db    tab,'and this is line two.',CR,LF
  51.  Usage - 2/7 
  52.  
  53.    With TEXT2DB, you use your text editor  (Document mode if it's WordStar) to 
  54. make the screen.   When it meets your  requirements,  just  run TEXT2DB on it.  
  55. The resulting  file of DB  statements can then  be  edited  into  the assembly 
  56. source  file (or  included  with  an  INCLUDE  statement,  depending  on  your 
  57. assembler).
  58.  
  59.    That is a simple case.   More tedious  yet  is  the  preparation of  a MENU 
  60. screen which includes fields that get  changed  while the program is  running.  
  61. In this case,  you will need  a label at each appropriate place in the list of 
  62. DB statements. In addition, the labeled DB statement must contain as its first
  63. data the field to be changed.  Again, you can do this manually.   All you have 
  64. to do is re-edit the file of DB statements. 
  65.  Usage - 3/7 
  66.  
  67. For example,
  68.  
  69.     db    tab,'This is line '
  70. label1:    db    'one,',CR,LF
  71.     db    tab,'and this is line '
  72. label2:    db    'two.',CR,LF
  73.  
  74. is equivalent to the original example.   Now, however,  the program can change 
  75. the contents of  the  data  fields 'one,' and 'two.' by  using  the  labels to 
  76. reference them.  TEXT2DB can also handle this labeling chore!   The menus used 
  77. with ZCNFG to alter TEXT2DB use this  strategy;  the screen data for  them was 
  78. generated with TEXT2DB.
  79.  Usage - 4/7 
  80.  
  81.    TEXT2DB must have some way of knowing  where to put the labels,  and how to 
  82. generate them so that they will not  conflict with  other labels  in the final 
  83. assembly source file you are working on.
  84.  
  85.    The location of labels is indicated in the input  text file by  a 'trigger'
  86. character which YOU include  in the text.   The default character used  is the
  87. accent character, "`" (60H). The original example, marked this way to indicate
  88. the location of labels is:
  89.  
  90.     This is line `one,
  91.     and this is line `two.
  92.  
  93.    The character used as a trigger is configurable, using ZCNFG.   If the ` is
  94. not suitable,  you may select another character that is  unlikely to be a part 
  95. of the input text.   If the character MUST  be included in  the  text (and not 
  96. treated as a trigger), simply type it twice.   `` will be recognized as a ` to 
  97. be included in the output  without causing  a label to be generated,  i.e. the 
  98. trigger character acts as its own 'escape' character.
  99.  Usage - 5/7 
  100.  
  101.    The labels inserted in the output file are called Synthetic Labels, and are
  102. generated by TEXT2DB from  an  initial  6  character  template.   The label is 
  103. initially Aaannn,  where the 'A' stands for an  Alphabetic character,  and the 
  104. 'aa' stands for 2 alpha-numeric characters and the 'nnn'  stands for 3 decimal 
  105. digits.   Each time a label is used, the 'nnn' part is incremented so that the 
  106. next label will  be  (systematically)  unique.   The  default  first  label is 
  107. SCR000:.   You may,  with ZCNFG,  change this default  as you  wish within the 
  108. above guidelines. 
  109.  Usage - 6/7 
  110.  
  111.    The length of the  DB statements in the output file is  controlled by three
  112. considerations:
  113.     1) Human readability - will it fit on your screen or printer
  114.        page, and don't fold lines in the middle of a word(!).
  115.     2) Assembler limitations - there is usually some limit to the
  116.        length of an input line for the assembler.
  117.     3) Synthetic labels - clearly, assembler syntax requires that
  118.        a label be on a new line. Thus, a break in the text must
  119.        occur where indicated by the trigger character.
  120.  
  121.    The Nominal line  length  (default is 50 characters) and  the  Maximum line
  122. length apply to the first  two considerations.   Both  are  configurable  with 
  123. ZCNFG.   The line is folded (terminated,  and a new line started) on the first
  124. space encountered beyond the nominal line length value.   If no  spaces occur, 
  125. then the line is unconditionally  folded when  it reaches the  Maximum length. 
  126. The Maximum line length is usually set to a larger value than the Nominal line
  127. length.   Its default value is  128 characters,  consistent with wide carriage 
  128. printers and most assemblers.
  129.  Usage - 7/7 
  130.  
  131.    One of the configuration options is  a choice  between  folding  the output
  132. line Before/After the next space.   This is a format option that is up to you.
  133. If After is chosen,  then the space will be at the END of the folded line;  if 
  134. Before then the space will be the first character in the next line of data.
  135.  
  136.    Before closing the output file,  one final  DB statement is added  to it by
  137. TEXT2DB - a statement whose data is a string terminator:
  138.  
  139.     DB    0
  140.  
  141.    The default argument is, as shown, binary zero.   This assumes your program 
  142. is written to process null-terminated strings.   This argument is configurable 
  143. with ZCNFG; a popular alternate (used with BDOS function 9) is '$'.  Note that
  144. the enclosing quotes must be included when  using ZCNFG to specify this value. 
  145. The configuration value you supply becomes  the  literal  argument  to  the DB 
  146. statement and must follow the syntax rules of your assembler.
  147. :3
  148.  
  149.  Configuration 
  150.  
  151.    You will probably try TEXT2DB without  bothering  with configuration.   OK,
  152. but THEN go  through  the  configuration!   You don't  have to change anything
  153. unless you want to, but the configuration will introduce you to all the things
  154. you CAN change easily;  and the help  screens associated with  each  menu give 
  155. further insight into what these parameters can do for you.  It's the next best
  156. thing to a formal ZCPR3 style HELP file.
  157.  
  158. Put the following files in the same directory.
  159.  
  160.     TEXT2DB.COM    (or whatever you renamed it to)
  161.     TEXT2DB.CFG    (DON'T change the name of this one!)
  162.     ZCNFG.COM
  163.  
  164. Then start the configuration session with:
  165.  
  166.     ZCNFG TEXT2DB    (or whatever you renamed it to)
  167.