home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / simtel / sigm / vols000 / vol081 / disk.doc < prev    next >
Text File  |  1984-04-29  |  11KB  |  248 lines
  1.  
  2.  
  3.  
  4.  
  5.      
  6.  
  7.  
  8.  
  9.      Disk Information
  10.  
  11.           This disk contains five Pascal/Z programs: two general
  12.      purpose utilities: PRINT and FF; two Pascal development aids: PP
  13.      and XREF; and a text processor: TP.  The assembly language and
  14.      other Pascal/Z files on the disk contain procedures used by
  15.      these programs.  The file that you are now reading exists in two
  16.      forms on the disk: DISK.DOC is obtained by running TP with
  17.      DISK.TEX as input.
  18.  
  19.           These programs have been donated to the Z User's Group.
  20.      They are guaranteed only to do what Iwant them to do on my
  21.      system.  Use them, alter them, and give them away to friends,
  22.      but please do not attempt to market them.  If they were saleable
  23.      products, I would have sold them.  If you make substantial
  24.      improvements to them or discover substantial bugs in them,
  25.      please let me know.
  26.  
  27.  
  28.      General Description
  29.  
  30.           These notes are intended to help you get the programs
  31.      running.  When you have got TP working, you should be able to
  32.      obtain specifications for them by processing SYSTEM.TEX.
  33.  
  34.           Everybody writes their own print utility; mine, PRINT, is
  35.      written for a specific printer, the I.D.S. 460G "Paper Tiger",
  36.      but the printer-dependent code is localized (and documented!) to
  37.      simplify changes.  PRINT will not send and strange codes to the
  38.      printer unless you select fancy options, such as boldface
  39.      printing or proportional spacing.
  40.  
  41.           FF is also written specifically for the I.D.S. 460; it
  42.      transmits all the codes necessary to straighten the printer out
  43.      when it has got into a muddle, and it also sends as many
  44.      form-feeds as you want.
  45.  
  46.           PP is a Pascal/Z pretty-printer.  It accepts a Pascal
  47.      source program (a .PAS file, not a .LST file) and produces a                                  ___
  48.      .PPP file containing an equivalent program with improved layout.
  49.      The idea is that you work with a .PAS file and generate a .PPP
  50.      file only when you want a fancy listing.  The .PAS files on this
  51.      disk are all squashed up and unreadable, but you can use PP to
  52.      massage them into a more presentable form.
  53.  
  54.           XREF is a cross-reference generator that reads the output
  55.      of PP and produces a .XRT file containing a cross-reference
  56.      table of user identifiers.  (It is really an index of user
  57.      identifiers, but I am not going to try and change accepted
  58.      terminology.)  The cross-reference table includes identifiers
  59.      that start with a lower case letter, are not part of a quoted
  60.      string, and are not inside a comment of the form { ... }.  I
  61.  
  62.  
  63.  
  64.      Disk Information                                                    Page 1
  65.  
  66.      
  67.  
  68.  
  69.  
  70.      write my programs entirely in lower case and PP converts Pascal
  71.      reserved words to upper case, and so this arrangement suits me
  72.      very well; if you don't like it, it is not difficult to modify
  73.      XREF to your own requirements.
  74.  
  75.           The submit file PRETTY.SUB shows how PP and XREF are used
  76.      together.
  77.  
  78.           If you use one of the flashy new "what you see is all
  79.      you've got" style text processors, you will find that TP is
  80.      something of a dinosaur.  I wrote it because none of the text
  81.      processors available at a reasonable price satisfied my somewhat
  82.      eccentric requirements.  (I use a small set of relatively
  83.      high-level commands suited to my work but I do not require high
  84.      quality final output, because I usually send the material to
  85.      someone with better typesetting equipment than mine.  TP does
  86.      several things automatically, including section numbering and
  87.      cross-referencing, and this makes reorganizing text
  88.      straightforward.  It does not do certain "basic" things, such as
  89.      justify text, because these are not part of my requirement.)  TP
  90.      is not yet complete, but it is still largely device independent.
  91.      The only assumption that it makes is that the printer can handle
  92.      a carriage-return that is not followed by a line-feed.  The next
  93.      revision will probably contain code for special character sets,
  94.      etc, which will be device dependent, so now seems a good time to
  95.      give it to ZUG.  The best way to learn about TP is to use it to
  96.      format the file SYSTEM.TEX, and then compare SYSTEM.TEX with
  97.      SYSTEM.DOC.  If you like TP and want to be informed of future
  98.      developments, let me know.
  99.  
  100.  
  101.      Implementation Notes
  102.  
  103.           The disk contains a .SUB file for each Pascal program.
  104.      Note that all of the programs except FF require CONSTS.PAS,
  105.      TYPES.PAS, GETFILES.PAS, and PROCS.PAS during compilation, and
  106.      that PRINT, XREF, and TP also require assembly language
  107.      subroutines.  The following suggestions may help to get you
  108.      started.
  109.  
  110.           (1)   Compile the programs by executing FF.SUB, PRINT.SUB,
  111.                 PP.SUB, XREF.SUB, and TP.SUB.  The .SUB files assume
  112.                 that everything happens on the current system disk,
  113.                 which must of course contain the compiler, assembler,
  114.                 linker, MAIN.SRC, etc.
  115.  
  116.           (2)   Use PRETTY.SUB to obtain a pretty-printed listing of
  117.                 each program.  This procedure requires the name of a
  118.                 Pascal source file as a parameter.  For example:
  119.  
  120.                           SUBMIT PRETTY FF
  121.  
  122.  
  123.  
  124.  
  125.      Disk Information                                                    Page 2
  126.  
  127.      
  128.  
  129.  
  130.  
  131.                 PRETTY uses PRINT to print a listing of the
  132.                 pretty-printed program and its cross-reference table.
  133.                 By default, PRINT assumes 11" paper and 6 lines/inch;
  134.                 it prints 60 lines of text on each page, printing
  135.                 page headings and using form-feed characters for
  136.                 pagination.  It does not truncate or wrap long lines.
  137.  
  138.           (3)   Test TP by formatting this file with it.  The command
  139.  
  140.                           TP DISK
  141.  
  142.                 should create a file DISK.DOC identical to the file
  143.                 DISK.DOC on this disk.  If it does, use TP to format
  144.                 the documentation contained in the files SYSTEM.TEX,
  145.                 SYSUT.TEX, and SYSTP.TEX.  The command
  146.  
  147.                           TP SYSTEM
  148.  
  149.                 does this, creating the formatted manual SYSTEM.DOC,
  150.                 the table of contents file SYSTEM.CON, and the file
  151.                 of cross-references SYSTEM.REF, which is of no great
  152.                 interest to the user.
  153.  
  154.           Computers being what they are, you will probably get stuck
  155.      at some point in the proceedings.  Unfortunately, I cannot
  156.      predict what will go wrong, but here are some possibly alarming
  157.      symptoms.
  158.  
  159.           (1)   All of the programs work with Version 4.0 of the
  160.                 compiler and I believe that all except PP also work
  161.                 with Version 3.0.  The problems with PP under Version
  162.                 3.0 concern passing one-byte integers by reference.
  163.  
  164.           (2)   Some of the operations are quite slow.  My system
  165.                 requires about 15 minutes to compile TP.
  166.                 Furthermore, TP will require at least 7 minutes to
  167.                 process SYSTEM -- it runs at about 1200 words per
  168.                 minute under Cache BIOS with floppy disks.
  169.  
  170.           (3)   Large intermediate files will be created.  Check the
  171.                 amount of free disk space before each compilation,
  172.                 especially before when compiling TP.  The submit
  173.                 procedures delete files as soon as they are no longer
  174.                 required.
  175.  
  176.           (4)   I have had no memory problems running Cache BIOS in
  177.                 128K.  I do not know whether TP can be compiled on a
  178.                 48K machine.  It should run on a 48K machine, but                                        ___
  179.                 there will be less space for cross-references and
  180.                 "keeps".  The simplest way to reduce the memory
  181.                 requirements of TP would be to split it in two: part
  182.                 1 would initialize the global tables and chain to
  183.  
  184.  
  185.  
  186.      Disk Information                                                    Page 3
  187.  
  188.      
  189.  
  190.  
  191.  
  192.                 part 2 which would do the work.
  193.  
  194.           (5)   Some of the cross-references in SYSTEM.DOC will be
  195.                 unsatisfied (there will be statements like "see
  196.                 Section 0.0.0").  There are two reasons for this: one
  197.                 is that TP requires two passes to satisfy forward
  198.                 references, and the other is that there are
  199.                 references to sections of the manual that are not on
  200.                 this disk.
  201.  
  202.           (6)   TP assumes 12 characters/inch by default.  Each line
  203.                 is preceded by 6 blanks (0.5"), and contains at most
  204.                 78 characters (6.5") of text.  Thus the text fits
  205.                 onto 8.5"x11" paper with 1" margins.  If your printer
  206.                 prints 10 characters/inch and you use 8.5" paper, the
  207.                 lines will be too long.  (They will also be too long
  208.                 to display on an 80-column screen.)  You can tell TP
  209.                 to print shorter lines by inserting the command
  210.  
  211.                            \HL 5 65
  212.  
  213.                 at the front of the file: look at DISK.TEX to see
  214.                 where it goes.
  215.  
  216.           (7)   PRINT has a "T" option for printing .DOC files
  217.                 produced by TP.  You can say, for example:
  218.  
  219.                           PRINT SYSTEM.DOC T1,5
  220.  
  221.                 This is supposed to print the first 5 pages of
  222.                 SYSTEM.DOC.  Unfortunately this option does not work
  223.                 on my system.  When the "T" option is selected, the
  224.                 printer seems to ignore the ETX/ACK protocol.
  225.                 Please let me know if you manage to fix the bug.
  226.                 In the meantime, use
  227.  
  228.                           PIP LST:=SYSTEM.DOC
  229.  
  230.                 instead.
  231.  
  232.      Good luck!
  233.  
  234.  
  235.      
  236.                                              Peter Grogono
  237.                                              Metonymy Productions
  238.                                              4125 Beaconsfield Avenue
  239.                                              Montreal, Quebec H4A 2H4
  240.      
  241.                        
  242.      
  243.  
  244.  
  245.  
  246.  
  247.      Disk Information                                                    Page 4
  248.