vpp View and (selectively) Print PDF and PostScript
doc generated from the script with gendoc
bash script, version=3.10

Synopsis

vpp [options] [file]

Options: 

-h,--help
show a help message and exit
-H,--Help
show full documentation via less and exit
-V,--version
show version and exit
-b,--batch=X
run in batch using X as the print command
   --view
view the document (this is the default)
   --noview
do not view the document
   --viewer=X
specifies X as the pdf viewer to use
   --print
offer printing interaction (this is the default)
   --noprint
do not offer printing interaction
-p,--printer=X
print the printer named X
-v,--verbose
be verbose, keeping intermediate files
   --noverbose
don’t be verbose (this is the default)
-r,--rc=X
set rc file to X, must be the first option!
without the argument: don't read any rc-file

Arguments for short options are given without a separator, so you can write either --rc=myrc or -rmyrc.

Description

vpp is a Bash script designed to display PDF or PostScript documents (after converting them to PDF). Users can utilize the viewer to print the document directly or exit the viewer and use vpp's features to print selected pages as a single-sided or double-sided hardcopy, or as an A5 booklet. For more details, refer to the section titled "Page selection and other commands". Additionally, instead of printing, users can save their selections as PDF files.

If file is specified with a .ps or .pdf extension, vpp will directly use that file. Otherwise, vpp will search for file.pdf, file.ps, and file in that order, and will use the first existing file it finds. If no file is specified, vpp will read from standard input.

In all cases, the file type (PDF or PostScript) is determined by examining the first few characters of the file.

vpp requires both a viewer and a printer to function. For more information, see the section "Printers and viewers".

Exit value

vpp has four possible exit values: 

0
OK
1
error
2
edit, which is a signal to the calling program that a new
edit session is at order; this is used by mk.
3
re-compile; this is used by mk

Dependencies

pdfinfo
from poppler-utils
ps2pdf
from ghostscript
getopt
from util-linux
lpoptions
from cups-client
lpstat
from cups-client
texlog_extract
from texlive

Printers and viewers

For the operation of vpp, availability of printers and pdf viewers is important. Therefore, two associative arrays are defined: 
printers
an array available printers, where the keys are printer names
viewers
an array of available viewers, where the keys are viewer names
and the values are the corresponding commands, with arguments if any.

For each array, an index is set: printer for the printers array. viewer for the viewers array. printer points to the current printer, viewer to the current viewer.

You can inspect the contents of these arrays either with the short help option (-h or --help) or, when you are in vpp's command mode, with the ? command.

The printers array is automatically filled, using the lpstat and lpoptions commands.

The viewers array can be set in several ways:

Options

vpp comes with several options. Before evaluating any options, vpp will try to read the user rc-file, ~/.vpprc, where you can set defaults for most options, by assigning values to variable named after the long form of the options. For example, there are three ways to select the printer named k550:

These are the variables that can be set in ~/.vpprc: 

batch
(string) sets the --batch option
print
(true or false) sets printing interaction on or off
printer
(string) sets the --printer option
verbose
(true or false) sets the --verbose option
view
(true or false) sets viewing on or off
viewer
(string) set the viewer; arguments may be added; example:
viewer='acroread -geometry 1450x1150+0+0'
You should use a basename here, that is: the name of the viewer should contain no slashes, and it should be in your PATH.

--help
Prints synopsis and available printers and viewers, then quits.
--Help
Prints this documentation, via less.
--version
Prints version, then quits.
--verbose
Prints messages about the progress vpp is making. Can be reverted with --noverbose.
--rc=X
Read the specified X, instead of the default rc-file, ~/.vpprc. If this option is used, it must be used before any other options. If rc-file is an empty string, no rc-file will be read, thus skipping reading of ~/.vpprc.
--batch=X 
Prevents the --print option to interrogate the user about pages to be printed. Instead the document is printed according to the commands in the mandatory X. Also sets viewing off. Thus the command

   vpp --batch '2-3 x3' test.pdf

