home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / print / qlistf / qlistf.doc < prev    next >
Text File  |  1994-02-04  |  11KB  |  274 lines
  1.  
  2.  
  3.                     QLISTF - 1.00 (DOS & OS/2)
  4.                           Documentation
  5.  
  6.     Copyright 1992-1993, Thomas G. Harold, All Rights Reserved.
  7.  
  8.  
  9.     QLISTF [switches] [infile ...] [-Ooutfile]
  10.  
  11.       Switches:
  12.         -ff{pdtf}   - Set footer format (page#,date,time,fname)
  13.         -hf{pdtf}   - Set header format (page#,date,time,fname)
  14.         -lf{z|l|r}  - Set line number format
  15.         -lix        - Set line number increment value to x
  16.         -ll{y|n}    - Display line numbers?
  17.         -lnx        - Set starting line number to x
  18.         -lp{y|n}    - Reset line number on each new page?
  19.         -lwx        - Set line number width to x
  20.         -mbx        - Set bottom margin to x lines
  21.         -mlx        - Set left margin to x columns
  22.         -mtx        - Set top margin to x lines
  23.         -pf{z|l|r}  - Set page number format
  24.         -pix        - Set page number increment value to x
  25.         -plx        - Set page length to x lines
  26.         -pnx        - Set starting page number to x
  27.         -pwx        - Set page number width to x
  28.         -sc{codes}  - Set printer setup codes eg -sc27,15
  29.         "-ls{str}"  - Set seperator string
  30.         @filename   - Reads switch settings from a file
  31.  
  32.  
  33.     QLISTF is a program that is designed to print code listings 
  34. complete with headers showing the file name, and line numbers.
  35. The following documentation applies to both DOS & OS/2 versions.
  36. The DOS & OS/2 versions are distributed as a single package and
  37. are not seperate programs.
  38.  
  39. -----------------------------------------------------------------
  40.  
  41. I.  Installation:
  42.  
  43.         To install QLISTF, copy QLISTF.EXE to a directory in your
  44.     DOS PATH statement.  QLISTF2.EXE is the OS/2 executable and
  45.     should be placed in with other OS/2 programs.
  46.  
  47.  
  48. II. Usage:
  49.  
  50.     A.  General use
  51.     
  52.             QLISTF will by default read from standard input and
  53.         write to standard output.  This allows the use of the
  54.         DOS pipe & redirection facility.  If a file name or
  55.         multiple file names (wildcards are allowed) is specified
  56.         on the command line, QLISTF will read instead from
  57.         those files.
  58.         
  59.             In order to send the output of QLISTF to a file
  60.         instead, use the "-Ofilename" paramenter, where filename
  61.         is the name of the file that you want to write to.
  62.         
  63.             To send the output of QLISTF directly to the printer
  64.         use DOS's redirection command:  e.g.
  65.         
  66.                 QLISTF ... > prn
  67.         
  68.             QLISTF will print a list of definable switches and 
  69.         their current default values by typing:
  70.         
  71.                 QLISTF -?
  72.                 
  73.  
  74.     B.  Switch Precedence
  75.  
  76.             QLISTF processes the command line switches in the 
  77.         order that they appear.  So if you define the left margin 
  78.         twice, the second definition will override the first.  
  79.         This also applies to reading switch settings from a file:  
  80.         QLISTF will read the file as soon as it encounters a "@" 
  81.         switch.
  82.  
  83.  
  84.     C.  Switch Settings Files (@filename)
  85.  
  86.             Switch settings files allow you to create more detailed
  87.         settings without trying to fit everything into the 128 
  88.         characters that DOS allows on the command line.  To use
  89.         a switch settings file, use the following command:
  90.         
  91.             QLISTF @filename ...
  92.             
  93.             You can include multiple switch settings files, and
  94.         even mix normal switches with switch settings file names.
  95.         Each settings file will be processed as soon as it is
  96.         encountered in the list of switches.
  97.  
  98.             Basically, these are files containing switches, with
  99.         one switch per line.  The '-' part of the switch MUST be
  100.         the first character on the line.
  101.  
  102.             You cannot nest switch files at this point.  If asked,
  103.         I will probably include this in a future version.  You must
  104.         also specify the complete pathname of the switch settings
  105.         file.  Depending on demand, I am also considering allowing
  106.         an environment variable to point to the directory which
  107.         contains your switch setting files.
  108.  
  109.             Included in the package are some sample settings files
  110.         with an extension of *.QLS.
  111.         
  112.  
  113.     D.  Switch settings
  114.  
  115.         -ff{pdtf}   - Set footer format (page#,date,time,fname)
  116.         -hf{pdtf}   - Set header format (page#,date,time,fname)
  117.         
  118.             Header and footer formats can contain any or all of
  119.         the following items:  Page #, Current Date, Current Time,
  120.         File Name.  To print the current date & time at the top
  121.         of the page, and the file name and page number at the 
  122.         bottom of the page, use the following command:
  123.         
  124.             QLISTF -hfdt -fffp        
  125.  
  126.         -lf{z|l|r}  - Set line number format
  127.         
  128.             Line numbers can be formatted one of three ways.
  129.         Left justified, right justified, or zero filled.  The
  130.         table below shows the formatting performed by each of
  131.         the possible options.
  132.         
  133.              -lfz        0093
  134.              -lfl        93
  135.              -lfr          93
  136.  
  137.         -lix        - Set line number increment value to x
  138.         -ll{y|n}    - Display line numbers?
  139.         -lnx        - Set starting line number to x
  140.         -lp{y|n}    - Reset line number on each new page?
  141.         -lwx        - Set line number width to x
  142.         
  143.             Line numbers default to starting with 0001,
  144.         incrementing by 1, with a width of 4, and not starting
  145.         over at the top of each page.  It is possible to 
  146.         change any of these behaviors, or even turn off the
  147.         line numbers all together.     
  148.         
  149.         -mbx        - Set bottom margin to x lines
  150.         -mlx        - Set left margin to x columns
  151.         -mtx        - Set top margin to x lines
  152.         
  153.             Use the above options to change your margins.  QLISTF
  154.         does not make use of a right margin, nor does it trim off
  155.         any characters that may cause the printer to wrap to the
  156.         next line or that do not fit on the paper.
  157.  
  158.         -pf{z|l|r}  - Set page number format
  159.         
  160.             Page numbers can also be formatted as left justified,
  161.         right justified, or zero filled.  See the line number 
  162.         format section for examples of each format type.
  163.  
  164.         -pix        - Set page number increment value to x
  165.         -pnx        - Set starting page number to x
  166.         -pwx        - Set page number width to x
  167.         
  168.             Page numbers default to starting with 1, incrementing
  169.         by 1, with a width of 4.  It is possible to change this
  170.         behavior with the above switches.  To turn off printing of
  171.         page numbers, see the Header/Footer formatting options.        
  172.         
  173.         -plx        - Set page length to x lines
  174.         
  175.             Page length defaults to 63, which is the maximum
  176.         number of lines that QLISTF will print (including headers,
  177.         footers, top margins, and bottom margins) before sending
  178.         a form-feed to the printer.
  179.         
  180.         -sc{codes}  - Set printer setup codes eg -sc27,15
  181.         
  182.             This switch allows printer setup codes to be sent to
  183.         the printer.  Codes can be entered as either decimal,
  184.         octal (#'s beginning with "0" e.g. 073), or hex (#'s 
  185.         beginning with "0x" e.g. 0x1B).  The maximum number of
  186.         codes that can be sent to the printer is around 500
  187.         bytes.  QLISTF will warn you if you send more than
  188.         450 bytes that you are close to filling up the printer
  189.         setup string buffer.
  190.             You can also split setup codes across multiple
  191.         switches.  They will be sent in the order that the
  192.         setup code switch was encountered.
  193.         
  194.         "-ls{str}"  - Set seperator string
  195.         
  196.             Seperator strings are used to seperate line numbers
  197.         from the text that they are numbering.  Seperator strings
  198.         can be up to 20 characters in length, and can contain
  199.         spaces.  The default seperator string is a row of three
  200.         dots ("...").  The following example shows how to change
  201.         the seperator string to five underlines.
  202.         
  203.             QLISTF "-ls_____" ...
  204.         
  205.         @filename   - Reads switch settings from a file
  206.         
  207.             Switch settings files are useful for large,
  208.         cumbersome "-sc..." setup code switches.  Or for 
  209.         relating groups of switch settings that are often
  210.         used.
  211.  
  212.         infiles...  - Input is read from a file or list of files
  213.         -Ooutfile   - Redirects output to a file
  214.         
  215.             To create a QLISTF listing of all the *.C & *.H
  216.         files in the current directory, as well as the MAKEFILE,
  217.         and send the output to MYFILES.PRN, use the following
  218.         command:
  219.         
  220.             QLISTF *.C *.H MAKEFILE -Omyfiles.prn
  221.  
  222. -----------------------------------------------------------------
  223.  
  224. History:
  225.  
  226.         1.02    May 1993
  227.             Original release version.
  228.  
  229. -----------------------------------------------------------------
  230.  
  231.     Usage of QLISTF is free to individuals using it for 
  232. personal/private use.  Educational institutions are also granted 
  233. free usage.  I do ask that if QLISTF is to be used by an 
  234. educational institution that I be notified for informational 
  235. purposes.  Use in a business environment or for business purposes
  236. requires a site licence.  (See SITELICN.DOC for current pricing 
  237. policy.)
  238.  
  239.                             DISCLAIMER
  240.     This program is distributed "as is".  I disclaim all 
  241.     warranties, expressed or implied, including, without 
  242.     limitation, the warranties of merchantability and of 
  243.     fitness for any purpose.  I will assume no liability for 
  244.     damages, direct or consequential, which may result from 
  245.     the use of this program. 
  246.  
  247.     Feel free to distribute this program so long as no money 
  248. changes hands except for media/connect-time costs.  Once again, I 
  249. ask that if this program is distributed by any mail-order 
  250. distribution company that I be notified.
  251.     Modifications may not be made to QLISTF except for 
  252. personal/private use.  Modified copies may not be distributed in 
  253. any form.  No additions, deletions, or modifications may be made 
  254. to the contents of the archive.  The chosen archive format may
  255. be changed so long as the contents of the archive remain intact.
  256.  
  257. -----------------------------------------------------------------
  258.  
  259. Please contact me if you have any suggestions or questions about 
  260. the program.  I can be reached at the following address: 
  261.  
  262.         Thomas G. Harold
  263.         2206 Tracey's Rd.
  264.         Sparks, MD. 21152
  265.  
  266. Or by using Compuserve MAIL:
  267.  
  268.         Thomas G. Harold - 71750,3724
  269.  
  270. Please place the word "QLISTF" where I can easily see it, 
  271. (e.g. in the subject field, or on the address label).  This will 
  272. help me to more easily attend to your correspondence.
  273.  
  274.