home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 19 Printer / 19-Printer.zip / cprint1.zip / CPRINT.DOC next >
Text File  |  1989-08-02  |  14KB  |  353 lines
  1.     CPRINT.EXE IS A PROGRAM SOURCE CODE AND ASCII FILE PRINTING UTILITY.
  2.  
  3.     CPRINT can INTELLIGENTLY handle a print request for MULTIPLE files such
  4.     that  the  files  are CORRECTLY printed on BOTH sides (optional) of the
  5.     paper.  This is great for printing hardcopy  of  large  documents  (eg.
  6.     PROCOMM.DOC)  or  many  small  files  (eg.  source  code  for  your 200
  7.     function  C  lib).  The resulting output is arranged just like a book -
  8.     page 1 & 2 of the first file are on opposite sides of the same piece of
  9.     paper.
  10.  
  11.     CPRINT will page break when the  default  line  count  is  reached  (/L
  12.     switch)  or when it encounters an ASCII form feed in the file.  You can
  13.     add a top margin (great for EPSON printers).   You  can  print  or  not
  14.     print  the files date & time info as a page header.  You can add a left
  15.     margin to all lines of the file (allows 3 hole punch  without  punching
  16.     through text).
  17.  
  18.  
  19.     File List
  20.     ---------
  21.  
  22.     The distribution files are:
  23.  
  24.       CPRINT.DOC  - this documentation file.
  25.  
  26.       CPRINT.EXE  - the executable program.
  27.  
  28.  
  29.     Program Usage
  30.     -------------
  31.  
  32.       cprint  [filespec] [switches]
  33.  
  34.  
  35.     OPTIONAL COMMAND LINE SWITCHES: ( where "xx" equals a number)
  36.  
  37.       /Ixxx[,xxx,xxx....]  decimal printer initialization code(s).
  38.               (ex: /I027,013,070   -or-   /I027,064   etc.)
  39.  
  40.       /Mxx    defines left margin to add to every print line (default=0).
  41.  
  42.       /Wxx    defines total maximum line width (default=80).
  43.  
  44.       /Cxx    defines number of copies to print (default=1).
  45.  
  46.       /H      do NOT print file's date/time info as page header.
  47.               useful for printing pre-formatted documents.
  48.  
  49.       /Txx    defines top margin to add (default=0).
  50.  
  51.       /Lxx    defines maximum print lines per page in addition to
  52.               the top margin (default=54  (66 if /H used)).
  53.  
  54.       /Ofile  send output to a file rather than the printer
  55.               (Ex:  /Ostuff will send the output to the file STUFF)
  56.  
  57.       /1      print pages which go on front side of paper  (see NOTES).
  58.  
  59.       /2      print pages which go on back side of paper  (see NOTES).
  60.  
  61.       /S      split such that each file is on a unique set of pages.
  62.               (do NOT print the first page of a new file on the back
  63.                of the last page of the previous file.)
  64.  
  65.  
  66.      NOTES:
  67.  
  68.        Filespec may contain pathnames & wildcards.
  69.  
  70.        To print on both sides of paper:
  71.           print with /1, turn the paper over, re-print with /2.
  72.  
  73.        /S only applies to /1 and /2.
  74.  
  75.        /C is disabled by /1 and /2.
  76.  
  77.        /O output is appended to the file if it already exists, otherwise
  78.           the file is created.
  79.  
  80.  
  81.     WARNING:
  82.     --------
  83.  
  84.     If the /O option is used to re-route the  output  to  a  file  for  the
  85.     purpose  of  editing  or  viewing  the  output  prior to printing, some
  86.     cautions are in order.  Because of the way  some  printers  handle  the
  87.     formfeed  character,  CPRINT always follows a formfeed character with a
  88.     carriage return character.  Be sure your  edit  or  view  program  will
  89.     retain/display  this character combination or you may get/see incorrect
  90.     results.  Also ensure that your editor will not change or  discard  any
  91.     other  printer  control codes which might be in the text or you may get
  92.     incorrect results when the output is printed.  For example, the control
  93.     code  sequence  to put my printer into Diablo 630 emulation mode is ESC
  94.     CR P (27 13 80 decimal).  When my editor reads  a  file  starting  with
  95.     this  sequence  it  interprets  the  CR  as  a  command and immediately
  96.     backspaces - erasing the ESC and leaving only the P.   Another  example
  97.     would  be a line which ENDS with a formfeed.  CPRINT puts this line out
  98.     terminated with a single CR (no linefeed).  Some editors  will  execute
  99.     the  CR  upon  reading  the file and effectively delete the line.  Also
  100.     some file view programs will  execute  the  CR  and  then  display  the
  101.     following  line  over  the  top of the line ending with the formfeed-CR
  102.     (effectively preventing it from being displayed).  BE CAREFUL.
  103.  
  104.  
  105.     Some Examples
  106.     -------------
  107.  
  108.         Print files with file date & time info as page heading, 54
  109.         text lines per page, using front of paper only (all defaults).
  110.  
  111.            CPRINT D:\LC\USER\SRC\*.C
  112.  
  113.  
  114.         Same as above but add an 8 character left margin and print on both
  115.         sides of the paper (put your printer in 12 CPI mode first).
  116.  
  117.            CPRINT D:\LC\USER\SRC\*.C /M8 /W88 /1
  118.  
  119.              when  1st  pass  printout  is  completed  flip paper over then
  120.              enter:
  121.  
  122.            CPRINT D:\LC\USER\SRC\*.C /M8 /W88 /2
  123.  
  124.  
  125.     Notice in the second example I told CPRINT to use an 88 character  line
  126.     width.  The default width is 80.  If the total print width (left margin
  127.     +  text)  is  greater than the /W parameter CPRINT will break the line,
  128.     linefeed, space over by the left margin amount, then print the  balance
  129.     of the line.  Since we put the printer in 12 CPI mode we needed to tell
  130.     CPRINT  that  88  characters  would fit on the print line so that input
  131.     lines longer than 72 characters would not be  needlessly  split.   This
  132.     effectively  centers an 80 character wide line on the 96 character wide
  133.     page with 8 character left and right margins.
  134.  
  135.  
  136.     The /I switch
  137.     -------------
  138.  
  139.     This  switch  can  be  very  useful  when printing on both sides of the
  140.     paper.  For instance, I use a text formatter which  puts  a  string  of
  141.     printer  intialization  codes  at  the beginning of the document to put
  142.     the printer in LETTER QUALITY mode.  When the  printer  is  turned  off
  143.     in  order  to  turn  the  paper over prior to printing the back side it
  144.     goes back into DRAFT mode.  The  /I  switch  can  be  used  during  the
  145.     second  pass to put the printer back in LETTER QUALITY mode (since page
  146.     one and the control codes it  contains  won't  be  printed  during  the
  147.     second pass).
  148.  
  149.  
  150.     The /S switch
  151.     -------------
  152.  
  153.     This  switch can be used in conjunction  with /1 and /2 to  control the
  154.     interleaving  of multiple  files  when  printing on both  sides of  the
  155.     paper. Suppose we have two files - FILEA containing 3 pages of data and
  156.     FILEB  containing 2 pages of data. If we wish to print on both sides of
  157.     the paper we can print the files with or without interleaving:
  158.  
  159.       Without /S
  160.       ----------
  161.  
  162.       CPRINT FILE? /1
  163.          then
  164.       CPRINT FILE? /2
  165.  
  166.       This will produce the following page layout:
  167.  
  168.         sheet 1 front side - page 1 of FILEA
  169.         sheet 1 back side  - page 2 of FILEA
  170.  
  171.         sheet 2 front side - page 3 of FILEA    <--- files
  172.         sheet 2 back side  - page 1 of FILEB    <---   interleaved
  173.  
  174.         sheet 3 front side - page 2 of FILEB
  175.         sheet 3 back side  - blank
  176.  
  177.       Notice that page 3 of FILEA and page 1 of FILEB are printed on
  178.       opposite sides of the same piece of paper.
  179.  
  180.       With /S
  181.       -------
  182.  
  183.       CPRINT FILE? /S /1
  184.          then
  185.       CPRINT FILE? /S /2
  186.  
  187.       This will produce the following page layout:
  188.  
  189.         sheet 1 front side - page 1 of FILEA
  190.         sheet 1 back side  - page 2 of FILEA
  191.  
  192.         sheet 2 front side - page 3 of FILEA    <--- files
  193.         sheet 2 back side  - blank              <---   split
  194.  
  195.         sheet 3 front side - page 1 of FILEB
  196.         sheet 3 back side  - page 2 of FILEB
  197.  
  198.       Notice that each file is printed on a unique set of sheets when /S
  199.       is used.
  200.  
  201.  
  202.     Line Length
  203.     -----------
  204.  
  205.     CPRINT will start a new print line whenever a Carriage Return/Line Feed
  206.     sequence  is  encountered in the  input  file  OR  the  line length (as
  207.     set  by the /W switch) is reached.  The program attempts to account for
  208.     non-printing  characters when  making these decisions (embedded printer
  209.     control codes).  This is critical only  when  an  input  line's  length
  210.     exceeds  the /W line length due to embedded control codes. CPRINT  does
  211.     NOT count any of the following as printed characters  when  calculating
  212.     printed line length:
  213.  
  214.             - Characters less than ASCII Space (32)
  215.  
  216.             - ANY single character immediately following an
  217.               ASCII Escape (27)
  218.  
  219.     For instance, if the physical line length is 84, the /W length  is  80,
  220.     and  the line contains two 2 character long printer control sequences -
  221.     the last four characters will NOT be printed on the next  line  because
  222.     CPRINT  understands that 4 of the characters were control codes and did
  223.     not move the printhead.  However, if the 84 character  long  line  does
  224.     not  contain  any  control  codes  then it will be split and the last 4
  225.     characters will be printed by themselves on the next  line.   There  is
  226.     one  situation  where  this  falls  flat  -  some printers have control
  227.     sequences composed of an ESCAPE  CHARACTER  FOLLOWED  BY  TWO  OR  MORE
  228.     NON-CONTROL CODE CHARACTERS.  For example:
  229.  
  230.        ESC A H
  231.  
  232.     This  will  be  considered  TWO  non-printed  characters  (ESC + single
  233.     character following it - A). Therefore CPRINT will think the  printhead
  234.     has moved right one character more than it actually has (due to the H).
  235.     The  /W  switch can be used to compensate accordingly.  I have found it
  236.     virtually impossible to build a program capable of interpreting all  of
  237.     the  various  control  code  sequences  used  by  all  of  the  printer
  238.     manufacturers.  I do not see this as a significant  problem  given  the
  239.     programs intent - to print source code and on-line documentation files.
  240.  
  241.  
  242.     Programmers Example
  243.     -------------------
  244.  
  245.     Given the following inputs:
  246.  
  247.       CPRINT PTD*.C /M8 /W88 /1
  248.  
  249.          then
  250.  
  251.       CPRINT PTD*.C /M8 /W88 /2
  252.  
  253.     CPRINT  printed  40 some files encompassing 115 pages with page breaks,
  254.     left margins for 3 hole punch, descriptive  file  information  as  page
  255.     headers,  and  correctly  interleaved on both sides of the 58 sheets of
  256.     paper.  Just like a book.  Need I say more?
  257.  
  258.  
  259.     Restrictions
  260.     ------------
  261.  
  262.           o  MS-DOS Version 2.0 or later is required for versions thru 4.6.
  263.  
  264.           o  OS/2 Version 1.0 or later is required for version 5.0.
  265.  
  266.           o  MS-DOS Version 2.0 or later -OR- OS/2 Version 1.0 or later is
  267.              required for version 5.02 and above.
  268.  
  269.  
  270.         CPRINT is supplied for personal, private use. Feel free to
  271.         distribute CPRINT given these restrictions:
  272.  
  273.           o  the program  shall be supplied in its original, unmodified
  274.              form, which includes this documentation and all other
  275.              files in the distribution list.
  276.  
  277.           o  no fee is charged.
  278.  
  279.           o  commmercial use is prohibited.
  280.  
  281.           o  the program may NOT be included - or bundled - with other
  282.              goods or services.
  283.  
  284.         If you  are using CPRINT and  find it of value, any contribution
  285.         would be greatly appreciated ($10 suggested).
  286.  
  287.         I would like to thank all of the users who have provided feedback
  288.         and bug reports.  I never dreamed how many strange character and
  289.         format combinations appear in many of the text files floating around
  290.         out there.  I am sure that we have not yet uncovered and addressed
  291.         all of them.  Keep the feedback coming and I'll keep trying to
  292.         improve CPRINT.
  293.  
  294.  
  295.         Contributions and problem reports may be sent to:
  296.  
  297.  
  298.                Larry I. Smith
  299.                808 Shenandoah Dr.
  300.                Plano, Texas 75023
  301.  
  302.  
  303.     Revision History
  304.     ----------------
  305.  
  306.           o  v3.9  - First public release.
  307.  
  308.           o  v4.0  - Added support for embedded printer codes.
  309.  
  310.           o  v4.1  - Corrected logic to handle lines containing an
  311.                      embedded CR.  Some formatters use this method
  312.                      to emulate bold and underlining.
  313.  
  314.           o  v4.2  - Internal housekeeping.
  315.  
  316.           o  v4.3  - Corrected a bug associated with lines which
  317.                      start with a CR and contain more than the CR.
  318.  
  319.           o  v4.4  - Replaced fopen/fprintf function calls with
  320.                      open/write function calls.  Some pc clones
  321.                      running versions of MS-DOS 2.x do not always
  322.                      write to the printer correctly using fopen/fprintf.
  323.  
  324.                    - Added CPRINTS.EXE to the archive.  This is
  325.                      CPRINT.EXE with the full screen editor input
  326.                      feature for page layout info (/P switch) removed
  327.                      so that users with non IBM compatible pc's won't
  328.                      crash their system trying to use the full screen
  329.                      mode.
  330.  
  331.           o  v4.5  - Corrected a logic error that caused the page
  332.                      break for page 2 to be calculated incorrectly
  333.                      for some files.  This only affected files which
  334.                      used CR's rather than FF's to space pages.
  335.  
  336.                    - Added the /O option to allow routing of output
  337.                      to a file rather than the printer.
  338.  
  339.           o  v4.6  - Added the /I option to allow sending printer
  340.                      initialization codes.
  341.  
  342.                    - Deleted CPRINT from the archive and renamed CPRINTS
  343.                      to CPRINT.  The full screen editor option (/P switch)
  344.                      in the original CPRINT just caused too many problems
  345.                      with too many PC clones.
  346.  
  347.           o  v5.0  - OS/2 Protected mode only version.
  348.  
  349.           o  v5.02 - Merged OS/2 and MS-DOS versions into one Family
  350.                      API program which can run under either operating
  351.                      system.  Now requires Microsoft C v5.10 or higher
  352.                      and the OS/2 Programmers Tool Kit to compile.
  353.