prints 3 copies of pages 2 and 3 of |test.pdf| without interaction

--print
Present the print prompt. This is the default. Can be reverted with --noprint, normally used to suppress the print prompt, for example when using vpp from other scripts that generate PDF or PostScript documents that have only to be displayed or printed without even being displayed.
--view
Run the file viewer. This is the default. Can be reverted with --noview, normally used to suppress starting the viewer, for example when using vpp from other scripts that generate PDF or PostScript documents that have only to be printed.
--printer=X
Specifies the printer X to be used instead of the system default printer. See the section Printers and viewers for more information.
--viewer=X
Specifies the viewer to use. This script defines an associative array viewers containing 4 viewers as follows:
viewers=([xp]=xpdf [ev]=evince [gv]=gv [ac]=acroread)
and the viewer is set to xp by default. However, you can define your own set of viewers in the ~/.vpprc file or in any rc file given with the --rc option. For example:
viewers=(
[xp]='xpdf -g 970x1050+0+0 -font 8x13bold -z page -cont'
[ac]='acroread -geometry 850x890+0+0'
[ev]='evince --fullscreen --presentation'
)
viewer=xp

Page selection and other commands

When you select the --print option, and you did not also use the --batch option, vpp interrogates you about the pages you want to print. To that end the following prompt appears: 

    vpp command (? for help):

upon typing ? or h, vpp displays examples of possible commands: 

  Command Examples:
    5       to print page 5
    5-      to print pages 5 through the end
    5-7     to print pages 5, 6 and 7
    7-5 ox  write the same pages, in reversed order, to x.pdf
    -7      to print the first 7 pages
    5-7 19- to print pages 5, 6, 7 and 19 through the end
    a       to print the whole document
    -       to print the whole document
    a x3    to print 3 copies of the document
    x3      the same
    5 x3    to print 3 copies of page 5
    s       print the whole document single-sided
    s 2-    print single-sided starting at page 2
    b       to print the whole document as an a5 size booklet
    b -12   to print the first 12 pages as an a5 size booklet
  Other commands:
    e       (if called by mk) edit the tex source and rerun mk
    c       (if called by mk) rerun mk
    v       (re)view the ps/pdf file or, with an argument, specify a viewer.
    w       list errors and warnings from the log file
    oxyz    send pdf output to file xyz.pdf instead of printer
    pxyz    print to printer xyz
    h       display this help
    ?       display this help
    q       quit

Sub-commands are separated with spaces or commas, so you can write either 5-7␣19␣ox or 5-7,19␣ox or 5-7,19,ox see the section Examples. With these descriptions, no further explanation should be necessary, except for the following:

Unless single-sided printing is selected with the s command, when the selected printer is a non-duplex printer, printing will be performed in two shifts, one for the front side and one for the back side. Between the shifts, another prompt appears: 

   printer ready? then turn pack over the long side and type enter (^D skips)

You will have to arrange your printer such that, with the printed sides up, the first page printed will be at the bottom of the stack, and the last page printed will be on top. Normally you will then have your output come out the front of your printer. Rotate it over the long side of the paper and feed it back into the printer for the other side to be printed.

When you use the oxyz subcommand, your selection will not be printed but instead will be saved in a PDF file named xyz.pdf. When you use a t or b selection, you will not, of course, be prompted to turn the paper stack. Instead, the odd and even pages of your selection will be saved in separate PDF files, xyz_odd.pdf and xyz_even.pdf.

Environment

Two environment variables may be useful in scripts using vpp: 
VPPOUTDIR
The directory where PDF files generated with the o command will
be saved; the default is the working directory.
VPPCHECKSAVED
If non-empty, vpp will check on exit that the inspected file
                has been saved into a pdf file and will issue a warning if
                it hasn’t. Useful if input is from standard input or a
                temporary file.

Examples

Since vpp can read from standard input, it can be used to print (parts of) manpages. This example (we assume a printer which cannot print double-sided) prints the full ls manpage first, followed by an A5 booklet of the first 8 pages: 

    $ man -t ls | vpp # (shows preview and is left with q)
    vpp command (? for help): a
    vpp command (? for help): b 1-8
    printer ready? then turn pack over the long side and type enter (^D skips)
    vpp command (? for help): q
    $

