


YUP(1)                                                     YUP(1)


NAME
       yup - print any number of page images on one physical page

SYNOPSIS
       yup [global/local opts] [file [ [local opts] file ... ] ]

DESCRIPTION
       yup is a PostScript utility designed to take any number of
       files  in  ASCII  or PostScript form and tile their output
       over a page, to  produce  a  number  of  scaled-down  page
       images  per  sheet,  and  reduce the total amount of paper
       used in printing.

       It is derived from an original version  of  psnup  by  the
       same  author, but has more features and options.  The name
       yup has been put forward  as  standing  for  `yet  unother
       psnup'  or  perhaps  `yup,  it'll  be  able to do what you
       want', since it is rather option overloaded.

       If no arguments are given, yup will use the  default  set-
       tings,  taking  standard  input as the file to be read and
       dumping output to the file yup.ps. If standard out is  not
       being redirected to another program or to a file, yup will
       print a list of the files it has completed.

       PostScript files are printed in an environment as  closely
       resembling  the  initial state of the printer as possible.
       yup tries to hide itself from the programs being run under
       it,  allowing  all  Level  1  PostScript programs that are
       passed through to execute correctly.

       ASCII text is printed using an internal line printer  rou-
       tine which is capable of tabs, backspaces, linefeeds, car-
       riage returns, form feeds and overstrike.  yup will  auto-
       detect ASCII files and print them using this routine, mak-
       ing  it  very  useful  in  converting   ASCII   files   to
       PostScript, in the same manner as a2ps (in fact the author
       has found that this is what yup  is  generally  used  for,
       rather than for it's PostScript capability).


OPTIONS
       There  are  a  large number of options that can be used to
       modify the output.  Most of these are flags which  can  be
       set  true  or  false,  depending  on the character used to
       denote them.  For example, +G turns on the option for gut-
       ters,  and  -G  turns  it off again.  All single character
       options have a longer multi-character counterpart, and  in
       this  case  ++gutters and --gutters can be used to perform
       the same task.

       Some options also take arguments, and in  these  cases  it
       does not matter whether the flag used to denote the option
       is + or -.  Again, using the example of gutters, you could



FSF                          15/02/95                           1





YUP(1)                                                     YUP(1)


       tell  yup  how big to make them with -g 5, --guttersize 5,
       +g 5 or ++guttersize 5 to make the gutters 5 points  wide.

       There  are two main groups of options, those whose effects
       are seen over all the input files (global) and those  that
       can  be used at any time on individual files (local).  All
       options may be present at any time, however  if  a  global
       option follows the first filename, it will be ignored.

       There is NO type checking done for options that take argu-
       ments, errors here will cause your printer to  reject  the
       file,  and  print nothing whatsoever (adding type checking
       code to the command line interface for yup would make  the
       program  bigger  and  more complicated -- the descriptions
       for  each  option  detail  the  argument  type   that   is
       expected).

       The  following list of options applies to the Unix and DOS
       perl versions of yup: users of the MS-DOS batch file  ver-
       sion  of  yup  should  consult the section entitled MS-DOS
       USERS, later in this manual entry.


       -V, --allavailable
              Use all available page area.  Any dead  space  left
              on the page after the allocation of spots, margins,
              titles and page numbers will be added to  the  spot
              image area.  This option allows the maximum area of
              the page to be used, however the  aspect  ratio  of
              the  page  is  generally  altered when the space is
              added.  Global flag, default true.

       -A, --alternate
              Alternate page margins.  When printing a file  with
              the  intention  of  binding  along  the left or top
              edge, this option makes sure that any page  numbers
              appear  on the outside edge, away from the binding.
              Page margins are also swapped, allowing a different
              amount  of  space to be allocated to inside or out-
              side edges of the page.  The  size  of  the  inside
              margin is defined by the size of the left margin in
              portrait prints and by the top margin in  landscape
              prints.  Global flag, default false.

       -b arg, --boxlinewidth arg
              Spot  box  line  width.  Specifies the thickness of
              the  lines  surrounding   each   spot   image,   in
              PostScript  points.   When set to 0, the PostScript
              default is to produce a line which is the  thinnest
              that the printer can produce, and hence will change
              depending on the resolution of the printer.  Global
              option, default 1 point.





FSF                          15/02/95                           2





YUP(1)                                                     YUP(1)


       -B, --boxspots
              Draw  a  box around each spot.  This option draws a
              box around each spot image, using the  current  box
              line  width, set with --boxlinewidth.  Global flag,
              default true.

       -C, --columnmajor
              Do column major output.  In normal use, the default
              printing  arrangement  is  to  have the spot images
              appear on the page in order from right to  left  in
              rows  advancing  down the page.  This option speci-
              fies that spot images appear in order from  top  to
              bottom in columns advancing to the right across the
              page.  Global flag, default false.

       -D, --duplex
              Print on both sides of page.  On printers that  are
              capable  of  printing  on two sides of a page, this
              option will turn on two-side printing of documents.
              As the format of the commands issued to the printer
              is not standard, this  particular  option  may  not
              work,  however  they  are reasonably universal, and
              have  been  found  to  work  on  several  printers.
              Global flag, default false.

       -J, --ejectpage
              Eject page at end of file.  Normally when a file is
              finished, the next is begun in  the  spot  position
              immediately  following  the  last,  with the result
              that files are printed one after the other with  no
              breaks   between  them.   This  option  forces  the
              printer to eject the current page at the end of the
              file  and  begin  the  next  file at the start of a
              clean page.  Local flag, default false.

       -E, --epsfile
              Treat file as an EPS file.  Encapsulated PostScript
              files  are  files  that have been put together with
              the intention of being included as  part  of  other
              PostScript  documents,  and  as  such  they may not
              print when sent to the printer by themselves.  This
              option  forces the files following it to be treated
              slightly differently to normal PostScript files, in
              that  they are assumed to contain none or one page.
              They are only assumed to have finished printing  at
              the  end of the file, no matter how many pages they
              have tried to print.  Files that  do  contain  more
              than  one  page  (such  as normal PostScript files)
              will invariably end up overlaying all their  output
              on  top  of  itself,  resulting  in a jumbled mess.
              Local flag, default false.

       -F, --filedate
              Use  file  date  in  spot  titles.   Normally,  the



FSF                          15/02/95                           3





YUP(1)                                                     YUP(1)


              command-line  interface  puts  the current printing
              date in the left title area of spot titles, if  the
              left  title  string  has not been set.  This option
              tells the command-line interface to place the  last
              modification date into the left title for each file
              being printed.  If the left title string is set  to
              something else between files, the setting will only
              affect the next file to be printed: the title  will
              revert  to  the modification date on the files fol-
              lowing.  Global flag, default false.

       -O, --flipallow
              Flip page sideways if necessary.   When  spots  are
              tiled  on a page, it is sometimes necessary to flip
              them by 90 degrees so that they fill the page  more
              efficiently.  When set true, this option allows the
              program to flip the spots sideways if it  finds  it
              necessary.  Global flag, default true.

       -K, --forcegstate
              Force  graphics  state.  One of the main complaints
              to be made of programs like psnup is that  they  do
              not  always handle the cases where files save their
              graphics state before issuing a page,  and  restore
              it  immediately  afterwards.   The major symptom of
              this behaviour is that the entire print for a  page
              appears  overlaid ontop of itself in the first spot
              position, indicating that  whatever  changes  psnup
              made  to  the  graphics state, they were ignored by
              the file being printed.  yup is able to  force  the
              graphics  state into the correct position with this
              option (at the expense of some  printing  speed  if
              the   file   makes  heavy  use  of  graphics  state
              save/restore commands).  Local flag, default false.

       -G, --gutters
              Use  gutters.  Gutters between spots generally help
              to delimit the edges of spot images.   This  option
              turns  on the generation of gutters, using the size
              given with the --guttersize option.   Global  flag,
              default true.

       -g arg, --guttersize arg
              Gutter  size.   Specifies  the  size  in PostScript
              points of the gutters to  be  placed  between  spot
              images.  Global option, default 5 points.

       -H, --hardbounds
              Make  sure  print  is  in  bounds.  Some PostScript
              files determine the size  of  the  page  they  have
              access  to by interrogating the printer to find out
              their clipping boundary, and assume that the entire
              area  within  this is theirs to modify at will.  In
              some cases this can be considered a benefit, but in



FSF                          15/02/95                           4





YUP(1)                                                     YUP(1)


              most  this  sort  of  action results in spot images
              being overwritten by  wayward  painting  operations
              from  other files.  This option makes sure that the
              clip path is set to the exact size of  the  current
              spot, making it impossible for a file to print out-
              side it.  Local flag, default true.

       -h, --help
              Print help messages.  When this option is called as
              --help,  the  command-line  interface prints a com-
              plete list of  the  options,  their  arguments  and
              whether  they  are  global  or  local in scope.  If
              called as ++help, the command-line interface prints
              out the meaning of each option it finds on the com-
              mand line as it encounters them, but  does  not  do
              anything.   In  this form the help option should be
              placed at  the  beginning  of  the  argument  list,
              before any other options or filenames.

       -L, --landscape
              Make  each  spot  landscape.   Applications such as
              spreadsheets or  graphing  programs  often  produce
              PostScript  output that is intended to be viewed in
              landscape mode, ie., at 90 degrees to a normal por-
              trait print.  As every file is usually treated as a
              simple portrait print, spot titles would appear  on
              the  the sides of any landscape print.  This option
              changes the orientation of the spots so  that  they
              are in landscape mode.  Global flag, default false.

       --lprboldgrey arg
              Grey value for line printer bold text.  On printers
              that do not have a bold font available, this option
              can be used to specify the grey value  to  use  for
              bold printing instead of a proper bold font, and so
              make it stand out from surrounding text.  Grey val-
              ues  range  from  0 (pure black) to 1 (pure white).
              Local option, default 0.

       -d arg, --lprcharhigh arg
              Characters high  for  line  printer.   This  option
              specifies  the  number of lines the line printer is
              expected to print per spot image.  If this  is  set
              to  zero,  a  number will be picked to best fit the
              values of --lprcharwide and --lprtextsize.  If  all
              of  these values are zero, this option is set to 66
              lines per page.  Local option, default 0.

       -e arg, --lprcharwide arg
              Characters wide  for  line  printer.   This  option
              specifies  the  number  of characters across a line
              the line printer will print  per  spot  image.   If
              this  is  set  to  zero, a number will be picked to
              best  fit   the   values   of   --lprcharhigh   and



FSF                          15/02/95                           5





YUP(1)                                                     YUP(1)


              --lprtextsize.  Local option, default 0.

       -Z, --lprcrlf
              Treat LF as CRLF in line printer.  On UNIX systems,
              an end-of-line character is denoted  by  control-J,
              otherwise known as linefeed, while MS-DOS uses con-
              trol-M (carriage-return) and linefeed  together  as
              end-of-line.   Normally  the  action  of  the  line
              printer is to move down a line when it encounters a
              linefeed  character, and not to position the cursor
              at the beginning of the new  line  (which  is  per-
              formed  by  the  carriage-return  character).  This
              option forces the line printer to treat a line-feed
              as  a  line-feed  and  carriage-return pair.  Local
              flag, default true.

       --lprfontbold arg
              Line printer bold font.  This is the font that  the
              line  printer will use to simulate overstruck char-
              acters.  It is normally the bold version  of  what-
              ever  is being used as the normal text font for the
              line printer.  Local option, default /Courier-Bold.

       -W, --lprlinewrap
              Wrap  lines  in  line  printer.  When a line is too
              long to fit into a page it can be  chopped  off  at
              the  point  where  it leaves the page, or it can be
              wrapped over onto the next line underneath the cur-
              rent.   This  option forces the line printer to put
              any extra characters onto  the  next  line  on  the
              page.  Local flag, default true.

       --lprmargin arg
              Margin  for  line  printer print.  Because there is
              normally a box around  a  spot  image  when  it  is
              printed,  it is sometimes difficult to see any text
              that has been printed right  to  the  edge  of  the
              spot.   This  option  specifies  a  margin to place
              aroun text in a spot to  bring  it  away  from  the
              edge.  Local option, default 6 points.

       --lprpagegrey arg
              Grey  value  for  line  printer  page.  This option
              allows the user to specify a  grey  value  for  the
              background  of the spot being printed with the line
              printer.  Grey values range from 0 (pure black)  to
              1 (pure white).  Local option, default 1.

       --lprtabsize arg
              Spaces  per  line  printer  tab.  The tab character
              (control-I) is mainly used  in  placing  text  into
              columns,  because it is usually interpreted in such
              a way that a tab character  will  place  the  print
              head  at the next tab stop, whichever that is.  Tab



FSF                          15/02/95                           6





YUP(1)                                                     YUP(1)


              stop spaces are normally the same size as 8  normal
              spaces,  but this option allows it to be changed to
              any other number.  Local option, default 8.

       --lprtextfont arg
              Font for line printer text.  This option  specifies
              the  font  to  be  used  for normal (non-bold) text
              printing inside the line-printer.  This should be a
              single-pitch font, so that the letter spacing looks
              correct on the page, rather than  a  variable-pitch
              font  such  as  Helvetica.   Local  option, default
              /Courier.

       --lprtextgrey arg
              Grey value for  line  printer  normal  text.   This
              option  allows the user to specify a grey value for
              the normal text of the spot being printed with  the
              line  printer.   Grey  values  range  from  0 (pure
              black) to 1 (pure white).  Local option, default 0.

       -z arg, --lprtextsize arg
              Font  size for line printer.  This option specifies
              the size of the characters the  line  printer  will
              print  in  a spot image.  If this is set to zero, a
              number will be picked to best  fit  the  values  of
              --lprcharhigh  and  --lprcharwide.   Local  option,
              default 0.

       --marginbottom arg
              Bottom  page  margin.   Specifies  the  number   of
              PostScript  points  that  will be left blank at the
              bottom of the page as a margin.   When  alternating
              pages  in landscape mode, this option specifies the
              amount of space to be left at the outside  edge  of
              the  page,  away  from the binding.  Global option,
              default 5 points.

       --marginleft arg
              Left  page  margin.   Specifies   the   number   of
              PostScript  points  that  will be left blank on the
              left side of the page as a margin.  When  alternat-
              ing  pages  in portrait mode, this option specifies
              the amount of space to be left on the  inside  edge
              of  the  page, next to the binding.  Global option,
              default 5 points.

       --marginright arg
              Right  page  margin.   Specifies  the   number   of
              PostScript  points  that  will be left blank on the
              right side of the page as a margin.  When alternat-
              ing  pages  in portrait mode, this option specifies
              the amount of space to be left at the outside  edge
              of the page, away from the binding.  Global option,
              default 5 points.



FSF                          15/02/95                           7





YUP(1)                                                     YUP(1)


       --margintop arg
              Top  page  margin.    Specifies   the   number   of
              PostScript  points  that  will be left blank at the
              top of the page  as  a  margin.   When  alternating
              pages  in landscape mode, this option specifies the
              amount of space to be left on the  inside  edge  of
              the  page,  next  to  the  binding.  Global option,
              default 5 points.

       -m arg, --mediatype arg
              Paper type to print on.  Many  PostScript  printers
              are  capable  of  printing on more than one size of
              paper.  This option  allows  the  user  to  specify
              which type of page media to print on.  Because this
              value must be a valid PostScript page type for  the
              printer  to  accept  the  print job, generally only
              `/letter', `/legal' or `/note' are acceptable  val-
              ues,  although  your printer may have other defined
              page types (such  as  `/a4'  or  `/halfletter'  for
              example).  Global option, default /letter.

       --numberboxsize arg
              Size of page number box.  This option specifies the
              amount of space on the page that is to be  reserved
              for  the  inclusion  of  the  page numbers for each
              sheet of paper printed.  This option has no  effect
              if  page  numbering  has  been  turned off.  Global
              option, default 16 points.

       --numberfont arg
              Font for page numbers.  Specifies the  font  to  be
              used when displaying the page numbers on each sheet
              of paper.  Any valid PostScript font name  that  is
              known  to  the printer is acceptable as an argument
              to this option.  Global option, default /Helvetica.

       -N, --numberpages
              Number each page.  This option enables the printing
              of page numbers on each sheet  of  printed  output.
              Page  numbers are normally printed in the top right
              corner of the page, unless the  --alternate  option
              has been enabled.  When this has been enabled, page
              numbers will appear on the outer edges of the page,
              on  the right for landscape printing and on the top
              for portrait printing.  Global flag, default  true.

       --numbersize arg
              Size for page number font.  Specifies the size that
              page numbers will be printed, in PostScript points.
              Global option, default 12 points.

       -S, --numberspots
              Number  each  spot.   As  with  page  numbers, this
              option causes the number of each spot to be printed



FSF                          15/02/95                           8





YUP(1)                                                     YUP(1)


              in the right title position for a spot if the right
              title has not been set and if spot titling has been
              enabled.  The spot numbers reflect the page numbers
              that the print would have had had it been  sent  to
              the  printer  directly  and  not through yup. These
              numbers reset themselves to 1 at the  beginning  of
              every file.  Global flag, default true.

       -o arg, --outfile arg
              Filename  to  dump  output into.  This option tells
              the command-line part of the program to  place  all
              output  into the file outfile. This file may be any
              file that is acceptable to  the  operating  system,
              except that it may not be the same as any file also
              appearing as an input file.  If yup is  being  used
              as  part  of  a  pipe or it's output is being redi-
              rected, this option has no effect.  Global  option,
              default yup.ps.

       -p arg, --pagecounter arg
              Page  counter.  This option allows direct access to
              the internal page counter of yup. This can be modi-
              fied at will between files to begin numbering pages
              from numbers other than one.  Local option, default
              1.

       -n arg, --pages arg
              Spots  per  page.  Sets the minimum number of spots
              that will appear on a page.  yup will look for  the
              tiling  pattern  that  will  yeild the largest size
              spots on the page, rotating them to fit  better  if
              necessary  (only  if  --flipallow  is set).  If the
              --strict flag has not been set, yup will also  look
              at --strictlevel more spots per page to see if they
              tile any better.  If they do, then it  will  choose
              those.   This option is overridden when user tiling
              has been specified.  Global option, default 2.

       -P, --program
              Treat files as PostScript.  This option forces  the
              files  following  to  be  treated  as  if  they are
              PostScript program files, rather  than  just  plain
              ASCII  text.   This  option  is  mainly  useful for
              PostScript programs that do not  begin  with  `%!'.
              Local flag, default false.

       -q, --quiet
              Suppress message printing.  When yup is in the pro-
              cess of putting an output file together, the normal
              response  is  to signify that it has completed each
              file by writing this information  to  the  console,
              along  with  the  output  file  name.  This option,
              whether called with + or - as the option flag, sup-
              presses  the output of these status messages.  When



FSF                          15/02/95                           9





YUP(1)                                                     YUP(1)


              yup is being used in a pipe or the output is  being
              redirected,   these   messages  are  suppressed  by
              default.  Global flag, default false.

       -R, --reverse
              Reverse spot order on page.  Some applications gen-
              erate  PostScript  files  in  which the page images
              appear in reverse order, in  that  they  print  the
              last  page  first.   This option reverses the order
              that spot images are placed on the  page,  allowing
              files  that  are  generated in this manner to print
              correctly.  This option also makes the  concept  of
              page  and  spot numbers meaningless, since there is
              no way of knowing what the total number  of  images
              will  be, so these facilities are disabled.  Global
              flag, default false.

       -s arg, --spotcounter arg
              Spot counter.  When spot titling is in effect,  and
              the  spots  are  being numbered, it is the value of
              this counter that is printed  in  the  right  title
              position  in  the  spot  title.   By modifying this
              counter, the starting spot number of the  file  can
              be set to any desired value.  Local option, default
              0.

       --spotcounter arg
              Spot position.  After the physical  page  has  been
              tiled, each spot position is referenced by an ordi-
              nal number ranging from 0 to one less than the num-
              ber of spots on the page.  These spot numbers go in
              order from the first spot on the page (usually  the
              top  left  spot) and progress down the page in rows
              moving from left to right (if column  major  output
              or  reversed  spot  options are enabled, this order
              will be different).  Setting the spot position man-
              ually  moves the spot that will begin the next file
              to the position nominated.  Local  option,  default
              0.

       -v arg, --spotshigh arg
              Number of spots high in user tile.  When specifying
              a user-defined tiling pattern, this option sets the
              number  of  spots  to  be  placed vertically in the
              tile.  Global option, default 1.

       -w arg, --spotswide arg
              Number of spots wide in user tile.  When specifying
              a user-defined tiling pattern, this option sets the
              number of spots to be placed  horizontally  in  the
              tile.  Global option, default 2.

       -Q, --strict
              Allow  only  n  spots  per  page.  If a user tiling



FSF                          15/02/95                          10





YUP(1)                                                     YUP(1)


              pattern is not in use, and yup is  being  asked  to
              find the best tile pattern to fit n spots per page,
              it will normally look not only at  that  number  of
              spots per page, but also at n + 1, n + 2 and so on,
              up  to  n   +   strictlevel   (defined   with   the
              --strictlevel  option).   This option forces yup to
              use only n spots per page.   Global  flag,  default
              false.

       -k arg, --strictlevel arg
              Tiling strictness level.  This option specifies how
              many extra  spots  per  page  are  acceptable  when
              determining a tiling pattern.  yup will try to find
              the tiling pattern  that  has  the  best  (largest)
              scale  for  each  spot,  and  occasionally,  better
              results are obtained by adding one or two spots  to
              the  tile  pattern  (try  seven  spots per page for
              instance: yup will find that a tile pattern of 4  x
              2  is  preferable  to  7 x 1, and will increase the
              spots  per  page  to  eight  accordingly.)   Global
              option, default 5.

       -T, --text
              Treat  files as ASCII text.  This option forces the
              files following to be treated as if they are  plain
              ASCII  text  files,  rather  than PostScript files.
              This option is mainly useful for  text  files  that
              begin  with  `%!' or for printing PostScript source
              code as text rather than executing it.  Local flag,
              default false.

       --titlebold arg
              Font  for  bold  titles.  This is the font used for
              the centre title when spot titling  is  in  effect.
              Global option, default /Helvetica-Bold.

       -a arg, --titleboldgrey arg
              Grey value for bold titles.  This is the grey value
              used for the centre title when spot titling  is  in
              effect.  Global option, default 0.

       -f arg, --titleboxgrey arg
              Grey value of title box.  This is the grey value of
              the background behind spot titles when spot titling
              is in effect.  Global option, default 0.8.

       --titleboxsize arg
              Size  of  spot  title  box.   This is the amount of
              space on the page allocated to the spot titles when
              spot  titling  is in use.  This value is referenced
              to the scale of the current spot:  a 12 point value
              here will be 12 points as it would appear on a spot
              that has been shrunk.  Global  option,  default  20
              points.



FSF                          15/02/95                          11





YUP(1)                                                     YUP(1)


       -c arg, --titlecentre arg
              Centre  title string.  When spots are being titled,
              this is the string that is  placed  in  the  centre
              title  area  of  the spot title.  If left blank yup
              will insert the current  filename  instead.   Local
              option, default `'.

       --titlefont arg
              Font  for normal titles.  This is the font used for
              the left and right titles when spot titling  is  in
              effect.  Global option, default /Helvetica.

       -t arg, --titlegrey arg
              Grey  value  of title text.  This is the grey value
              used for  the  left  and  right  titles  when  spot
              titling is in effect.  Global option, default 0.

       -l arg, --titleleft arg
              Left  title  string.   When spots are being titled,
              this is the string that is placed in the left title
              area  of  the  spot  title.  If left blank yup will
              insert a date, either the print date, or  the  last
              modification  time  of  the  current  file.   Local
              option, default `'.

       -r arg, --titleright arg
              Right title string.  When spots are  being  titled,
              this  is  the  string  that  is placed in the right
              title area of the spot title.  If  left  blank  and
              spots  are being numbered, yup will insert the cur-
              rent spot number in this position.   Local  option,
              default `'.

       -I, --titles
              Title each spot.  This flag enables each spot to be
              printed with a  title,  optionally  specifying  the
              filename,  print  date and page number of the spot.
              Global flag, default true.

       --titlesize arg
              Size for title  font.   The  title  font  must  fit
              within  the  title  box, specified with --titlebox.
              Global option, default 14 points.

       -X, --translate
              Translate   origin.    Some   PostScript   programs
              (notably  some  versions  of  dvips  output) do not
              position their output properly within a spot due to
              what yup must do to some of the operators they use.
              This option allows specific portions of a  page  to
              be  printed,  by  changing the origins of the spot.
              Local flag, default false.





FSF                          15/02/95                          12





YUP(1)                                                     YUP(1)


       -x arg, --translatex arg
              Translate factor x coordinate.  This is the  amount
              by  which  the  page  will  be shifted to the right
              within the spot.  Local option, default 0 points.

       -y arg, --translatey arg
              Translate factor y coordinate.  This is the  amount
              by  which  the  page  will be shifted up within the
              spot.  Local option, default 0 points.

       -Y, --tumble
              Print for  binding  on  top  edge.   On  PostScript
              printers with duplex printing capability, there may
              also be the option to print both sides of the  page
              with the same or opposite orientation.  Effectively
              a value of false produces output which can be bound
              on the left or right edge, and a value of true pro-
              duces output which can be bound on the top or  bot-
              tom edge.  Global flag, default false.

       -M, --usemedia
              Use  specified  paper  for print.  On printers with
              more than one type of page media (A4 and letter for
              example),  this option enables the use of the media
              type given in the --mediatype option.  Global flag,
              default false.

       -j arg, --userheight arg
              User  defined  spot height.  Specifies the vertical
              size of the user-defined page size.  Global option,
              default 792 points.

       --usersize
              Use   user   spot   dimensions.   When  printing  a
              PostScript file on a printer that does not have the
              page media specified in the file it will be printed
              at the  normal  size,  however  any  printing  that
              appears  beyond  the edges of the printed page will
              be lost.  On the other hand there may  be  a  print
              that would normally be extremely small when printed
              normally.  This option enables the use of the user-
              defined spot sizes, allowing any size of spot to be
              created and scaled to fit the current  media  size.
              Global flag, default false.

       -U, --usertile
              Use  user  tile specifications.  When undertaking a
              speciality printing job, it is sometimes  necessary
              to  override  the tiling pattern yup would normally
              impose.  For example, when printing seven spots  on
              a  page with the intention of having them appear as
              a tile of spots seven wide and one high,  yupoption
              forces  yup to only use the tile pattern defined by
              the user.  Global flag, default false.



FSF                          15/02/95                          13





YUP(1)                                                     YUP(1)


       -i arg, --userwidth arg
              User defined spot width.  Specifies the  horizontal
              size of the user-defined page size.  Global option,
              default 612 points.

ENVIRONMENT
       If yup is constantly in use with a set of options that  is
       not  the  same as the defaults, it can get tedious to have
       to specify an argument list all the time.  yup is able  to
       read the environment settings of the current shell for the
       variable YUPARGS, which will be taken as a list  of  argu-
       ments  to be prepended to whatever is on the command-line.
       Note that the MS-DOS batch-file version of yup handles the
       environment differently -- see the section entitled MS-DOS
       USERS).

MS-DOS USERS
       Those users of MS-DOS that do not have  access  to  a  DOS
       version  of  Perl  can  use  a  batch-file  version of yup
       instead, at the expense of a lot  of  the  Perl  version's
       useability.   As  the  batch-file  version  uses  the same
       PostScript part, there is no loss of functionality as  far
       as the printer is concerned.

       Note  that both Perl versions of yup behave in exactly the
       same manner, including the option delimiters (ie. the  use
       of  + and - instead of DOS' /) and their options were left
       in the DOS manual because the descriptions for each option
       are  relevant,  even  if  the functions are not accessable
       from the command line.  Instead,  the  batch-file  version
       uses the concept of `argument files' which contain all the
       information about option states in one file.  You can edit
       these argument files with a text editor to change the con-
       dition of any option.


   Synopsis
       yup-simp [-q] [-h] [-d yupdir] [-o outfile]  [-a  argfile]
       file [file..]

   Options
       Unlike  the  Perl  versions  of  yup,  the options for the
       batch-file must appear in the order they are given in  the
       line  above,  there must be a space between the option and
       it's argument,  and  each  option  is  considered  global.
       There are no options to modify the output.

       -q     Quiet.   This  flag tells the batch-file version of
              yup not to produce a banner message, nor any status
              message when it completes files.

       -h     Help.   Produces  a  short  listing  of the options
              available, and the arguments they take (if any).




FSF                          15/02/95                          14





YUP(1)                                                     YUP(1)


       -i arg Yup home directory.  This option is  used  to  tell
              the  batch-file  version  of yup where it's support
              files  are,  namely  the  PostScript  prologue  and
              trailer.   If not specified, yup will use the value
              of the YUPDIR environment variable, or if  that  is
              not  set, will set it to whatever is defined in the
              main batch file (usually `C:\YUP').  Changing  this
              value will also change the environment variable.

       -o arg Filename  to  dump  output into.  This option tells
              yup which file output should be placed in.  Because
              output  from batch files cannot be redirected under
              MS-DOS, output must always be placed in a file.  If
              not specified, yup will use the value of the YUPOUT
              environment variable, or if that is not  set,  will
              set  it  to  whatever  is defined in the main batch
              file (usually `YUP.PS').  Changing this value  will
              also change the environment variable.

       -a arg File  to  input  as  an argument file.  This option
              specifies which file is to be inserted as an  argu-
              ment  file  for the PostScript part of yup. Because
              there may be a number of different formats for out-
              put, this option was added to allow the creation of
              argument files, and then only specify the  argument
              file  for the format desired (to create a new argu-
              ment file, copy YUP-ARGS.ARG to  another  file  and
              modify  the  contents).  If not specified, yup will
              use the value of the YUPARG  environment  variable,
              or  if  that is not set, will set it to whatever is
              defined   in   the   main   batch   file   (usually
              `C:\YUP\YUP-DFLT.ARG').   Changing  this value will
              also change the environment variable.

   Environment
       The DOS Perl version of yup uses the  YUPARGS  environment
       variable  in  exactly the same manner as the UNIX version,
       however there are notable differences in  the  DOS  batch-
       file  version.   Most  importantly  every  variable in the
       batch-file version remains set after the completion of the
       batch-file,  and  hence  absorbs some environment space as
       well.  For that reason the number of variables used in the
       batch-file version has been kept to a minimum.

       To avoid conflict with any other environment settings, all
       of the batch-file variables begin  with  YUP.  Here  is  a
       short explanation of each of them.

       YUP    This  variable  is  used internally as a pointer to
              the current copy of yup that is being executed.  It
              is reset every time the batch-file is run, and can-
              not be set manually.

       YUPARG The location  of  the  batch-file  arguments  file.



FSF                          15/02/95                          15





YUP(1)                                                     YUP(1)


              This file is inserted between the PostScript header
              and procedure set and contains all the settings for
              a particular output format.  If not set, it will be
              set to whatever  is  in  the  batch  file  (usually
              YUPDIR\YUP-DFLT.PS).   This variable can be changed
              from the command line using the SET command or with
              the use of the -a option.

       YUPDIR The  directory  in which the batch-file should look
              for it's support files (the yup PostScript  header,
              procedure set and trailer files).  If this variable
              is not set, it will be set to whatever  is  in  the
              batch-file  (usually  `C:\YUP').  It can be changed
              from the shell using the DOS SET  command  or  with
              the use of the -d option.

       YUPOUT The  location  of the batch-file output file.  This
              is the  file  that  all  output  destined  for  the
              printer  is  collected.  If not set, it will be set
              to whatever is in the batch file (usually  YUP.PS).
              This  variable can be changed from the command line
              using the SET command or with the  use  of  the  -o
              option.

       YUPSHH This  variable  tells the batch-file whether or not
              it is being run  in  quiet  mode.   Initially  this
              starts  with  a  value  of  FALSE  but  this may be
              changed with the use of the -q option.  It is reset
              every execution and cannot be set manually.

   Examples
       All of these examples assume the default conditions as set
       up when released.

       To print an ASCII file whose name is `man.txt', two images
       to a page and boxed (the default), with results to be sent
       to a PostScript printer via LPT1:

              yup-simp -o lpt1 man.txt

       To print the PostScript source file `obfusc.ps'  as  ASCII
       text, with results dumped to the file `obfusc.yup':

              yup-simp -o obfusc.yup -a yup-text.arg obfusc.ps

       To  print  a  TeX PostScript file, with print to appear as
       four images per page:

              yup-simp -a yup-4pag.arg report.ps

       To print a program listing in three columns, with 96 char-
       acters per column, and no titles, to a file:

              yup-simp -o project.ps -a yup-list.arg project.c



FSF                          15/02/95                          16





YUP(1)                                                     YUP(1)


EXAMPLES
       All of these examples assume the default conditions as set
       up when released.  Note that these examples apply only  to
       the Perl versions of yup, for the DOS batch-file examples,
       see the MS-DOS USERS section of this manual.

       To print an ASCII file whose name is `man.txt', two images
       to  a page, dated and boxed (the default), with results to
       be sent to a PostScript printer via lpr:

              yup man.txt | lpr -Pps

       To print the PostScript source file `obfusc.ps'  as  ASCII
       text, with results dumped to the file `obfusc.yup':

              yup +T obfusc.ps > obfusc.yup

       To  print  a  TeX  .dvi file, with print to appear as four
       images per page, alternating pages,  and  a  centre  title
       string "Draft" (using dvips(1)):

              dvips -f < report.dvi | yup +An4 -c 'Draft'

       To print a program listing in three columns, with 96 char-
       acters per column, and no titles, to a file:

              yup -o project.ps +VQn 3 -Ie 96 project.c

WARNINGS
       PostScript programs that use up a lot  of  virtual  memory
       resources  in  the  printer may cause a VMerror.  In these
       situations it may be better to print  the  offending  file
       without  using yup, which is intended primarily for draft-
       ing of TeX and ASCII files.

       yup also changes the format of comments  internal  to  the
       PostScript file, making the output unsuitable for preview-
       ing by programs such as GhostScript.

AUTHOR
       yup was written by Malcolm Herbert (drol@rmit.edu.au).

EXTERNAL INFLUENCES
       Multi-byte characters can  be  used  in  the  contents  of
       files,  but because the PostScript internal to the printer
       may object or misinterpret it, it is not recommended.

       When printing ASCII files with different encoding (such as
       those  used  in  European  languages), accented characters
       will be printed incorrectly unless the  encoding  for  the
       font  used in the line printer routine is changed from the
       normal StandardEncoding encoding vector to something  like
       ISOLatin1Encoding.   Alternatively, there may be language-
       specific versions of the standard Courier  type-face  that



FSF                          15/02/95                          17





YUP(1)                                                     YUP(1)


       can  be  substituted in it's place using the --lprtextfont
       and --lprboldfont options (the actual font does  not  mat-
       ter, as long as it is a single-pitch font).

BUGS
       The PostScript code is too big.

       The line printer routine is too slow.

       Some  PostScript  operators  have  not been properly simu-
       lated, or have been disabled entirely, thereby making out-
       put behave badly in some cases.

       It is still possible for badly constructed PostScript pro-
       grams to break the setup  used  by  yup  in  the  printer.
       tiger.ps,   as   supplied   with   GhostScript  causes  an
       invalidrestore error when files are placed after  it.  (As
       it  is a demo program, yup should really be able to handle
       it.)

       The YUPARGS environment variable is added  without  regard
       to  whether  it  contains  strings  with spaces or not, or
       strings of any sort for that matter.


































FSF                          15/02/95                          18


