Changes which rewrite 'lpc topq', and which add 'lpc bottomq'. These

reflect much valuable feedback from wollman.  More details on the new
'lpc topq' are in the log message for revision 1.2 of lpc/movejobs.c.

The previous implementation of 'lpc topq' is available as 'lpc xtopq',
in case there are any problems noticed in the new implementation.  If
there are no problems with this version, a later update will remove the
'lpc xtopq' command.

Reviewed by:	freebsd-print@bostonradio.org
MFC after:	6 days

1 files changed, 83 insertions, 4 deletions

diff --git a/usr.sbin/lpr/lpc/lpc.8 b/usr.sbin/lpr/lpc/lpc.8
index 8d62b3f..a9ce4cb 100644
--- a/usr.sbin/lpr/lpc/lpc.8
+++ b/usr.sbin/lpr/lpc/lpc.8
@@ -32,7 +32,7 @@
 .\"     @(#)lpc.8	8.5 (Berkeley) 4/28/95
 .\" $FreeBSD$
 .\"
-.Dd June 15, 2002
+.Dd July 16, 2002
 .Dt LPC 8
 .Os
 .Sh NAME
@@ -92,6 +92,18 @@ then disable printing (preventing new daemons from being started by
 .Xr lpr 1 )
 for the specified printers.
 .Pp
+.It Ic bottomq Ar printer Xo
+.Op Ar jobspec ...
+.Xc
+Take the specified jobs in the order specified and move them to the
+bottom of the printer queue.
+Each
+.Ar jobspec
+can match multiple print jobs.
+The full description of a
+.Ar jobspec
+is given below.
+.Pp
 .It Ic clean Brq Cm all | Ar printer
 Remove any temporary files, data files, and control files that cannot
 be printed (i.e., do not form a complete printer job)
@@ -188,16 +200,83 @@ command is a privileged command, while the
 command is not restricted.
 .Pp
 .It Ic topq Ar printer Xo
-.Op Ar jobnum ...
-.Op Ar user ...
+.Op Ar jobspec ...
 .Xc
-Place the jobs in the order listed at the top of the printer queue.
+Take the specified jobs in the order specified and move them to the
+top of the printer queue.
+Each
+.Ar jobspec
+can match multiple print jobs.
+The full description of a
+.Ar jobspec
+is given below.
 .Pp
 .It Ic up Brq Cm all | Ar printer
 Enable everything and start a new printer daemon.
 Undoes the effects of
 .Ic down .
 .El
+.Pp
+Commands such as
+.Ic topq
+and
+.Ic bottomq
+can take one or more
+.Ar jobspec
+to specify which jobs the command should operate on.
+A
+.Ar jobspec
+can be:
+.Bl -bullet
+.It
+a single job number, which will match all jobs in the printer's queue
+which have the same job number.  Eg:
+.Ar 17 ,
+.It
+a range of job numbers, which will match all jobs with a number between
+the starting and ending job numbers, inclusive.  Eg:
+.Ar 21-32 ,
+.It
+a specific userid, which will match all jobs which were sent by that
+user.  Eg:
+.Ar jones ,
+.It
+a host name, when prefixed by an `@', which will match all jobs in
+the queue which were sent from the given host.  Eg:
+.Ar @freebsd.org ,
+.It
+a job range and a userid, separated by a `:', which will match all jobs
+which both match the job range and were sent by the specified user.  Eg:
+.Ar jones:17
+or
+.Ar 21-32:jones ,
+.It
+a job range and/or a userid, followed by a host name, which will match
+all jobs which match all the specified criteria.  Eg:
+.Ar jones@freebsd.org
+or
+.Ar 21-32@freebsd.org
+or
+.Ar jones:17@freebsd.org .
+.El
+.Pp
+The values for userid and host name can also include pattern-matching
+characters, similar to the pattern matching done for filenames in
+most command shells.
+Note that if you enter a
+.Ic topq
+or
+.Ic bottomq
+command as parameters on the initial
+.Nm
+command, then the shell will expand any pattern-matching characters
+that it can (based on what files in finds in the current directory)
+before
+.Nm
+processes the command.
+In that case, any parameters which include pattern-matching characters
+should be enclosed in quotes, so that the shell will not try to
+expand them.
 .Sh FILES
 .Bl -tag -width /var/spool/*/lockx -compact
 .It Pa /etc/printcap