=head1 NAME

gspl-plist - display printer list

=head1 SYNOPSIS

B<gspl-plist>
[ I<-options> ]
[ I<printer> ... ]

=head1 DESCRIPTION

B<gspl-plist> generates a list of the printers, with their current status,
on the B<GNUspool> printer lists, including those on remote machines,
on standard output. Each line of the output corresponds to a single
printer, and by default the output is generally similar to the default
format of the printers screen of the gspl-pq(1) command.

Various options allow the user to control the output in various ways
as described below.

The output can be restricted to one or more named printers by listing
them on the command line.

The default output of B<gspl-plist> looks like the following

 ljet       lp    a4      idle
 epson      tty15 invoice halted
 blue:epson lp    invoice idle

Printer names for printers on remote machines are prefixed as shown
by the machine name and a colon. The output is displayed in the
minimum width to let each column line up as shown, with fields
separated by spaces.

The output format and types of information displayed can be redefined
using the B<-F> option.

=head1 OPTIONS

=for man
Note that the order of treatment, letters and keywords described below
may be modified by editing the file \fIrest.help\fR \-
see \fIspsyntax\fR\|(5).

The environment variable on which options are supplied is C<GSPL_PLIST> and the
environment variable to specify the help file is C<SPRESTCONF>.

=over 4

=item -? or +explain or +help

causes a summary of the other options to be displayed without taking
further action.

=item -C I<classcode> or +classcode I<classcode>

list only printers which match (have at least one bit in common with)
the specified I<classcode>. This is reduced (I<and>ed) with) to a
subset of the user's default classcode unless the user has I<override
class> privilege).

=item -D or +default-format

revert to default format. This overrides any preceding B<-F> option.

=item -F I<string> or +format I<string>

Specify user defined output format. The	I<string> argument contains
characters to be printed and symbols representing the required data
fields. This option overrides and preceding B<-D> option, and is
itself overridden by a following B<-D> option.

=for html
<P>See <a href="#Gspl-Plist_format">the section on format codes</a> for
details of the format code sequences.</P>

=for man
See the section on format codes below for details of the format code
sequences.

=item -H or +header

generate a header for each column of the output according to the field
displayed there. The headers are taken from the message file, by
default F<rest.help>, which may be adjusted as
required.
 
=item -l or +local-only

include only printers local to the host on which the B<gspl-plist> command
is run.

=item -N or +no-header

cancel the B<-H> option.

=item -q I<name> or +list-only I<name>

list only printers whose name matches I<name>.

I<name> may be a pattern with wild cards matched in a similar fashion
to the shell, or a list of comma-separated alternatives.

	-q 'a*'

displays printers whose names start with C<a>

	-q '[p-t]*,*[!h-m]'

displays printers whose names start with C<p> to C<t> or end with
anything other than C<h> to C<m>.

To cancel this argument, give a single B<-> sign as I<name>.

=item -r or +remotes

include printers on the local and connected hosts, canceling B<-l>

=item -S or +sort-ptrs

sort printers into order by host identifier and name.

=item -U or +no-sort-ptrs

display printers in the order encountered (default).

=item +freeze-current

Save all the current options in a F<.gnuspool> file in the current
directory.

=item +freeze-home

Save all the current options in a F<.gnuspool> file in the user's home
directory.

=back

=head2 Format codes

The format string consists of a string containing the following character
sequences, which are replaced by the following job parameters. The
string may contain various other printing characters or spaces as
required.

Each column is padded on the right to the length of the longest
entry.

If a header is requested, the appropriate abbreviation is obtained
from the message file and inserted.

=over 4

=item %%

insert a single C<%> sign

=item %a

display C<AB!!> if printer has received an interrupt (abort print or
interrupt print) message.

=item %c

display class code.

=item %d

display device name, with angle brackets for network devices.

=item %e

display comment field.

=item %f

form type

=item %h

display C<heoj> if printer marked to halt at end of current job.

=item %i

process id of spd(8) process. 

=item %j

job number being printed (preceded by host name if not a local job).

=item %l

display C<localonly> if printer is marked for local jobs only.

=item %m

feedback message on standard error from network filter process.

=item %n

C<N/A> if printer is marked in need of running alignment routine.

=item %p

printer name.

=item %s

printer state, followed by a colon and the feedback message if
applicable.

=item %t

printer state only, no feedback message.

=item %u

user name of owner of printing job.

=item %y

minimum job size if applicable.

=item %z

maximum job size if applicable.

=back

Note that the various strings such as B<localonly> etc are read from the
message file also, so it is possible to modify them as required by the
user.

The default format is

	%p %d %f %s %j %u

=head1 FILES

F<~/.gnuspool>
configuration file (home directory)

F< .gnuspool>
configuration file (current directory)

F<rest.help>
message file

=head1 ENVIRONMENT

=over 4

=item GSPL_PLIST

space-separated options to override defaults.

=item SPRESTCONF

location of alternative help file.

=back

=head1 SEE ALSO

gspl-start(1),
gspl-pq(1),
gspl-qlist(1),
spsyntax(5),
gnuspool.conf(5),
gnuspool.hosts(5).

=head1 DIAGNOSTICS

Various diagnostics are read and printed as required from the message
file, by default F<rest.help>.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
## LocalWords:  gspl-plist gspl-pq
