more manpages

1 files changed, 308 insertions, 0 deletions

diff --git a/sys/src/cmd/postscript/postio/postio.1.man b/sys/src/cmd/postscript/postio/postio.1.man
new file mode 100644
index 000000000..3075951b7
--- /dev/null
+++ b/sys/src/cmd/postscript/postio/postio.1.man
@@ -0,0 +1,308 @@
+.TH POSTIO 1 "DWB 3.2"
+.SH NAME
+.B postio
+\- serial interface for PostScript printers
+.SH SYNOPSIS
+\*(mBpostio\f1
+.OP \-l line
+.OP "" options []
+.OP "" files []
+.SH DESCRIPTION
+.B postio
+sends
+.I files
+to the PostScript printer attached to
+.IR line .
+If no
+.I files
+are specified the standard input is sent.
+The first group of
+.I options
+should be sufficient for most applications:
+.TP 0.75i
+.OP \-b speed
+Transmit data over
+.I line
+at baud rate
+.I speed.
+Recognized baud rates are 1200, 2400, 4800, 9600, and 19200.
+The default
+.I speed
+is 9600 baud.
+.TP
+.OP \-c
+Do not send
+.MR ^C s
+(interrupts) to the printer,
+which means
+.B postio
+does not force a busy printer into the idle state.
+.TP
+.OP \-l line
+Connect to printer attached to
+.IR line .
+In most cases there is no default and
+.B postio
+must be able to read and write
+.IR line .
+If
+.I line
+does not begin with
+.MW /
+it is treated as a Datakit destination.
+.TP
+.OP \-q
+Prevents status queries while
+.I files
+are being sent to the printer.
+When status queries are disabled a dummy message is appended
+to the log file before each block is transmitted.
+.TP
+.OP \-B num
+Set internal buffer size for reading and writing
+.I files
+to
+.I num
+bytes
+(default is 2048 bytes).
+.TP
+.OP \-D
+Enable debug mode.
+Guarantees that everything read on
+.I line
+will be added to the log file (standard error by default).
+.TP
+.OP \-L file
+Data received on
+.I line
+gets put in
+.IR file .
+The default log
+.I file
+is standard error.
+Printer or status messages that do not indicate a change in state
+are not normally written to
+.I file
+but can be forced out using the
+.OP \-D
+option.
+.TP
+.OP \-P string
+Send
+.I string
+to the printer before any of the input files.
+The default
+.I string
+is simple PostScript code that disables timeouts.
+.TP
+.OP \-R num
+Run
+.B postio
+as a single process if
+.I num
+is 1 or as separate read and write processes if
+.I num
+is 2.
+By default
+.B postio
+runs as a single process.
+.PP
+The next two
+.I options
+are provided for users who expect to run
+.B postio
+on their own.
+Neither is suitable for use in spooler interface
+programs:
+.TP 0.35i
+.OP \-i
+Run the program in interactive mode.
+Any
+.I files
+are sent first and followed by the standard input.
+Forces separate read and write processes
+and overrides many other options.
+To exit interactive mode use your interrupt or quit character.
+To get a friendly interactive connection with the printer type
+.MW executive
+on a line by itself.
+.TP
+.OP \-t
+Data received on
+.I line
+and not recognized as printer or status information is written to
+the standard output.
+Forces separate read and write processes.
+Convenient if you have a PostScript program that
+will be returning useful data to the host.
+.PP
+The last option is not generally recommended and should only
+be used if all else fails to provide a reliable connection:
+.TP 0.35i
+.OP \-S
+Slow the transmission of data to the printer.
+Severely limits throughput, runs as a single process,
+disables the
+.OP \-q
+option, limits the internal buffer size to 1024 bytes,
+can use an excessive amount of
+.SM CPU
+time, and does nothing in interactive mode.
+.PP
+Best performance is usually obtained by using
+a large internal buffer
+.OP -B "" ) (
+and by running the program as separate read and write processes
+.OP \-R2 "" ). (
+Inability to fork the additional process causes
+.B postio
+to continue as a single read/write process.
+When one process is used, only data sent to the printer is flow-controlled.
+.PP
+The options are not all mutually exclusive.
+The
+.OP \-i
+option always wins, selecting its own settings for whatever is
+needed to run interactive mode, independent of anything else
+found on the command line.
+Interactive mode runs as separate read and write processes
+and few of the other
+.I options
+accomplish anything in the presence of the
+.OP \-i
+option.
+The
+.OP \-t
+option needs a reliable two way connection to the printer and
+therefore tries to force separate read and write processes.
+The
+.OP \-S
+option relies on the status query mechanism, so
+.OP \-q
+is disabled and the program runs as a single process.
+.PP
+In most cases
+.B postio
+starts by making a connection to
+.I line
+and then attempts to force the printer into the
+.SM IDLE
+state by sending an appropriate sequence of
+.MW ^T
+(status query), 
+.MW ^C
+(interrupt), and
+.MW ^D
+(end of job) characters.
+When the printer goes
+.SM IDLE
+.I files
+are transmitted along with an occasional
+.MW ^T
+(unless the
+.OP \-q
+option was used).
+After all the
+.I files
+are sent the program waits until it is reasonably sure the
+job is complete.
+Printer generated error messages received at any time
+except while establishing the initial connection
+(or when running interactive mode) cause
+.B postio
+to exit with a non-zero status.
+In addition to being added to the log file, printer error messages
+are also echoed to standard error.
+.SH EXAMPLES
+Run as a single process at 9600 baud and send
+.I file1
+and
+.I file2
+to the printer attached to
+.MR /dev/tty01 :
+.EX
+postio -l /dev/tty01  \f2file1  file2
+.EE
+Same as above except two processes are used,
+the internal buffer is set to 4096 bytes,
+and data returned by the printer gets put in file
+.MR log :
+.EX
+postio -R2 -B4096 -l/dev/tty01 -Llog  \f2file1  file2
+.EE
+Establish an interactive connection with the printer at Datakit
+destination
+.MR my/printer :
+.EX
+postio -i -l my/printer
+.EE
+Send file
+.MW program
+to the printer connected to
+.MR /dev/tty22 ,
+recover any data in file
+.MR results ,
+and put log messages in file
+.MR log :
+.EX
+postio -t -l /dev/tty22 -L log program >results
+.EE
+.SH DIAGNOSTICS
+A 0 exit status is returned if the files ran successfully.
+System errors (e.g., ``can't open the line'') set the low order
+bit in the exit status, while PostScript errors set bit 1.
+An exit status of 2 usually means the printer
+detected a PostScript error in the input
+.IR files .
+.SH WARNINGS
+.PP
+The input
+.I files
+are handled as a single PostScript job.
+Sending several different jobs, each with their own internal
+end of job mark
+.RM ( ^D )
+is not guaranteed to work properly.
+.B postio
+may quit before all the jobs have completed and could be restarted
+before the last one finishes.
+.PP
+All the capabilities described above may not be available on every
+machine or even across the different versions of
+.SM UNIX
+that are currently supported by the program.
+For example, the code needed to connect to a Datakit destination may only
+work on System\ V and may require that the
+.SM DKHOST
+software package be available at compile time.
+.PP
+There may be no default
+.I line
+so using
+.OP \-l
+option is strongly recommended.
+If omitted
+.B postio
+may attempt to connect to the printer using the standard output.
+If Datakit is involved the
+.OP \-b
+may be ineffective and attempts by
+.B postio
+to flow control data in both directions may not work.
+The
+.OP \-q
+option can help if the printer is connected to \s-1RADIAN\s+1.
+The
+.OP \-S
+option is not generally recommended and should only be used if
+all else fails to establish a reliable connection.
+.SH SEE ALSO
+.BR buildtables (1),
+.BR dpost (1),
+.BR postdaisy (1),
+.BR postdmd (1),
+.BR postmd (1),
+.BR postprint (1),
+.BR postreverse (1),
+.BR posttek (1),
+.BR printfont (1)