Provided by: texlive-extra-utils_2023.20230613-2_all bug

NAME

       pdfxup - n-up tool with reduced margins

SYNOPSIS

       pdfxup [OPTIONS] [FILE]

DESCRIPTION

       pdfxup  creates a PDF document where each page is obtained by combining several pages of a
       PDF file given as output. The important feature of pdfxup, compared to  similar  programs,
       is  that  it tries to compute the (global) bounding box of the input PDF file, in order to
       remove the margins and to keep the text only. Instead of having the font size divided by 2
       (for  the case of 2-up output), in some case you may end up with almost the same font size
       as in the original document (as is the case for a default 'article' document  produced  by
       LaTeX).

       pdfxup  uses  ghostscript for computing the maximal bounding box of (some of) the pages of
       the document, and then uses pdflatex (with graphicx package) in order to produce  the  new
       document.

OPTIONS

       pdfxup accepts numerous options. The most important ones are:

       -x m, --columns m
              sets the number of columns of the output file (default 2);

       -y n, --rows n
              sets the number of lines of the output file (default 1);

       -nup mxn, --nup mxn
              sets the number of rows and columns of the output file (default 2x1);

       -l (0|1), --landscape, --portrait
              sets orientation of paper (of final document);

       -cf file, --config  file, --mode  file
              reads  file  (with extension .xup) and uses options defined in that file (see below
              for details about .xup files).  All options are processed in the order  the  appear
              on  the  command-line,  so  that  it  is  possible to modify the options set in the
              configuration file (and it is even possible to include several configuration files,
              the later one overwriting the options set by the previous ones).  Files are looked-
              up using kpsewhich (if available).

       -b (le|se), --booklet (le|se)
              configure for printing as a booklet. Value 'le' (which is the default value when -b
              is used with no argument) means that two-sided printing is in 'long-edge' mode (you
              turn from one page to the next along the long edge  of  the  paper).  'se'  is  the
              'short-edge' option.

       -c, --clip, -nc, --no-clip
              clip  (or  don't  clip)  pages to the computed bounding box. By default, content is
              clipped, to avoid overlap between neighbouring  pages.   With  --no-clip,  anything
              outside the bounding box will be displayed.

       -o file, --output file
              name of output file.

       -i     ask before overwriting output file.

       -ow    overwrite output file without asking.

       -ps s, --paper s
              sets  paper  size  (default  a4).  The name must be known by package geometry (more
              precisely, "<s>paper" should be defined in that package).

       -fw d, --framewidth d
              width of the frame around each page (default 0.4pt). Set to 0pt to have no frame at
              all.

       -tf [0|1], --tight-frame [0|1]
              whether  the  frame should be tight around the page, leaving horizontal white space
              outside the frame, or should be wide and span the whole available width.

       -im d, --innermargins d
              inner margin between frame and page (default 5pt).

       -m d, --margins d
              margin of pages of the new document (default 5pt).

       -is d, --intspaces d
              space between different pages (default 1pt).

       -p list, --pages list
              only consider sublist of pages of input document. List is a comma-separated list of
              pages  or  ranges pages of the form a-b; a can be omitted to start from first page,
              and b can be omitted to end at the last page.  Therefore,  "-p  -"  (which  is  the
              default)  includes  all  pages.  Also allows modulo, so that "-p 0%2" would include
              only even-numbered pages.

       -bb list, --bb list
              only consider sublist of pages of input document for computing bounding box.

       -nobb list, --no-bb list
              omit list of pages of input document from computation of bounding box.

       -g, --get-bb
              only compute (and output) bounding box. Will not produce any output file.

       -kbb, --keep-bb
              do not compute bounding box, preserve current margins.

       -s x y W H, --set-bb x y W H
              set the bounding box to the given values. Values are in pt; the first two  elements
              correspond  to  the  lower  left corner, while the last two represent the width and
              height of the part to be displayed.

       -w file, --watermark file
              use file as background watermark. file can be any format accepted by pdflatex (e.g.
              png  or pdf). If file is a multipage PDF file, page n of the watermark file is used
              with page n of the input file, and the last page of the watermark file is  repeated
              if the input file has more pages.

       -wp p, --watermark-period p
              repeat the last p pages of the watermark file instead of only the last one.

       -d, --debug
              debug mode: keep intermediary files.

       -col, --column-mode, --vertical
              fill  in  pages  top-down  first  (instead  of the default left-to-right mode).  By
              default, pages are inserted from left to right, until the line is full;  with  this
              option, pages are inserted from top to bottom, until the column is full. See option
              -bal below for examples of both options.

       -row, --row-mode, --horizontal
              fill in pages left to right (which is the default mode).

       -bal, --balance-last
              balance last page: when using column mode, the pages are  filled  in  from  top  to
              bottom,  and  the  last  page  is  no exception. Still, it may be prefered that the
              columns in the last page remains "balanced", which is what  this  option  achieves.
              Symmetrically, in row mode, this option would balance the rows.
                               ---------                        ---------
              row, no-balance | 1  2  3 |  column, no-balance  | 1  4  7 |
              (default mode)  | 4  5  6 |                      | 2  5  8 |
                              | 7  8  9 |                      | 3  6  9 |
                               ---------                        ---------
                               ---------                        ---------
                              |10 11 12 |                      |10 13    |
                              |13 14    |                      |11 14    |
                              |         |                      |12       |
                               ---------                        ---------

                               ---------                        ---------
                 row, balance | 1  2  3 |     column, balance  | 1  4  7 |
                              | 4  5  6 |                      | 2  5  8 |
                              | 7  8  9 |                      | 3  6  9 |
                               ---------                        ---------
                               ---------                        ---------
                              |10 11    |                      |10 12 14 |
                              |12 13    |                      |11 13    |
                              |14       |                      |         |
                               ---------                        ---------

       -V [0-3], --verbose [0-3]
              select verbosity (default: 1).

       -q, --quiet
              run quietly (equiv. '-V 0').

       -v, --version
              print version number and exit.

       -h, --help
              print help message and exit.

CONFIGURATION FILES

       Configuration  files  (extension  .xup)  are  bash  scripts used to set some variables. If
       option "--config-file <file>" (or equivalent) is used, <file> is looked up with  kpsewhich
       first,  if  it  contains  no '/'. If kpsewhich does not find it, then pdfxup checks if the
       file exists (using 'test -e') before sourcing it (the PATH variable will not  be  used  to
       find it).

       The script should only set some internal variables of pdfxup, such as NB_ROWS, NB_COLUMNS,
       LANDSCAPE (to set up a predefined layout). It can be used to set the bounding box, but  it
       is  often  better  to  compute  it  on the first few pages of the document.  Here are some
       examples of lines that can be put in a .xup file:

       NB_COLUMNS=1
              set the number of columns to 1

       NB_ROWS=2
              set the number of rows to 2

       LANDSCAPE=0
              set portrait mode

       KEEP_ORIG_BBOX=1
              do not crop margins

       SET_BBOX="75 47 540 755"
              set bounding box: lower left=(75,47); upper right=(540,755)

       TIGHT_FRAME=1
              set tight frames around pages

       INNER_MARGINS=10pt
              set margin around each page (inside the frame) to 10pt

       INTERM_SPACES=10pt
              set space between pages to 10pt

       FRAME_WIDTH=2mm
              set frame width to 2mm

       Other available variables can be found in the setdefaultvalues function.

EXAMPLES

       # pdfxup file.pdf
              produces 2-up pdf file from file.pdf.

       # pdfxup -bb 1-4 file.pdf
              same behaviour, but computes the bounding box only using the first  4  pages  (this
              saves time when processing long documents).

       # pdfxup -b -o booklet.pdf file.pdf
              same behaviour, but creates a booklet (as booklet.pdf).

       # pdfxup -kbb -x1 -y2 -l0 beamer-frames.pdf
              arranges 2 beamer frames per page (not reducing margins).

       # pdfxup --mode beamer2 beamer-frames.pdf
              arranges PDF pages according to beamer2.xup configuration file.

       # pdfxup -kbb -x2 -y2 -l beamer-frames.pdf:1-12,15-19
              arranges  4  beamer frames per page (not reducing margins), including only frames 1
              to 12 and 15 to 19.

SEE ALSO

       gs(1), pdflatex(1)

AUTHOR

       Nicolas Markey (pdfxup@markey.fr)