home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / INTER52D.ZIP / INTPRINT.DOC < prev    next >
Text File  |  1996-02-11  |  11KB  |  294 lines
  1.                 INTPRINT v3.10
  2.                 by Ralf Brown
  3.  
  4. The INTPRINT program is hereby donated to the public domain, with the sincere
  5. hope that proper credit will be retained in all copies and derivatives.
  6.  
  7. ------------------------------------------------------------------------------
  8.  
  9. INTPRINT.COM is a simple formatter for the interrupt list.  Use this
  10. program to print only a portion of the list, prevent widow lines at the
  11. beginning of a function call, number the pages, boldface key portions,
  12. center the printout, or create a summary of the function calls.  After
  13. formatting is complete, the total number of pages is displayed on the
  14. screen.
  15.  
  16. Usage:
  17.    intprint [options] intlist [[>|>>]outfile]
  18.  
  19. where the options are:
  20.     -b    boldface the title lines, Return:, and Notes: by overprinting
  21.     -B    boldface by sending printer control sequences
  22.  
  23.     -d    (duplex) print even/odd pages with different margins; suitable
  24.           for binding the printout.
  25.  
  26.     -e    assume printer is in elite mode (96 characters per line), and
  27.           indent the output eight spaces to center the printout.  This
  28.           is primarily for the default printer, as other printers may
  29.           force the equivalent or override this option.
  30.  
  31.     -ffile    create a file containing only the data structures described
  32.           in the interrupt list.
  33.           NOTE: you must put the filename immediately after the 'f'; no
  34.           blanks are allowed.
  35.  
  36.     -Ffile    filter the listing based on include and exclude strings
  37.           in 'file'.  Only entries whose headers match none of the
  38.           exclude strings and at least one of the include strings
  39.           will be processed.  All others will be skipped.
  40.           NOTE: you must put the filename immediately after the 'F'; no
  41.           blanks are allowed.
  42.  
  43.     -H    print a heading on each page indicating which interrupts
  44.           are listed on the page
  45.  
  46.     -iN   indent the output N spaces.  The output device is assumed to be
  47.           at least 80+N characters wide.
  48.           NOTE: you must put the number immediately after the 'i'; no
  49.           blanks are allowed.
  50.  
  51.     -I    assume the printer is capable of producing IBM character
  52.           graphics.  Printers other than "default" may force this option.
  53.  
  54.     -k    keep original divider lines instead of replacing them
  55.           with all dashes.
  56.  
  57.     -lN   print N lines per pages, overriding the printer-specific
  58.           default.    Use 0 to omit page breaks (in this case, the
  59.           reported number of pages and -r page restriction may be
  60.           incorrect unless you also use -L); this can be useful if
  61.           you only want to filter the list before processing it
  62.           further.
  63.  
  64.     -LN   assume N lines on a page.  If this is more than the number of
  65.           lines to print on each page, INTPRINT will use line feeds to
  66.           advance to the next page instead of form feeds.
  67.  
  68.     -m    specify that the interrupt list is in multiple parts beginning
  69.           with the named file.  INTPRINT will increment the last
  70.           character of the name to get the next filename, and continue
  71.           until it is unable to open the file thus selected.
  72.  
  73.     -nN   assume N pages have already been printed, and start numbering
  74.           at N+1.  This option allows you to create a properly-numbered
  75.           printout even if there is not enough disk space to concatenate
  76.           the parts of the interrupt list or hold a complete output file.
  77.           See the examples below.
  78.           NOTE: you must put the number immediately after the 'n'; no
  79.           blanks are allowed.
  80.  
  81.     -p    print the page number at the bottom center of each page
  82.  
  83.     -Pname use control codes for the specified printer (-P? lists the
  84.           supported printers).  The printer name may be given in either
  85.           case and abbreviated to a unique prefix; use either dashes or
  86.           underscores in place of blanks in the printer name.
  87.  
  88.     -rN:M print only pages N through M.  The entire input is processed
  89.           for use in -s and -f summaries (see below) even though only
  90.           a portion is formatted for printing.  If filtering is enabled,
  91.           (see -F), page numbers are based on entries selected by the
  92.           filter file.
  93.           NOTE: you must put the page numbers immediately after the 'r';
  94.           no blanks are allowed.  When using -l0 together with -r,
  95.           you must specify the appropriate page length with -L so
  96.           that page numbers can be computed correctly.
  97.  
  98.     -sfile    create a one-line-per-function summary and write it to "file"
  99.           if -n is also given, the summary will be appended to "file",
  100.           allowing a properly numbered summary file to be created even if
  101.           there is not enough disk space to concatenate the parts of the
  102.           list.  See the examples below.  If -p is also given, page
  103.           numbers will be included in the summary.    If -V is also given,
  104.           byte offsets for use by INTERVUE will be included.
  105.           NOTE: you must put the filename immediately after the 's'; no
  106.           blanks are allowed.
  107.  
  108.     -tN   select typeface N for the chosen printer (currently supported
  109.           only for the HP).
  110.  
  111.     -Tfile    create a one-line-per-table summary and write it to "file"
  112.           if -n is also given, the summary will be appended to the named
  113.           file.  If -p is also given, page numbers will be included in
  114.           the summary.  If -V is also given, byte offsets for use by
  115.           INTERVUE will be included.
  116.           NOTE: you must put the filename immediately after the 'T'; no
  117.           blanks are allowed.
  118.  
  119.     -V    indicate that the summary file is intended for use by INTERVUE.
  120.           INTPRINT will output byte offsets that allow INTERVUE to jump
  121.           directly to an entry.  Also forces -I.
  122.  
  123.     -wN   (widow lines) search N lines from the end of the page for a
  124.           good place to break.  The default is eight lines; the valid
  125.           range is from 3 to one-half of the page length.
  126.           NOTE: you must put the number immediately after the 'w'; no
  127.           blanks are allowed.
  128.  
  129.     -x    include Index: lines in formatted listing.  These lines are
  130.           are excluded by default because they are intended primarily
  131.           for use by hypertext converters.
  132.  
  133. Options may not be merged; "-ep" is illegal and the "p" will be ignored.
  134. Use "-e -p" instead.
  135.  
  136. The formatted result of the input file is sent to the specified output file,
  137. or to standard output if no output file is given.  Standard output may be
  138. redirected using the usual Unix or MSDOS redirection characters > or >>.  If
  139. you only want a summary file or data formats file, send or redirect the
  140. output to the null device ("NUL" under MSDOS, "/dev/null" under Unix).
  141.  
  142.  
  143. FILTER FILE:
  144. ------------
  145.  
  146. The filter file specified with -F is a simple text file containing
  147. include lines, exclude lines, and comment lines.  Both 'include' and
  148. 'exclude' lines may be based on either a category code or a substring
  149. of the entry's title line.  Comment lines start with a hash mark (#) in
  150. the first column and are ignored.  The other valid command characters
  151. in the first column are:
  152.  
  153.    >  unconditionally include any entry with the specified category letter
  154.    <  unconditionally exclude any entry with the specified category letter
  155.    +  include entries containing the specified string, unless unconditionally
  156.       excluded
  157.    -  exclude entries containing the specified string, unless unconditionally
  158.       included
  159.    i  include entries with the given category letter unless specifically
  160.       excluded by a '-' line
  161.    o  override '-' line and include entry anyway if it has the given
  162.       category letter
  163.  
  164. Note that any category letters or selection strings must immediately
  165. follow the command character.  All spaces on '+' include and '-' exclude
  166. lines are significant.  Thus,
  167.     + DOS
  168. will only match entries containing the four-letter sequence " DOS",
  169. while
  170.     +DOS
  171. will match any entries containing the sequence "DOS", whether or not it
  172. is preceded by a blank.
  173.  
  174. If a filter file is specified, only entries whose title lines contain at
  175. least one of the '+' include lines (ignoring uppercase/lowercase
  176. distinctions), none of the '-' exclude lines, or whose category codes
  177. have been selected by other include/exclude lines, are processed.  Thus,
  178. a filter file must contain at least one include line, or INTPRINT will
  179. skip all interrupt entries and print only the non-interrupt text in the
  180. file.
  181.  
  182. ----cut here----
  183. # SAMPLE1.FLT
  184. # Sample filtering file number 1, using only title includes/excludes.
  185. # Extract MS-DOS calls, but exclude DR-DOS-specific, DOS-extender, and
  186. # non-DOS networking calls.
  187. # Note: a few extraneous calls are still included.
  188. #
  189. + DOS
  190. -DR DOS
  191. -DR-DOS
  192. -DR Multiuser DOS
  193. -Concurrent DOS
  194. -DOS/16M
  195. -DOS4GX
  196. -DOS/4G
  197. -extender
  198. -LAN Manager
  199. -DECnet DOS
  200. #
  201. # end of SAMPLE1.FLT
  202. ----cut here----
  203.  
  204. ----cut here----
  205. # SAMPLE2.FLT
  206. # Sample filtering file number 2, using category includes/excludes.  Extract
  207. # MS-DOS and DR-DOS calls, but exclude OS/2 and other operating systems.
  208. #
  209. # unconditionally include the DOS category
  210. >D
  211. # include 'other OSes' category, but remove OS/2, VMiX, PC-MOS, etc.
  212. iO
  213. -OS/2
  214. -VMiX
  215. -PC-MOS
  216. -STARLITE
  217. -WinDOS
  218. -Acorn BBC
  219. -Linux DOSEMU
  220. #
  221. # end of SAMPLE2.FLT
  222. ----cut here----
  223.  
  224. ------------------------------------------------------------------------------
  225.  
  226. EXAMPLES:
  227. ---------
  228.  
  229.     Print the interrupt list with page numbers, and create a summary file,
  230.     without concatenating INTERRUP.A, INTERRUP.B, and INTERRUP.C:
  231.  
  232.         A> intprint -sb:interrup.sum -p interrup.a >prn
  233.         146 pages    [screen output from INTPRINT]
  234.         A> intprint -sb:interrup.sum -p -n146 interrup.b prn
  235.         285 pages    [screen output from INTPRINT]
  236.         A> intprint -sb:interrup.sum -p -n285 interrup.c >prn
  237.         403 pages    [screen output from INTPRINT]
  238.  
  239.     or, more easily:
  240.         A> intprint -sb:interrup.sum -m -p interrup.a prn
  241.         1587 pages   [screen output from INTPRINT]
  242.  
  243.     Create only a summary file:
  244.  
  245.         C> intprint -sinterrupt.sum interrup.lst nul
  246.  
  247.     Create a listing of the tables in the interrupt list:
  248.  
  249.         C> intprint -Tinterrup.tbl interrup.lst nul
  250.  
  251.     Print only those entries containing the string "DOS", except
  252.     those containing the string "DR-DOS"
  253.  
  254.         C> type dos
  255.         +DOS
  256.         -DR-DOS
  257.  
  258.         C> intprint -Fdos interrup.lst nul
  259.         
  260.  
  261.     Print the interrupt list on an Epson FX80, using 54 lines per page and
  262.     omitting both page numbers and summary:
  263.  
  264.         C> intprint -Pepson -l54 interrup.lst >prn
  265.  
  266.     Print the interrupt list using 120 lines on every 132-line page (using
  267.     superscript mode, for example), and make divider lines using IBM
  268.     character graphics:
  269.  
  270.         C> intprint -I -l120 -L132 interrup.lst >prn
  271.  
  272.     Print only pages 123 through 127, assuming that 106 pages are contained
  273.     in the first section of the list:
  274.  
  275.         C> intprint -n106 -r123:127 interrup.b prn
  276.  
  277.     Print using HP PCL4/5 escape sequences, numbering pages, from file
  278.     "interrup.lst" to file "interrup.pcl", at the default 69 lines per
  279.     page, using form-feeds:
  280.  
  281.         C> intprint -Php -p interrup.lst >interrup.pcl
  282.         1587 pages    [screen output from INTPRINT]
  283.  
  284. ------------------------------------------------------------------------------
  285.  
  286. PORTABILITY:
  287. ------------
  288.  
  289. INTPRINT.C contains the source code for INTPRINT, for those people who
  290. are using the interrupt list on a machine which does not run MSDOS.
  291. This code has been tested with Turbo C v2.0, Borland C++ v3.1, and Mach
  292. (BSD 4.3 Unix) "cc" and "gcc".
  293.  
  294.