Overview
********

spr--Simple PRinter.  spr is a printing program that paginates the output, adds left margins, cuts lines that extend beyond the right margin, selects character pitches and line spacings and adds customisable page headers and footers.

spr does not format the text in any way, ie.  it doesn't justify margins, wrap long lines or anything that would change the appearance of the text, with the exception of adding the headers. spr is not intended to be a text formatter (like nroff) or word processing language (like TeX).

You can, of course, use another program to preprocess the text for spr.  Adam M. Costello's par, for instance, is a good choice, but even simpler utilities may do what you're looking for.  For example, to have the text lines numbered and control characters translated to the ^ and M- notation, you can preprocess the file with GNU cat like this:

         cat -nv somefile.txt | spr

A printer definition (*.def) file is needed for the printer-dependent actions (selecting character pitches etc.)  to work. See Printer definition files, if your printer is not on the following list:

  * 9-pin Epson compatibles (at least FX-80/100)

  * IBM Graphics Printer and compatibles

  * Panasonic KX-P1081 (possibly other Panasonics too)

  * Fujitsu DL2400, DL2600, and DL3400

  * Hewlett-Packard LaserJet (III, possibly others too)

The following definition files are untested and may not work at all. Also, they are partial and do not contain all the commands the printers might support:

  * IBM QuietWriter

  * Epson LQ-2500 (possibly other LQ's, too)

Usage
*****

         spr FILE ... [ OPTIONS ]

Standard input can be read by specifying con as the file name.  In that case, however, the $f and $F commands in headers and footers (see Headers and footers) return an empty string.

Output goes to the standard output if no other output stream is set with the /o (or /output) switch.

Multiple occasions of any single option (or its synonym) are allowed on the command line and the SPRSWITCHES environment variable (see Environment).  Only the last one will take effect.

/a=N
/starting-from=N
     The first page of the document is page number N.  This is intended to help in the creation of multi-file documents.  The default is 1.

/b=N
/begin=N
     Begin at page number N, ie.  skip N-1 pages from the beginning of the document.  The value of N is affected by the /a switch, if it was specified before /b.  The default is 1.

/c=N
/pitch=N
     Set the character pitch to N characters per inch (cpi).  If the printer doesn't support N cpi printing, an error message is given. The default is 10.

/e=N

/end=N
     End the printing after page number N, ie.  skip pages from and including page number N+1.  If the file has fewer pages than that, the switch is silently ignored.  The default is 65536, which practically always means the end of the file.

/f="FOOTER"
/footer="FOOTER"
     Create a page footer for the document.  See Headers and footers, and the note under /F switch.  The default is "|$#" (centered page number).

/fe="EVENFOOTER"

/even-footer="EVENFOOTER"
     Create an even-page footer.  See Headers and footers, and the note under /F switch.  The default is "".

/fo="ODDFOOTER"
/odd-footer="ODDFOOTER"
     Create an odd-page footer.  See Headers and footers, and the note under /F switch.  The default is "".

/F={0|1|2}
/footers={0|1|2}
     Select the number of printable footers.  If /F=0, footers are not printed even if one or more of the switches /f, /fe, and /fo were specified.  If /F=1, the value of /f will be used as a footer for both odd- and even-numered pages.  If /F=2, even-numbered pages will get /fe footer, and odd-numbered pages /fo footer.  The default is /F=0.

/h="HEADER"
/header="HEADER"
     Create a page header for the document.  See Headers and footers, and the note under /H switch.  The default is "$F||$#".

/he="EVENHEADER"
/even-header="EVENHEADER"
     Create an even-page header.  See Headers and footers, and the note under /H switch.  The default is "$#" (left-aligned page number).

/ho="ODDHEADER"
/odd-header="ODDHEADER"
     Create an odd-page header.  See Headers and footers, and the note under /H switch.  The default is "||$#" (right-aligned page number).

/H={0|1|2}
/headers={0|1|2}
     Select the number of printable headers.  If /H=0, headers are not printed even if one or more of the switches /h, /he, and /ho was given.  If /H=1, the value of /h will be used as a header for both odd- and even-numered pages.  If /H=2, even-numbered pages will get /he header, and odd-numbered pages /ho header.  The default is /H=1.

/k[+|-]
/keep-long[+|-]
     Keep long lines, ie.  don't truncate lines that extend beyond the right margin as is the default behaviour.  The result of keeping is unpredictable and depends on your printer.  The switch can be followed by an optional plus or minus sign, of which the minus sign - reverses the effect (ie.  /k-:  cut long lines).

/l=N
/left=N
     Set the left margin to N, where N is a positive integer.  The margin is given in character units, which means that the margin will be different for different character pitches.  The default is 8.

/n=N
/page-length=N
     Set the page length to N (in line units).  Note that this value is not affected by the value of the /s switch:  if you set a low value for /s (fewer lines per inch), you might need to change the value of /n too, so that the page breaks print out correct. The default is 55.

/o=FILE

/output=FILE
     This switch bears the same function as the OS/2 redirection symbol >.  If you type

              spr somefile.txt /o=somefile.prn

     this has the same effect as

              spr somefile.txt > somefile.prn

     The main reason for having the a separate /o switch is that you can set /o=prn in the SPRSWITCHES environment variable (see Environment), and the output is sent directly to the printer without you having to remember the > prn redirection.  Only con is redirectable, ie.  if FILE is anything else than con, command line level redirection and piping will be disabled.

     The default is con.

/p=PRINTER
/printer=PRINTER
     Select which printer definitions to use.  This switch causes spr to read a definition file named PRINTER.def, where PRINTER is the name you specified on the command line.  The definition file is searched using SPRDEFPATH environment variable (see Environment), or if it is not set, from the current directory.

     If the printer is set to dumb, which is the default, spr doesn't support changing print qualities, character pitches, or line spacings.  The output format of dumb should be fine for most printers.

/q={0|1|2}
/quality={draft|report|letter}
     Select print quality (resolution) used.  This switch only works with printers that support different print qualities.  If the current printer doesn't support requested quality, an error message is given.  The default is 0 or the lowest quality.

/r=N

/right=N
     Set the right margin to N.  The total width of the page is the value of /r + the value of /l; that is, the /r switch determines the right margin as it is before the left margin is added.  The default is 72.

/s=N
/spacing=N
     Set the line spacing to N lines per inch.  If the printer does not support N lpi spacing, an error message is given.  The default is 6.

/v
/version
     Display program version and quit.

/?
/help
     Display help page and quit.

Headers and footers
*******************

Headers and footers are defined with the following switches:

         /h /he /ho /f /fe /fo

The value part of these switches is a string containing text and special commands.  The commands begin with a $ (dollar sign) and consist of one command character.  The character case is significant, ie.  $w is not the same command as $W.

The general format for the header- or footer-defining string is

         "LEFT[|[CENTER]|[RIGHT]]"

A bar (|) separates the parts that should be left-aligned, centered, and right-aligned.  For example, the string

         "Left|Center|Right"

would align the word Left to the left margin, center the word Center, and right-align the word Right.  Any part can be missing--for example,

         "Left"
         "|Center"
         "Left||Right"
         "|Center|Right"
         "||Right"

spr infers the placing of the text from the number of preceding | characters (see Bugs and limitations).

The following $ commands are recognized:

$#
     current page number

$a
     am or pm of current time

$d
     current day

$f
     file name

$F
     same as $f, but includes the path

$h
     current hour (24 hour clock)

$H
     current hour (12 hour clock; cf. $a)

$m
     current month

$M
     current minute

$o
     English name of the current month (eg. February)

$O
     current English month name abbreviation (eg. Feb)

$v
     spr version (eg. v1.0)

$V
     OS/2 version (eg. 2.1)

$w
     current weekday (eg. Monday)

$W
     current weekday abbreviation (eg. Mon)

$z
     file size in bytes (eg. 13005)

$Z
     file size in kilobytes (eg. 12)

$y
     current year with century (eg. 1994)

$Y
     current year without century (eg. 94)

$$
     $ (literal dollar sign)

$d, $h, $m, $M, and $Y of course, always include the leading zero (eg. 07 instead of 7).

The default header is

         /h="$F||$#"

That is, the full path name on the left, and the page number on the right. To have the same kind of header that GNU pr uses, type

         /h="$O $d $h:$M $y $F Page $#"

on the spr command line (everything is left-aligned).

Printer definition files
************************

Experienced users are encouraged to look at the existing definition files. The format of the file is so simple that the quickest way to write new definition files is to copy and modify an existing one.

Printer definition file consists of three things: comments, keys, and values for the keys. The syntax for the file is:

  * empty lines are ignored

  * lines beginning with a semicolon ; are ignored

  * the key and its corresponding value must appear on the same line

  * only one key-value pair per line is accepted

  * the value must always be specified but it can be the empty string ""

  * the key and the value are both `words' in the REXX-sense, ie. blank-separated--this means you have to surround the value by double quotes if it contains blank characters (usually, it is best to do it anyway)

  * the following keys are recognized (case is not significant):

     Init
          `initialise printer' sequence

     Term
          `terminate printer' sequence

     Pitch(N)
          set character pitch to N cpi

     Quality(N)
          set print quality N, where N = 0...2 (0 = draft)

     Spacing(N)
          set line spacing to N lpi

  * Init and Term keys are obligatory

  * N in Pitch, Quality and Spacing keys must be an integer!

The value string can contain printable characters, and the following backslash quotes to represent non-printable codes:

           dec hex   name
       --------------------------------------------------------------
       \e   27 1B   escape
       \f   12 0C   form feed (FF)
       \n   10 0A   line feed (LF)
       \r   13 0D   carriage return (CR)
       \t    9 09   horizontal tab
       \xNN        ASCII character whose hex value is NN

For example, to set the Init sequence to ESC + @, and the Term sequence to the empty string (no terminate action), specify:

         ; The following is for Epsons
         Init    "\e@"
         Term    ""

To set the line spacing to 8 lpi, some printers use ESC + 0:

         Spacing(8) "\e0"

Only those character pitches etc.  are usable with a specific printer that are specified in the definition file.  That is, to be able to use 6 lpi spacing, you'll have to include a definition for Spacing(6) in the printer definition file.

Environment
***********

SPRSWITCHES

     This environment variable is designed to keep the user's default switch values for spr.  For example, if the system only has an Epson printer, you can define

              set sprswitches=/p=epson

     and have the Epson definitions used always without explicitly specifying so on the command line.

     The format of the string is the same as for the command line switches.  To have it set when the system starts, include the line in your \config.sys file.

     I'm using the following:

              /c=12/h="$f|$#|$d.$M.$Y $h.$m"/n=80/o=prn/p=fujitsu/r=76/s=8

     (There is no need to put any blanks between the switches.)  This means: character pitch 12 cpi, custom header, page length 80 lines, output directly to printer, use Fujitsu definitions, right margin at 76, and line spacing 8 lpi.

     The defaults given in SPRSWITCHES can of course be overridden from the command line.

SPRDEFPATH
     This is the search path for the printer definition (*.def) files. It has the same format as other path variables such as PATH and DPATH.  For example, to force spr to search for the definition files first in the current directory, and then C:\Etc\Printer directory, set

              set sprdefpath=.;C:\Etc\Printer

     Note:  if the current directory . isn't given, the current directory won't be searched at all.  However, if SPRDEFPATH is left undefined, only the current directory is searched.

Files
*****

         spr.cmd     the executable
         *.def       printer definition files

Bugs and limitations
********************

The section-separating bar | in the header- and footer-defining strings cannot be safely included in the headers and footers--currently the routine that sections the string is fairly straightforward and doesn't allow quoting the bar.  Additionally, only the first and the last bar are noticed, which means that in fact it is possible to insert bars in the headers or footers, but only in the centered section.  For example,

         "Left|Centered|This is also Centered|Right"

would center the text Centered|This is also Centered.

Version and copyrights
**********************

SOS spr v1.0

Copyright © SuperOscar Softwares, Tommi Nieminen 1994.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or at (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.