home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 19 Printer / 19-Printer.zip / spr10.zip / spr.inf (.txt) < prev    next >
OS/2 Help File  |  1994-03-10  |  18KB  |  478 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Overview ΓòÉΓòÉΓòÉ
  3.  
  4. spr--Simple PRinter.  spr is a printing program that paginates the output, adds 
  5. left margins, cuts lines that extend beyond the right margin, selects character 
  6. pitches and line spacings and adds customisable page headers and footers. 
  7.  
  8. spr does *not* format the text in any way, ie.  it doesn't justify margins, 
  9. wrap long lines or anything that would change the appearance of the text, with 
  10. the exception of adding the headers. spr is not intended to be a text formatter 
  11. (like nroff) or word processing language (like TeX). 
  12.  
  13. You can, of course, use another program to preprocess the text for spr.  Adam 
  14. M. Costello's par, for instance, is a good choice, but even simpler utilities 
  15. may do what you're looking for.  For example, to have the text lines numbered 
  16. and control characters translated to the `^' and `M-' notation, you can 
  17. preprocess the file with GNU cat like this: 
  18.  
  19.     cat -nv somefile.txt | spr
  20.  
  21. A printer definition (`*.def') file is needed for the printer-dependent actions 
  22. (selecting character pitches etc.)  to work. See Printer definition files, if 
  23. your printer is not on the following list: 
  24.  
  25. o 9-pin Epson compatibles (at least FX-80/100) 
  26.  
  27. o IBM Graphics Printer and compatibles 
  28.  
  29. o Panasonic KX-P1081 (possibly other Panasonics too) 
  30.  
  31. o Fujitsu DL2400, DL2600, and DL3400 
  32.  
  33. o Hewlett-Packard LaserJet (III, possibly others too) 
  34.  
  35. The following definition files are untested and may not work at all. Also, they 
  36. are partial and do not contain all the commands the printers might support: 
  37.  
  38. o IBM QuietWriter 
  39.  
  40. o Epson LQ-2500 (possibly other LQ's, too) 
  41.  
  42.  
  43. ΓòÉΓòÉΓòÉ 2. Usage ΓòÉΓòÉΓòÉ
  44.  
  45.     spr file ... [ options ]
  46.  
  47. Standard input can be read by specifying `con' as the file name.  In that case, 
  48. however, the `$f' and `$F' commands in headers and footers (See Headers and 
  49. footers) return an empty string. 
  50.  
  51. Output goes to the standard output if no other output stream is set with the 
  52. `/o' (or `/output') switch. 
  53.  
  54. Multiple occasions of any single option (or its synonym) are allowed on the 
  55. command line and the `SPRSWITCHES' environment variable (See Environment). 
  56. Only the last one will take effect. 
  57.  
  58. /a=n 
  59. /starting-from=n 
  60.           The first page of the document is page number n.  This is intended to 
  61.           help in the creation of multi-file documents.  The default is 1. 
  62.  
  63. /b=n 
  64. /begin=n 
  65.           Begin at page number n, ie.  skip n-1 pages from the beginning of the 
  66.           document.  The value of n is affected by the `/a' switch, if it was 
  67.           specified *before* `/b'.  The default is 1. 
  68.  
  69. /c=n 
  70. /pitch=n 
  71.           Set the character pitch to n characters per inch (cpi).  If the 
  72.           printer doesn't support n cpi printing, an error message is given. 
  73.           The default is 10. 
  74.  
  75. /e=n 
  76.  
  77. /end=n 
  78.           End the printing after page number n, ie.  skip pages from and 
  79.           including page number n+1.  If the file has fewer pages than that, 
  80.           the switch is silently ignored.  The default is 65536, which 
  81.           practically always means the end of the file. 
  82.  
  83. /f="footer" 
  84. /footer="footer" 
  85.           Create a page footer for the document.  See Headers and footers, and 
  86.           the note under `/F' switch.  The default is "|$#" (centered page 
  87.           number). 
  88.  
  89. /fe="evenfooter" 
  90.  
  91. /even-footer="evenfooter" 
  92.           Create an even-page footer.  See Headers and footers, and the note 
  93.           under `/F' switch.  The default is "". 
  94.  
  95. /fo="oddfooter" 
  96. /odd-footer="oddfooter" 
  97.           Create an odd-page footer.  See Headers and footers, and the note 
  98.           under `/F' switch.  The default is "". 
  99.  
  100. /F={0|1|2} 
  101. /footers={0|1|2} 
  102.           Select the number of printable footers.  If `/F=0', footers are not 
  103.           printed even if one or more of the switches `/f', `/fe', and `/fo' 
  104.           were specified.  If `/F=1', the value of `/f' will be used as a 
  105.           footer for both odd- and even-numered pages.  If `/F=2', 
  106.           even-numbered pages will get `/fe' footer, and odd-numbered pages 
  107.           `/fo' footer.  The default is `/F=0'. 
  108.  
  109. /h="header" 
  110. /header="header" 
  111.           Create a page header for the document.  See Headers and footers, and 
  112.           the note under `/H' switch.  The default is "$F||$#". 
  113.  
  114. /he="evenheader" 
  115. /even-header="evenheader" 
  116.           Create an even-page header.  See Headers and footers, and the note 
  117.           under `/H' switch.  The default is "$#" (left-aligned page number). 
  118.  
  119. /ho="oddheader" 
  120. /odd-header="oddheader" 
  121.           Create an odd-page header.  See Headers and footers, and the note 
  122.           under `/H' switch.  The default is "||$#" (right-aligned page 
  123.           number). 
  124.  
  125. /H={0|1|2} 
  126. /headers={0|1|2} 
  127.           Select the number of printable headers.  If `/H=0', headers are not 
  128.           printed even if one or more of the switches `/h', `/he', and `/ho' 
  129.           was given.  If `/H=1', the value of `/h' will be used as a header for 
  130.           both odd- and even-numered pages.  If `/H=2', even-numbered pages 
  131.           will get `/he' header, and odd-numbered pages `/ho' header.  The 
  132.           default is `/H=1'. 
  133.  
  134. /k[+|-] 
  135. /keep-long[+|-] 
  136.           Keep long lines, ie.  don't truncate lines that extend beyond the 
  137.           right margin as is the default behaviour.  The result of keeping is 
  138.           unpredictable and depends on your printer.  The switch can be 
  139.           followed by an optional plus or minus sign, of which the minus sign 
  140.           `-' reverses the effect (ie.  `/k-':  cut long lines). 
  141.  
  142. /l=n 
  143. /left=n 
  144.           Set the left margin to n, where n is a positive integer.  The margin 
  145.           is given in character units, which means that the margin will be 
  146.           different for different character pitches.  The default is 8. 
  147.  
  148. /n=n 
  149. /page-length=n 
  150.           Set the page length to n (in line units).  Note that this value is 
  151.           *not* affected by the value of the `/s' switch:  if you set a low 
  152.           value for `/s' (fewer lines per inch), you might need to change the 
  153.           value of `/n' too, so that the page breaks print out correct. The 
  154.           default is 55. 
  155.  
  156. /o=file 
  157.  
  158. /output=file 
  159.           This switch bears the same function as the OS/2 redirection symbol 
  160.           `>'.  If you type 
  161.  
  162.                         spr somefile.txt /o=somefile.prn
  163.  
  164.           this has the same effect as 
  165.  
  166.                         spr somefile.txt > somefile.prn
  167.  
  168.           The main reason for having the a separate `/o' switch is that you can 
  169.           set `/o=prn' in the `SPRSWITCHES' environment variable (See 
  170.           Environment), and the output is sent directly to the printer without 
  171.           you having to remember the `> prn' redirection.  Only `con' is 
  172.           redirectable, ie.  if file is anything else than `con', command line 
  173.           level redirection and piping will be disabled. 
  174.  
  175.           The default is `con'. 
  176.  
  177. /p=printer 
  178. /printer=printer 
  179.           Select which printer definitions to use.  This switch causes spr to 
  180.           read a definition file named `printer.def', where printer is the name 
  181.           you specified on the command line.  The definition file is searched 
  182.           using `SPRDEFPATH' environment variable (See Environment), or if it 
  183.           is not set, from the current directory. 
  184.  
  185.           If the printer is set to `dumb', which is the default, spr doesn't 
  186.           support changing print qualities, character pitches, or line 
  187.           spacings.  The output format of `dumb' should be fine for most 
  188.           printers. 
  189.  
  190. /q={0|1|2} 
  191. /quality={draft|report|letter} 
  192.           Select print quality (resolution) used.  This switch only works with 
  193.           printers that support different print qualities.  If the current 
  194.           printer doesn't support requested quality, an error message is given. 
  195.           The default is 0 or the lowest quality. 
  196.  
  197. /r=n 
  198.  
  199. /right=n 
  200.           Set the right margin to n.  The total width of the page is the value 
  201.           of `/r' + the value of `/l'; that is, the `/r' switch determines the 
  202.           right margin as it is *before* the left margin is added.  The default 
  203.           is 72. 
  204.  
  205. /s=n 
  206. /spacing=n 
  207.           Set the line spacing to n lines per inch.  If the printer does not 
  208.           support n lpi spacing, an error message is given.  The default is 6. 
  209.  
  210. /v 
  211. /version 
  212.           Display program version and quit. 
  213.  
  214. /? 
  215. /help 
  216.           Display help page and quit. 
  217.  
  218.  
  219. ΓòÉΓòÉΓòÉ 3. Headers and footers ΓòÉΓòÉΓòÉ
  220.  
  221. Headers and footers are defined with the following switches: 
  222.  
  223.     /h /he /ho /f /fe /fo
  224.  
  225. The value part of these switches is a string containing text and special 
  226. commands.  The commands begin with a `$' (dollar sign) and consist of one 
  227. command character.  The character case is significant, ie.  `$w' is not the 
  228. same command as `$W'. 
  229.  
  230. The general format for the header- or footer-defining string is 
  231.  
  232.     "LEFT[|[CENTER]|[RIGHT]]"
  233.  
  234. A bar (`|') separates the parts that should be left-aligned, centered, and 
  235. right-aligned.  For example, the string 
  236.  
  237.     "Left|Center|Right"
  238.  
  239. would align the word `Left' to the left margin, center the word `Center', and 
  240. right-align the word `Right'.  Any part can be missing--for example, 
  241.  
  242.     "Left"
  243.     "|Center"
  244.     "Left||Right"
  245.     "|Center|Right"
  246.     "||Right"
  247.  
  248. spr infers the placing of the text from the number of preceding `|' characters 
  249. (See Bugs and limitations). 
  250.  
  251. The following `$' commands are recognized: 
  252.  
  253. $# 
  254.           current page number 
  255.  
  256. $a 
  257.           `am' or `pm' of current time 
  258.  
  259. $d 
  260.           current day 
  261.  
  262. $f 
  263.           file name 
  264.  
  265. $F 
  266.           same as `$f', but includes the path 
  267.  
  268. $h 
  269.           current hour (24 hour clock) 
  270.  
  271. $H 
  272.           current hour (12 hour clock; cf. `$a') 
  273.  
  274. $m 
  275.           current month 
  276.  
  277. $M 
  278.           current minute 
  279.  
  280. $o 
  281.           English name of the current month (eg. `February') 
  282.  
  283. $O 
  284.           current English month name abbreviation (eg. `Feb') 
  285.  
  286. $v 
  287.           spr version (eg. `v1.0') 
  288.  
  289. $V 
  290.           OS/2 version (eg. `2.1') 
  291.  
  292. $w 
  293.           current weekday (eg. `Monday') 
  294.  
  295. $W 
  296.           current weekday abbreviation (eg. `Mon') 
  297.  
  298. $z 
  299.           file size in bytes (eg. `13005') 
  300.  
  301. $Z 
  302.           file size in kilobytes (eg. `12') 
  303.  
  304. $y 
  305.           current year with century (eg. `1994') 
  306.  
  307. $Y 
  308.           current year without century (eg. `94') 
  309.  
  310. $$ 
  311.           `$' (literal dollar sign) 
  312.  
  313. `$d', `$h', `$m', `$M', and `$Y' of course, always include the leading zero 
  314. (eg. `07' instead of `7'). 
  315.  
  316. The default header is 
  317.  
  318.     /h="$F||$#"
  319.  
  320. That is, the full path name on the left, and the page number on the right. To 
  321. have the same kind of header that GNU pr uses, type 
  322.  
  323.     /h="$O $d $h:$M $y $F Page $#"
  324.  
  325. on the spr command line (everything is left-aligned). 
  326.  
  327.  
  328. ΓòÉΓòÉΓòÉ 4. Printer definition files ΓòÉΓòÉΓòÉ
  329.  
  330. Experienced users are encouraged to look at the existing definition files. The 
  331. format of the file is so simple that the quickest way to write new definition 
  332. files is to copy and modify an existing one. 
  333.  
  334. Printer definition file consists of three things: comments, keys, and values 
  335. for the keys. The syntax for the file is: 
  336.  
  337. o empty lines are ignored 
  338.  
  339. o lines beginning with a semicolon `;' are ignored 
  340.  
  341. o the key and its corresponding value must appear on the same line 
  342.  
  343. o only one key-value pair per line is accepted 
  344.  
  345. o the value must always be specified but it can be the empty string "" 
  346.  
  347. o the key and the value are both `words' in the REXX-sense, ie. 
  348.   blank-separated--this means you have to surround the value by double quotes 
  349.   if it contains blank characters (usually, it is best to do it anyway) 
  350.  
  351. o the following keys are recognized (case is not significant): 
  352.  
  353.    Init 
  354.              `initialise printer' sequence 
  355.  
  356.    Term 
  357.              `terminate printer' sequence 
  358.  
  359.    Pitch(n) 
  360.              set character pitch to n cpi 
  361.  
  362.    Quality(n) 
  363.              set print quality n, where n = 0...2 (0 = draft) 
  364.  
  365.    Spacing(n) 
  366.              set line spacing to n lpi 
  367.  
  368. o Init and Term keys are obligatory 
  369.  
  370. o n in Pitch, Quality and Spacing keys must be an integer! 
  371.  
  372. The value string can contain printable characters, and the following backslash 
  373. quotes to represent non-printable codes: 
  374.  
  375.       dec hex   name
  376.   --------------------------------------------------------------
  377.   \e   27 1B   escape
  378.   \f   12 0C   form feed (FF)
  379.   \n   10 0A   line feed (LF)
  380.   \r   13 0D   carriage return (CR)
  381.   \t    9 09   horizontal tab
  382.   \xnn        ASCII character whose hex value is nn
  383.  
  384. For example, to set the Init sequence to ESC + `@', and the Term sequence to 
  385. the empty string (no terminate action), specify: 
  386.  
  387.     ; The following is for Epsons
  388.     Init    "\e@"
  389.     Term    ""
  390.  
  391. To set the line spacing to 8 lpi, some printers use ESC + `0': 
  392.  
  393.     Spacing(8) "\e0"
  394.  
  395. Only those character pitches etc.  are usable with a specific printer that are 
  396. specified in the definition file.  That is, to be able to use 6 lpi spacing, 
  397. you'll have to include a definition for `Spacing(6)' in the printer definition 
  398. file. 
  399.  
  400.  
  401. ΓòÉΓòÉΓòÉ 5. Environment ΓòÉΓòÉΓòÉ
  402.  
  403. `SPRSWITCHES' 
  404.           This environment variable is designed to keep the user's default 
  405.           switch values for spr.  For example, if the system only has an Epson 
  406.           printer, you can define 
  407.  
  408.                         set sprswitches=/p=epson
  409.  
  410.           and have the Epson definitions used always without explicitly 
  411.           specifying so on the command line. 
  412.  
  413.           The format of the string is the same as for the command line 
  414.           switches.  To have it set when the system starts, include the line in 
  415.           your `\config.sys' file. 
  416.  
  417.           I'm using the following: 
  418.  
  419.                         /c=12/h="$f|$#|$d.$M.$Y $h.$m"/n=80/o=prn/p=fujitsu/r=76/s=8
  420.  
  421.           (There is no need to put any blanks between the switches.)  This 
  422.           means: character pitch 12 cpi, custom header, page length 80 lines, 
  423.           output directly to printer, use Fujitsu definitions, right margin at 
  424.           76, and line spacing 8 lpi. 
  425.  
  426.           The defaults given in `SPRSWITCHES' can of course be overridden from 
  427.           the command line. 
  428.  
  429. `SPRDEFPATH' 
  430.           This is the search path for the printer definition (`*.def') files. 
  431.           It has the same format as other path variables such as `PATH' and 
  432.           `DPATH'.  For example, to force spr to search for the definition 
  433.           files first in the current directory, and then `C:\Etc\Printer' 
  434.           directory, set 
  435.  
  436.                         set sprdefpath=.;C:\Etc\Printer
  437.  
  438.           Note:  if the current directory `.' isn't given, the current 
  439.           directory won't be searched at all.  However, if `SPRDEFPATH' is left 
  440.           undefined, only the current directory is searched. 
  441.  
  442.  
  443. ΓòÉΓòÉΓòÉ 6. Files ΓòÉΓòÉΓòÉ
  444.  
  445.     spr.cmd     the executable
  446.     *.def       printer definition files
  447.  
  448.  
  449. ΓòÉΓòÉΓòÉ 7. Bugs and limitations ΓòÉΓòÉΓòÉ
  450.  
  451. The section-separating bar `|' in the header- and footer-defining strings 
  452. cannot be safely included in the headers and footers--currently the routine 
  453. that sections the string is fairly straightforward and doesn't allow quoting 
  454. the bar.  Additionally, only the first and the last bar are noticed, which 
  455. means that in fact it *is* possible to insert bars in the headers or footers, 
  456. but only in the centered section.  For example, 
  457.  
  458.     "Left|Centered|This is also Centered|Right"
  459.  
  460. would center the text `Centered|This is also Centered'. 
  461.  
  462.  
  463. ΓòÉΓòÉΓòÉ 8. Version and copyrights ΓòÉΓòÉΓòÉ
  464.  
  465. SOS spr v1.0 
  466. Copyright (C) SuperOscar Softwares, Tommi Nieminen 1994. 
  467.  
  468. This program is free software; you can redistribute it and/or modify it under 
  469. the terms of the GNU General Public License as published by the Free Software 
  470. Foundation; either version 1, or at (at your option) any later version. 
  471.  
  472. This program is distributed in the hope that it will be useful, but WITHOUT ANY 
  473. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
  474. PARTICULAR PURPOSE.  See the GNU General Public License for more details. 
  475.  
  476. You should have received a copy of the GNU General Public License along with 
  477. this program; if not, write to the Free Software Foundation, Inc., 675 Mass 
  478. Ave, Cambridge, MA 02139, USA.