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 / UTILITYS / XTP.ARC / XTP.DOC < prev   
Text File  |  1990-07-21  |  10KB  |  229 lines
  1.                                 XTP Version 1.0
  2.                                 ===============
  3.                          Copyright (c) H.C.Chin 11/1986
  4.                               All rights reserved.
  5.  
  6.       Though this utility may be freely distributed in the public domain,
  7.           no commercial use/sale is permitted under any circumstances.
  8.  
  9.  
  10.  
  11. Purpose of XTP:
  12. ---------------
  13.  
  14.         XTP is a Turbo Pascal source program cross reference utility inspired
  15. both by a similar utility for the C language XC and the source code listing
  16. utility LISTT. XC can be found in the public domain (somewhere!) and LISTT is
  17. distributed in Borland International's Turbo Tutor package.
  18.  
  19.     This explains the similarities between XTP and XC, LISTT.
  20.  
  21.  
  22.  
  23. Hardware/software requirements:
  24. -------------------------------
  25.  
  26.     Any CP/M 2.2 (CP/M 3?) computer with Z-80 processor and 64K minimum of
  27. memory. A disk drive or two is helpful! Currently the printer initialisation
  28. (for redirection to printer) is set for Elite font for Epson compatible type
  29. printers (96 chars per line), and 66 lines per page, though can be patched
  30. easily (see patch information below).
  31.  
  32.  
  33.  
  34. Usage:
  35. ------
  36.  
  37.     Only XTP.COM is required. To run, simply type 'xtp' at CP/M command
  38. level and a brief description will be displayed, including all command line
  39. options and what they do. The options are mainly to change default setting of
  40. the utility.
  41.  
  42.     Usage: xtp [d:]iufn [-iklpx] [-o [d:][oufn]]
  43.     
  44.         where iufn is unambiguous input file name
  45.                     oufn is unambiguous output file name
  46.      
  47.     When XTP is running, if output is redirect elsewhere (other than vdu) or
  48. suppresed, then an on-screen status report is generated. In file inclusion mode,
  49. two number will be updated dynamically on-screen. The first being the global
  50. (total) line count, while the second being the line count of the indicated
  51. current input file. If file inclusion is off then only one number will appear
  52. on-screen. The on-screen status report also indicates the different stages of
  53. XTP, like parsing, sorting, etc ...
  54.  
  55.     The numbers in the x-ref tables next to each symbol are the source
  56. line number in which the symbol occurs. In file inclusion mode, these are the
  57. global line count.
  58.  
  59.  
  60.  
  61. Command line options and defaults:
  62. ----------------------------------
  63.  
  64. d:      Where 'd' is the drive code on which the input file (main source file)
  65.         is to be found.  
  66.         Default drive is the currently logged drive.
  67.  
  68. -i      The 'i' option if chosen turns on the file inclusion facility as in
  69.         Turbo Pascal.
  70.         Default is off (no file inclusion).
  71.         NB: Include file(s) is/are assumed to be on the currently logged drive
  72.             unless otherwise defined in the file inclusion directive itself (see
  73.             Turbo Pascal manual for file inclusion directive).  If the include
  74.             file(s) is/are not found on the currently logged drive or that
  75.             specified in the inclusion directive, the drive on which the main
  76.             source file is found is searched, in this case drive 'd' if
  77.             specified in the command line.
  78.  
  79. -k      The 'k' option when chosen enables the cross reference of keywords in
  80.         Turbo Pascal ('begin', 'end' etc). This option speeds up the process of
  81.         parsing as no work is done in searching/matching keywords, though it
  82.         clobbers up the cross-reference-table. Useful when debugging programs
  83.         especially matching begin-ends.  
  84.         Default is off.
  85.  
  86. -l      The 'l' option enables the generation of program source listing only,
  87.         no cross-reference-table is generated. This is where XTP doubles as a
  88.         source listing utility, with the extra features of pagination, line
  89.         numbering and file inclusion (ala LISTT).  
  90.         Default is off.
  91.  
  92. -o      The 'o' option redirects output from XTP to either a disk file or the
  93.         printer. Output file name is optional, when not supplied redirection to
  94.         disk file is assumed, the input file name is used with a default file
  95.         type of .XRF. Two file names have special meanings: 'CON:' will use the
  96.         system console as the output (normally the vdu) while 'LST:' will
  97.         redirect output to the printer. See Turbo Pascal for other logical
  98.         devices that might work.  
  99.         Default output file name is "'input-file-name'.XRF".
  100.  
  101. -p      The 'p' option will redirect output to the printer, ie. output file name
  102.         of 'LST:'.
  103.         Default is off.
  104.  
  105. -x      The 'x' option enables the generation of cross-reference-table only, no
  106.         listing of the source program/include file(s) is/are generated.
  107.         Default is off.
  108.  
  109.  
  110. NB:     Due to the way in which the command line parsing is implemented, there
  111. ===     are various traps and strange behaviours to be avoided.
  112.  
  113.     1) The 'l' and 'x' options must not be chosen at the same time, as they
  114.            both work independently - disabling each other! If both chosen then
  115.            no output is generated!
  116.  
  117.     2) The 'o' and 'p' options must not be chosen at the same time, as they
  118.            operate on the same variable - output file name. If both enabled then
  119.            the output file name will be determined by the options that is chosen
  120.            last.
  121.            eg. 'xtp xtp -op' will have output file name 'LST:'
  122.                'xtp xtp -po' will have output file name 'XTP.XRF'
  123.                'xtp xtp -po dummy.txt' will have output file name 'DUMMY.TXT'
  124.                etc ...    
  125.  
  126.         3) The 'o' option must not be followed immediate by another option
  127.            separated by space, otherwise that option will be treated as an
  128.            output file name. A good practice is to invoke the 'o' option as the
  129.            last option.
  130.            eg. 'xtp xtp -o -l' will have output file name '-L.XRF'
  131.                'xtp xtp -l -o' will have output file name 'XTP.XRF' (OK)
  132.  
  133.         More ..... ??
  134.  
  135.  
  136. NB:     Options can be bump together.
  137. ===     eg. 'xtp xtp -i -k -o' is the same as 'xtp xtp -iko'
  138.             etc ...
  139.  
  140.  
  141.  
  142. Patch information:
  143. ------------------
  144.  
  145.     A limited default settings can be patched by user. They are outlined
  146. below in the format:
  147.  
  148.     name: hex address in file XTP.COM - default values
  149.     ----  ---------------------------   --------------
  150.      |       |                   |
  151. max_page_length: H2100 - 3C 00  <-------------------
  152.         Mainly to suit various printer paper sizes, currently set for 11" paper,
  153.         60 (H3C) source lines per page (minus 6 lines for title and footer).
  154.  
  155. max_page_width: H2102 - 60 00
  156.         Mainly for centering of title and footer to suit the printer font
  157.         selected, currently set at 96 (H60) character per line for Epson
  158.         compatible Elite font.
  159.  
  160. printer_init_string: H2104 - 08 1B 40 1B 4D 00 00 00 00
  161.         Printer initialise string to be send to printer, currently set for Epson
  162.         compatible Elite font - "ESC @ ESC M".
  163.         NB: a maximum of 8 bytes can be send (as indicated by byte H2104 - 08),
  164.             important - do not change this byte! as this is the string length
  165.             indicator. The NULLs (00) that follow are simply paddings.
  166.  
  167. i_option: H210D - 00
  168.         Default setting for 'i' option (file inclusion), currently set to false
  169.         - no file inclusion. Set to H01 to enable default file inclusion.
  170.  
  171. k_option: H210E - 00
  172.         Default setting for 'k' option (x-ref of keywords), currently set to
  173.         false - no x-ref of keywords. Set to H01 to enable default x-ref of
  174.         keywords.
  175.  
  176. l_option: H210F - 00
  177.         Default setting for 'l' option (source listing only), currently set to
  178.         false. Set to H01 to turn XTP into a source file lister utility only.
  179.  
  180. x_option: H2110 - 00
  181.         Default setting for 'x' option (x-ref table only), currently set to
  182.         false. Set to H01 to make XTP generates x-ref table only.
  183.  
  184.  
  185. NB:     As mentioned before, the 'l' and 'x' option must not both be set to 01,
  186. ===      as this will suppress the output totally!
  187.  
  188.         The hex addresses given above all have an offset of H0100 added to them
  189.         (for .COM file), so H2100 actually is H2000 if the first byte of the
  190.         file is taken to be H0000. etc ..
  191.  
  192.  
  193.  
  194. Known bugs and limitations:
  195. ---------------------------
  196.  
  197. 1)      Output formatting (especially to printer) from XTP relies on the input
  198.         source file being well behaved - meaning each line must fit into the
  199.         page width - as the page count and hence formatting relies on the line
  200.         count. Also, lines longer than 128 characters will be truncated.
  201.  
  202. 2)      As XTP is quite a memory intensive program - due to the use of dynamic
  203.         link list, therefore larger source may not fit into the 64K limits. In
  204.         this case, turned off file inclusion and processing each include file
  205.         separately.  
  206.         Alternatively, if a convention of only using the primary commenting
  207.         directive ('{' and '}') generally, then the secondary commenting
  208.         directive ('(*' and '*)') can be used to optionally comment out file
  209.         inclusion directives in the main souce file. This is a good practice
  210.         since it also makes commenting out part of code with embedded comments
  211.         easier.
  212.  
  213. More ..... ??
  214.  
  215.  
  216.  
  217.     This utility is hereby donated to the public domain. Have fun!
  218.  
  219.                             H.C.Chin
  220.                             Sydney,
  221.                             AUSTRALIA.
  222.                             26/2/1987
  223.  
  224.  
  225. Turbo Pascal, Turbo Tutor are trademarks of Borland International, Inc.
  226. CP/M is a registered trademark of Digital Research, Inc.
  227. Z-80 is a trademark of Zilog Corp.
  228. Epson is a trademark of Epson Corp.
  229.