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 `y et u nother p snup' 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 settings, 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 routine which is capable of tabs, backspaces, linefeeds, carriage returns, form feeds and overstrike. yup will auto-detect ASCII files and print them using this routine, making 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 gutters, 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 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 arguments, 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).

-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 outside 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.

-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 specifies 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 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 following. 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 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 outside it. Local flag, default true.

-h, --help
    Print help messages. When this option is called as --help , the command-line interface prints a complete 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 command 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 portrait 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 values 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 --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 control-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 performed 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 characters. It is normally the bold version of whatever 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 current. 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 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 alternating 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 alternating 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.

--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 values, 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 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 redirected, 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 modified 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 process 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, suppresses the output of these status messages. When 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 generate 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 ordinal number ranging from 0 to one less than the number 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 manually 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 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.

-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 current 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.

-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 produces output which can be bound on the top or bottom 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, yup option forces yup to only use the tile pattern defined by the user. Global flag, default false.

-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 arguments to be prepended to whatever is on the command-line.

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, 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 characters 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 drafting of TeX and ASCII files.

yup also changes the format of comments internal to the PostScript file, making the output unsuitable for previewing 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 can be substituted in it's place using the --lprtextfont and --lprboldfont options (the actual font does not matter, 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 simulated, or have been disabled entirely, thereby making output behave badly in some cases.

It is still possible for badly constructed PostScript programs 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.