=head1 NAME

gspl-pq - view spool queue interactively

=head1 SYNOPSIS

B<gspl-pq>
[ I<-options> ]

=head1 DESCRIPTION

B<gspl-pq> is a screen-oriented program which displays in real time the
current state of the B<GNUspool> spool queue and printer list,
refreshing the screen automatically as the queue changes or printer
state changes, and allowing the status of jobs on the queue to be
altered according to each user's permissions and privileges.

=for man
For more information about the details of the interactive commands,
please see the on-line help information, obtained by pressing ?
(although this may be changed on your site). This section focuses on
the command-line options which may be used to control the initial
display.

=for html
<P>Please see <a href="TxtRef-7.html#Sect_7_1">Chapter 7</a> for more
details of the interactive commands. This section focuses on the
command-line options which may be used to control the initial display.</P>

=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_PQ> and the
environment variable to specify the help file is C<SPQCONF>.

Certain commands available on-screen enable many of these options to
be changed and saved in configuration files.

=over 4

=item -? or +explain

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

=item -A or +no-confirm-abort

do not require confirmation of any jobs being aborted or deleted.

=item -a or +confirm-abort

require confirmation of all jobs being aborted or deleted. If a
previous B<-A> option has been given, this will restore the default of
only requiring confirmation for unprinted jobs. A further B<-a> option
in these circumstances will require confirmation in all cases.

=item -B or +no-help-box

put help messages in inverse video rather than in a box (default).

=item -b or +help-box

put help messages in a box rather than displaying inverse video.

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

list only jobs and printers which match (have at least one bit in
common with) the specified I<classcode>.

=item -D or +printed-jobs

restrict the jobs display to jobs which have been printed.

=item -d or +dont-care

cancel B<-j> or B<-p> options; the cursor will be in the jobs section
of the screen if there are any jobs to display and otherwise in the
printers section, unless the user does not have access to the printer
list.

=item -E or +page-counts

try to display page counts of jobs where applicable.

=item -e or +no-page-counts

do not try to display page counts in jobs, just the size in bytes.

=item -H or +keep-char-help

when displaying a help screen, interpret the next key press as a
command as well as clearing the help screen.

=item -h or +lose-char-help

discard whatever key press is made to clear a help screen.

=item -I or +include-all

display all jobs regardless of printer (but still, if appropriate,
restrict the display of printers).

=item -j or +jobs-screen

commence with cursor in jobs section of the screen.

=item -l or +local-only

display only jobs or printers local to the host on which B<gspl-pq> is
invoked.

=item -M or +no-error-box

put error messages in inverse video rather than in a box.

=item -m or +error-box

put error messages in a box rather than displaying inverse video.

=item -n or +follow-job

if a job or printer moves on the screen, try to follow it.

=item -P I<number> or +number-printers I<number>

set the number of lines on the printer section of the screen to
I<number>.

=item -p or +printer-screen

commence with cursor in printers section of the screen.

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

list only jobs whose destination includes, or printers whose name
matches I<name>.

I<name> may be a pattern with wild cards matched in a similar fashion
to the shell.

	-q 'a*'

displays jobs with printer names and printers whose names start with
C<a>.

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

displays jobs and printer 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 I<number> or +refresh-time I<number>

set the screen refresh time to I<number>. This only affects minor
changes such as the current page count. Addition or deletion of jobs
etc count as major changes and will cause an immediate screen refresh.

=item -r or +remotes

display jobs or printers on all attached hosts.

=item -S or +sort-ptrs

sort printers into order by host identifier and name.

=item -s or +keep-cursor

if a job or printer moves on the screen, try to preserve the relative
position of the cursor on the screen rather than following the job or
variable.

=item -t I<pattern> or +just-title I<pattern>

Restrict the display to jobs whose title matches the I<pattern> specified.

The pattern may be a pattern with shell-like wild cards as in the
description of the B<-q> parameter.

=item -U or +no-sort-ptrs

display printers in the order encountered (default).

=item -u I<user> or +just-user I<user>

Restrict the display to jobs owned by the I<user> specified.

The user name may be a pattern with shell-like wild cards as in the
description of the B<-q> parameter.

=item -Y or +all-jobs

cancel the display restrictions of B<-y> or B<-D>.

=item -y or +unprinted-jobs

restrict the jobs display to jobs which have not been printed.

=item -Z or +no-include-null

when listing jobs and printers restricted by a B<-q> argument, do not
include jobs without a destination printer.

=item -z or +include-null

when listing jobs and printers restricted by a B<-q> argument, include
jobs without a destination printer. 

=back

=head1 FILES

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

F<.gnuspool>
configuration file (current directory)

F<spq.help>
message file

F<gnuspoolptrs>
printers directory

F<spshed_reps>
error log file

=head1 ENVIRONMENT

=over 4

=item GSPL_PQ

space-separated options to override defaults.

=item SPQCONF

path name of alternative message file.

=back

=head1 SEE ALSO

gspl-pr(1),
gspl-user(1),
gspl-qdel(1),
gspl-qchange(1),
gspl-qlist(1),
gspl-plist(1),
gnuspool.conf(5),
gnuspool.hosts(5).

=head1 DIAGNOSTICS

Various diagnostics are read as required from the message file
F<spq.help>. In most cases (unless something drastic
happens) these are displayed on the screen.

Messages about key conflicts are probably because entries in your
I<terminfo> file contain duplications. Please see the I<GNUspool
Installation Guide>.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

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