If you don’t need a preview, because you have seen the man page already, you can print it immediately as an A5 booklet with: 

    $ man -t ls | vpp --batch=b

or, to make an A5 booklet of the first 8 pages: 

    $ man -t ls |vpp --batch='-8 b'

If you just want to save a PDF copy of the man page in ls.pdf, you can say: 

    $ man -t ls |vpp -bols

Some PDF-documents, like the CVS manual (cvs.pdf), have their table of contents in their back instead of behind the title page. You can use vpp to rearrange such documents: 

    $ vpp --batch='1 2 153-160 3-152 ocvs' cvs.pdf

This overwrites the input document. Note that any links in the file will get broken, so that is only useful for documents that have to be printed. It would have been more sensible in this case to say: 

    $ vpp --batch=b,1,2,153-160,3-152 cvs

which prints the reordered document as an A5 booklet without replacing it. Note that we used comma's instead of spaces here, so we didn't need to quote the string.

You can even print or output page ranges in reverse order: 

    $ vpp --batch='12-1 otest' cvs.pdf

Author

Wybo Dekker

Copyright

Released under the GNU General Public License

Functions used:

check_viewers

description:
Check pdf viewers
The variable viewer is a key to the viewers array. Test viewers for executability.
globals  set:
viewer
globals used:
viewer viewers

extest

synopsis:
extest command [arg...]
description:
test if the command is available and executable
returns:
0 if the test is ok, 1 otherwise
synopsis:
src file
description:
source a file

handle_options

synopsis:
handle_options "$@"
description:
Handles the options
globals  set:
batch input mk print printer rcfile verbose view viewer
viewers writeto
globals used:
Myname Version batch viewer viewers printers

find_pdf

description:
Find the input and provide a pdf-copy;
If vpp had no file argument, standard input is used. If the argument has one of the extensions .pdf, .ps or .eps, or any uppercase variant, that file is used. Any other argument is used as such, if the file exists or, if not, a .pdf, PDF, PS, .ps, .eps or .EPS extension is added and the first existing file is used.
globals  set:
log tempdir
globals used:
input tempdir

pdfproperties

description:
Find page width, page height and the number of pages in the
input file
globals  set:
height pagecount width
globals used:
height pagecount width

printhelp

description:
Print help for vpp-commands and show which viewer and printer
are active.
globals used:
Blu Nor mk batch

ask_selection

synopsis:
ask_selection [arg...]
description:
Interact with user, specifying pages to be printed or exported
as pdf, or to re-view the pdf or (if called from mk) re-edit the tex-source. If called with arguments (caused by vpp’s --batch option) executes those.
globals  set:
booklet com copies output printer saved selection singlesided
viewer
globals used:
Mag Myname Nor Red VPPCHECKSAVED batch booklet com compileexit
viewer viewers

wait_for_printer

description:
Wait for user typing enter, signalling that the printer is
ready for next job. ^D instead skips further output.
returns:
0

printout

description:
Print selected pages or output them to pdf.
globals  set:
selection
globals used:
batch booklet output printer printers selection singlesided
writeto

find_printers

description:
Use lpstat to find any printers defined;
use lpoptions to detect if each printer is double-sided; create associative array printers with printer names as keys and set the values to true for double-sided printers and to false for single-sided ones. Issue a warning if no printers are found.
globals  set:
printer printers
globals used:
printer printers

list_printers

description:
List available printers and their sidedness; mark current
printer.
globals  set:
printers printer
globals used:
Blu Nor Red printers printer

list_viewers 

description:
List available viewers; mark current viewer
globals  set:
viewer viewers
globals used:
Blu Nor Red viewer viewers

clean_viewers 

description:
Remove unavailable viewers, no messages
globals  set:
viewer viewers
description:
run the current viewer
globals used:
verbose viewers viewer