.\" Automatically generated by Pod::Man version 1.16 .\" Sun Sep 16 14:21:15 2001 .\" .\" Standard preamble: .\" ====================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Ip \" List item .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used .\" to do unbreakable dashes and therefore won't be available. \*(C` and .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and .\" index entries marked with X<> in POD. Of course, you'll have to process .\" the output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it .\" makes way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. .bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ====================================================================== .\" .IX Title "EPSMERGE 1" .TH EPSMERGE 1 "perl v5.6.1" "2001-08-31" "User Contributed Perl Documentation" .UC .SH "NAME" epsmerge \*(-- a program for merging encapsulated postscript files. .PP This file documents version 2.2.2 of epsmerge. .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBepsmerge\fR [\fIoption\fR \fIvalue\fR] [\fB\--\fR] \fIfile-1\fR \fIfile-2\fR ... .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBepsmerge\fR is a program that merges several \s-1EPS\s0 files into one big \s-1EPS\s0 file. The original files are untouched. (Unless your output file is also one of the input files; don't do that :\-) .PP \&\fBepsmerge\fR is provided \s-1AS\s0 \s-1IS\s0 copyrighted under the \s-1GNU\s0 \s-1GPL\s0. Be sure to read the copyright section if you do not know what this means. .SH "OPTIONS" .IX Header "OPTIONS" An \fIoption\fR is a string telling epsmerge how to behave; each option begins with '\-' (called short options) or '\-\-' (called long options). Usually, an option should be followed by a single \fIvalue\fR (could be a number, a string, or a filename or something else), but some options need not have any value (they will then take a default value) or could have more than one. .PP There \fImust\fR be a space or a '=' separating the option from its value. The value may not contain whitespaces (unless the entire value is quoted). .PP Short options are case sensitive (i.e., \fB\-O\fR is not equivalent to \fB\-o\fR), but the long ones are case insensitive (\fB\*(--orientation\fR is equivalent to \&\fB\*(--orIeNtAtIon\fR). .PP Note that if you \fIdon't\fR specify an option on the command line when invoking epsmerge, then the value in your configuration file will be used. Except if there isn't any specified in the configuration file (or there is no configuration file); then an internal default will be used. Most of the information about the options below also tells you what the internal default is. You can also get some of this information when you you give the \fB\-?\fR option to epsmerge. .PP Note also that a \fB\--\fR (two dashes) by itself signifies the end of the option list. You can use this, e.g., if you want to specify '\-' (standard input) as the first input file. (Or if the first input file is called '\-rf', cf. Larry Wall's comment :\-) .PP .Vb 2 \& Just don't create a file called -rf. :-) \& -- Larry Wall in <11393@jpl-devvax.JPL.NASA.GOV> .Ve \&\fBepsmerge\fR currently understands the following options: .Sh "Options: Version and help" .IX Subsection "Options: Version and help" \&\fB\-?\fR .PP \&\fB\-h\fR .PP \&\fB\*(--help\fR .PP Causes \fBepsmerge\fR to allege a hopefully useful arranged abridged epsmerge usage message barrage, and then stop. .PP \&\fB\-v\fR .PP \&\fB\*(--version\fR .PP Causes \fBepsmerge\fR to print a version string (one line) and then stop. .Sh "Options: general options" .IX Subsection "Options: general options" \&\fB\*(--font\fR .PP This option specifies the font to be used to print labels and headers (see below). The value should be a case-sensitive string. It is passed uncritically into the generated file, so please make sure that your postscript interpreter/printer knows the font. Default value is \&'Times-Roman'. .PP \&\fB\-b\fR .PP \&\fB\*(--header\fR .PP This option writes a header (which could be at the bottom of the page). See section the How to write labels entry elsewhere in this document for how to specify the header string. .PP \&\fB\-u\fR .PP \&\fB\*(--labels\fR .PP Use this option to print labels for each \s-1EPS\s0 file. See section the How to write labels entry elsewhere in this document for how to specify the label string. .PP \&\fB\-o\fR .PP \&\fB\*(--output-file\fR .PP This option tells \fBepsmerge\fR to write its output to the specified file. Otherwise, the default is to write to standard output. Which you can then pipe on to your favourite printer (but you may want to see the Examples of usage entry elsewhere in this document below). And the \fB\*(--print\fR switch. However, if you generate multiple files (see the How to generate multiple files entry elsewhere in this document) then the filename you specify will only be used to \fIderive\fR the names of the output files. .PP \&\fB\-O\fR .PP \&\fB\*(--orientation\fR .PP Orientation means that the paper should be turned 90 degrees. The value following should be `Landscape' or `Portrait', or just `L' or `P' (case unimportant). The default value is Portrait. .PP \&\fB\-r\fR .PP Landscape. Equivalent to \fB\*(--orientation=L\fR. .PP \&\fB\-R\fR .PP Portrait. Equivalent to \fB\*(--orientation=P\fR. .PP \&\fB\-p\fR .PP \&\fB\*(--paper\fR .PP Paper specifies the paper size. Normally for an \s-1EPS\s0 file the size of the bounding box doesn't really matter (since it will probably be rescaled anyway when included in some document). But if you want to send it to a printer then it matters. Default is A4 (this can easily be changed in the script, though), and the currently recognized sizes are: A2, A3, A4, A5, B4, B5, letter, tabloid, ledger, legal, and executive. See also '\-pw' and '\-ph'. .PP \&\fB\-ph\fR .PP \&\fB\*(--paper-height\fR .PP Specifies the height of the paper directly. Should be used with \fB\-pw\fR. As with all distances, the width may be given in postscript points, centimetres, millimetres, or inches. .PP \&\fB\-pw\fR .PP \&\fB\*(--paper-width\fR .PP Specifies the width of the paper directly. Should be used with \fB\-ph\fR. .PP \&\fB\-ps\fR .PP \&\fB\*(--postscript\fR .PP Causes epsmerge to produce a postscript file (non-encapsulated). The biggest difference is that a postscript file (unlike \s-1EPS\s0) can contain several pages, so if you format more than one page (see section the How to generate multiple files entry elsewhere in this document), you will get them all in one postscript file. This option automatically implies \fB\*(--print\fR. .PP \&\fB\*(--print\fR .PP This option can be useful when printing an \s-1EPS\s0 file directly; it causes the '%%EOF' \s-1DSC\s0 to be preceded with the otherwise illegal 'showpage' operator, which is necessary since the printers I know will otherwise happily ignore everything. You will still need to pipe the output to the printer yourself, though. .PP \&\fB\*(--script\fR .PP This option allows you to specify a Perl script that will generate a label for you, one for each label specifier (see the How to write labels entry elsewhere in this document) that contains the specifier letter \fBs\fR. The script should return a one line string (either as returned by the last statement, or by an explicit \&\fIreturn\fR statement). If you do not specify a script on the command line, then epsmerge will prompt you for a script every time it needs to format something with a label; if you just press return then it will take the last script also as the current script. Inside the script, the following variables are at your disposal: \f(CW$f\fR is the current filename, \f(CW$n\fR is the number of the current label, starting with the zeroth (if you specify both \fB\*(--header\fR and \fB\*(--labels\fR then the header label will be the last), and \f(CW$l\fR is the number of times the script has been run for the current label (again starting with zero). This means that if you specify, say, \fBsss\fR as the value to \fB\*(--labels\fR, then your script will be called three times for each label, with \f(CW$l\fR equal to, respectively, 0, 1, and 2 for each call. See the Examples of usage entry elsewhere in this document. Oh, and be sure that your script is enclosed in quotes if typed on the command line, just as you would when running \fBperl \-e\fR (in the configuration file just type the script as any normal perl program (block)). .PP \&\fB\*(--ignore-eof\fR .PP This option causes the reader to ignore the %%EOF \s-1DSC\s0 which normally marks the end of a postscript file. Default is to use them. .Sh "Options: formatting options, standard formatter" .IX Subsection "Options: formatting options, standard formatter" These options are the ones understood by the default formatter. This formatter places things in rows and columns of \fIcells\fR. Imagine each page as a matrix made of cells each of the same size, and normally (modulo the \fB\-prs\fR and \fB\-par\fR options, see below) images are formatted to fit each into one cell (in the order they are given on the command line, but see also the \fB\-rmo\fR option). .PP Option values that specify a distance may be specified in postscript points (1/72th of an inch), centimetres, millimetres, or inches, and they may be negative. Examples: '42', '0.1cm', '\-42mm', '3.6in'. Normally you would not type the quotes; note that there is no space between the number and the unit. For boolean options (true/false), the value is optional, but true values can be specified as 'yes', 'y', '1', \&'true', 't', whereas the false ones are 'no', 'n', '0', 'f', 'false', \&'nil', '""'. The default is (usually) true. .PP \&\fB\-x\fR .PP \&\fB\*(--columns\fR .PP The number following the \fB\-x\fR switch specifies how many cells you want in a row, or, if you will, how many columns you want. .PP \&\fB\-y\fR .PP \&\fB\*(--rows\fR .PP Like \fB\-x\fR, but how many cells you want in each column, i.e. how many rows you want. You may specify either, both, or none, of \fB\-x\fR and \&\fB\-y\fR; if you specify none then the formatter will make an (educated) guess. .PP \&\fB\*(--margin\fR .PP \&\fB\-lmar\fR .PP \&\fB\-rmar\fR .PP \&\fB\-tmar\fR .PP \&\fB\-bmar\fR .PP The \fB\*(--margin\fR option sets a default margin (its default is, in turn, 20 postscript points). However, the other switches can be used to override the default for, respectively, the left, right, top, and bottom margins. .PP \&\fB\-xcs\fR .PP X Cell Spacing. Says how much space you want between each cell in the horizontal direction. You may specify a negative value if you wish. The default value is 20 (postscript points). .PP \&\fB\-ycs\fR .PP Y Cell Spacing. Analogous to the \fB\-xcs\fR option (qv). .PP \&\fB\-rmo\fR .PP Row major order. If true (this is the default, too) then the cells will be set with \fIrows\fR first (starting with the first \s-1EPS\s0 file you specified, then the next, etc), filling out the top row first. If the value is false, then the \fIcolumns\fR will be set one at a time, starting with the leftmost. .PP \&\fB\*(--major\fR .PP Must be either \fB\*(--major=rows\fR (the default) or \fB\*(--major=columns\fR. The former is equivalent to \fB\-rmo=true\fR, and the latter equivalent to \&\fB\-rmo=false\fR. .PP \&\fB\-par\fR .PP Preserve Aspect Ratio. If true, then the formatter will preserve the aspect ratio of the cells by (if necessary) compressing them even further. .PP \&\fB\-prs\fR .PP Preserve Relative Size. If true, then the formatter will preserve the relative sizes of the cells by (if necessary) compressing them even further. .Sh "Formatting options, stacking formatter" .IX Subsection "Formatting options, stacking formatter" This formatter is a rather simple one which simply stacks its images in either the horizontal or the vertical direction (but currently not both). Images are scaled so that the sides where they meet have the same lengths. .PP \&\fB\*(--stack\fR .PP Boolean. This option activates the stacking formatter, rather than the default one. .PP \&\fB\-x\fR .PP Same as for the standard formatter; says to format cells horizontally. Note that if you want more pages with the stacked formatter, you should specify both \fB\-x\fR and \fB\-y\fR (one of which should be 1), e.g., .PP .Vb 1 \& epsmerge -o foo.ps -x 4 -y 1 file-1 [..] file-8 .Ve (This is a bug) .PP \&\fB\-y\fR .PP The moral equivalent of \fB\-x\fR (qv). .PP \&\fB\-cs\fR .PP Cell spacing. This tells how much distance there should be between two images. The default is zero, and it can be negative. .SH "How to write labels" .IX Header "How to write labels" Two options, namely the \fB\*(--header\fR and \fB\*(--labels\fR options, allow you to write a label for, respectively, the entire generated \s-1EPS\s0 file and for each included \s-1EPS\s0 file. The option (if present) should be followed by a string which specifies what to print as follows: .Ip "1" 4 .IX Item "1" The first letter should be `a', `t' or `b', stating that the labels should be written above (top) or below (bottom) the image of the \s-1EPS\s0 file. You may omit this letter; by default \fB\*(--labels\fR writes labels \fIbelow\fR its \s-1EPS\s0 file, and \fB\*(--header\fR writes its labels \fIabove\fR the \s-1EPS\s0 files (i.e., on top of the page). .Ip "2" 4 .IX Item "2" Each of the following letters specifies that the label should contain one line of information as follows: .Sp \&\fBd\fR: The letter `d' says to include the creation date for the \s-1EPS\s0 file. For the \fB\*(--header\fR option, this just means the time when epsmerge is run, written in standard (\s-1UNIX\s0) time format. For the \fB\*(--labels\fR option, this is read from the \s-1EPS\s0 file's \s-1DSC\s0 if it has one, otherwise epsmerge reads the last time the file was modified. .Sp \&\fBf\fR: The letter `f' says to write the filename (of the \s-1EPS\s0 file or the generated file). For the generated file, if you haven't given a filename (via the \fB\-o\fR option), `stdout' is written. .Sp \&\fBF\fR: The letter `F' does the same as `f' except that the file's extension (if present) is stripped. So if your file is called \fIfoo.eps\fR, only \fIfoo\fR is written. .Sp \&\fBi\fR: The letter `i' tells epsmerge to prompt you for a one line label (only if run interactively). If you want more than one line as a label, just specify as many `i's in your label string as you want. .Sp \&\fBs\fR: The letter `s' says that epsmerge should run your Perl script to generate a one line label. Normally you would specify the script with the \fB\*(--script\fR option (qv), but if you don't, epsmerge will prompt you for a script every time it wants one. If you type a script once and would like epsmerge to use it next time it prompts you, then just press return at the prompt. .Sp \&\fBT\fR: The letter `T' says to include the title of the \s-1EPS\s0 file (this is given in the \&\s-1EPS\s0 file's \s-1DSC\s0 \*(-- if not, it's ignored). .Sp Each of these letters gives you one \fIline\fR of labelling (or, if you are from the \s-1US\s0, labeling). .Sp If you omit \fIall\fR of these letters, then some default is assumed. .Ip "3" 4 .IX Item "3" As the final information in the label string you may write a number, specifying the required font size. The default for \fB\*(--labels\fR is 12, the default for \fB\*(--header\fR is 20. .SH "The configuration file" .IX Header "The configuration file" As of version 1.2.0, you can now write a configuration file specifying your favourite options and their values. Create a file called .epsmergerc and put it somewhere in Perl's include path (next to the .pm files would be good). Or you can put it in your home directory. Also, you can put it in the current working directory, and this will be checked first. This allows you to have a per-project configuration file, assuming that you keep each project in a separate directory. .PP Each line of the file may be: .Ip "1" 4 .IX Item "1" A blank line, or .Ip "2" 4 .IX Item "2" A comment line: these begin with a `#' character and the rest of the line will then be ignored (really; there is no backslash continuation), or .Ip "3" 4 .IX Item "3" A line consisting of \fIoption\fR=\fIvalue\fR or \fIoption\fR: \fIvalue\fR. The option is just the long or short option name with the leading '\-' or \&'\-\-' stripped off (this method was chosen to make it easier to remember), and the value should just be a value just like you would write it on the command line (except that there \fImust\fR be a value; for a boolean value you would have to write explicitly yes/true or no/false). .PP Here is an example of what could be written in an .epsmergerc file: .PP .Vb 7 \& # Sample epsmerge config file \& o=my_output_file.eps \& rmo = false \& paper = A3 \& lmar: 2cm \& rmar: 30mm \& script: '(' . chr( ord('a')+$n ) . ')' .Ve If epsmerge doesn't seem to do what you thought it should, take a look again at your configuration file. For example, if you redirect stdout, thinking that your data will go into a file: .PP .Vb 1 \& epsmerge file1.eps file2.eps > new_file.eps .Ve but you have forgotten about some \fBo=\fR in your config file, then epsmerge will write to the \fBo\fR file, leaving \fBnew_file.eps\fR empty. In this case, you should use the \fB\-o\fR switch. .Sh "Further configuration" .IX Subsection "Further configuration" There are a couple of other things you might want to configure when you install epsmerge. These are currently .Ip "1" 4 .IX Item "1" The default paper size. .Ip "2" 4 .IX Item "2" The filename-page separator, used to say which pages from a multi-page postscript file you want to use. See section the Using Postscript entry elsewhere in this document below. .PP These can be configured by editing the epsmerge file \fIepsmerge\fR; look for the section `User serviceable parts'. .SH "How to generate multiple files" .IX Header "How to generate multiple files" epsmerge can print multiple files as follows: if you call epsmerge with something like .PP \&\fBepsmerge\fR \fB\-x\fR \fIx\fR \fB\-y\fR \fIy\fR \fB\-o\fR foo.eps filea.eps fileb.eps ... .PP where the number of input files is greater than the product of \fIx\fR and \&\fIy\fR, then epsmerge will generate several output files. In the first file, epsmerge will format the first \fIxy\fR input files; the second output file will contain the next \fIxy\fR input files, etc. (As usual, if there are not enough input files to fill the last output file then some of the spaces will be blank.) Note that all files will be formatted with \fIexactly\fR the same options. .PP The filenames of the output files will be generated by the given filename (in the example \fBfoo.eps\fR) as follows: If less than 10 files are generated, then they will be named \fBfoo-0.eps\fR, \fBfoo-1.eps\fR, etc. If 10 or more but less than 100 files are generated, then they will be named \fBfoo-00.eps\fR, \fBfoo-01.eps\fR, etc. Thus the output files are generated in alphabetical order. And are thus easier to handle wholesale by the shell as \fBfoo-??.eps\fR. .PP Alternatively, if you use the \fB\*(--postscript\fR option, you will get a single postscript file with \fIxy\fR \s-1EPS\s0 files formatted on each page. .PP Unless specified otherwise, this will be decided by looking at the file's extension: if the file is called \fBfoo.eps\fR you get multi-file \&\s-1EPS\s0'es; if the file is called \fBfoo.ps\fR you get single-file multi-page (non-encapsulated) postscript. =head1 Examples of usage .PP These examples assume that you have set up an epsmerge script somewhere in your path. See the The Path entry elsewhere in this document below. .Ip "\(bu" 4 Format five \s-1EPS\s0 files into one: .Sp .Vb 1 \& epsmerge -o newfile.eps file-a.eps file-b.eps file-c.eps file-d.eps file-e.eps .Ve or let the shell do the job (remember: the shell is your \fIfriend\fR!) .Sp .Vb 1 \& epsmerge -o newfile.eps file-?.eps .Ve .Ip "\(bu" 4 Reformat a single \s-1EPS\s0 file to fit one A4 page with 1 centimetre margins everywhere and send it to the printer (note the pipe at the end): .Sp .Vb 1 \& epsmerge -lmar 1cm -rmar 1cm -tmar 1cm -bmar 1cm --print myfile.eps | lpr .Ve This time use default margins, but print in landscape mode on letter paper: .Sp .Vb 1 \& epsmerge -O L -paper letter --print y myfile.eps | lpr .Ve .Ip "\(bu" 4 Format a page with three \s-1EPS\s0 files in the first row and just two in the second: .Sp First method leaves a space in the lower right corner where the sixth cell should have been: .Sp .Vb 2 \& epsmerge -o myoutputfile.eps -x 3 -y 2 file-11.eps file-12.eps file-13.eps \e \& file-21.eps file-22.eps .Ve Second method uses \fBepsmerge\fR to create temporary files: .Sp .Vb 3 \& epsmerge -o tmp1.eps -x 3 -y 1 file-11.eps file-12.eps file-13.eps \& epsmerge -o tmp2.eps -x 2 -y 1 file-21.eps file-22.eps \& epsmerge -x 1 -y 2 -o myoutputfile.eps tmp1.eps tmp2.eps .Ve .Ip "\(bu" 4 For each included \s-1EPS\s0 file write below it its name with .eps extension stripped off, and creation date. The output file should have filename and creation date written above all the included \s-1EPS\s0 files. The font sizes should be 20 and 30, respectively: .Sp .Vb 1 \& epsmerge -o myoutput.eps --labels bFd20 --header tfd30 a.eps b.eps c.eps .Ve .Ip "\(bu" 4 I want to write my \s-1EPS\s0 files with labels (a), (b), (c), etc. .Sp .Vb 1 \& epsmerge -o myoutput.eps --labels s --script '"(" . chr( ord("a")+$n ) . ")"' a.eps b.eps c.eps d.eps .Ve (Note the single quotes preventing the \s-1UNIX\s0 shell from messing with the script. If you are not on a \s-1UNIX\s0 shell, consult your local system guru (possibly yourself) for how to prevent the shell from tampering with your data.) .Ip "\(bu" 4 I am confused about the variables available to my script. What do I do? .Sp .Vb 1 \& epsmerge -o myoutput.eps --labels sss --headers sss --script '"(\e$n,\e$l)=($n,$l)"' ?.eps .Ve where ?.eps is your favourite selection of simple \s-1EPS\s0 files. Note that the shell strips the outer single quotes, so the inner double quotes say to Perl: this is an interpolated string. Also try it without the \&\fB\*(--headers\fR switch. .Ip "\(bu" 4 I have ten \s-1EPS\s0 files, and I want them formatted to some files, each containing four input files. .Sp .Vb 1 \& epsmerge -o page.eps -x 2 -y 2 firstfile.eps [ ... ] tenthfile.eps .Ve This will generate the ouput files \fBpage-0.eps\fR (containing the first four input files), \fBpage-1.eps\fR (containing the next four), and \fBpage-2.eps\fR (containing the last two). .Sp Alternatively, generate a single postscript file: .Sp .Vb 1 \& epsmerge -o pages.ps -x 2 -y 2 -ps firstfile.eps [ ... ] tenthfile.eps .Ve .SH "Using Postscript" .IX Header "Using Postscript" As of version 1.2.4, epsmerge has support for reading non-encapsulated (i.e., consisting of several pages) postscript (provided that the postscript file has a bounding box \s-1DSC\s0). By default, it does that with a postscript file, i.e., if the file \fIwarp-drive.ps\fR contains eight pages, then it will get expanded as eight pages in your input. Example: .PP .Vb 1 \& epsmerge -o foo.ps -x 2 -y 2 warp-drive.ps .Ve will take the pages of the file \fIwarp-drive.ps\fR and reformat them into a postscript file with four of the original pages on each page. .PP However, you can pick out which pages you actually want, in any order you want. Example: if you write .PP .Vb 1 \& epsmerge -o foo.ps -x 2 -y 2 bar.eps eek.ps:3,1,5-9,4 moo.eps .Ve then epsmerge will generate a three page postscript file with four (two by two) images on each page; the first image will be \fIbar.eps\fR, the next three images on the first page will be pages 3, 1, and 5 of \&\fIeek.ps\fR. The second page will contain pages 6, 7, 8, and 9 of \&\fIeek.ps\fR. The third and final page will contain page 4 of \fIeek.ps\fR and \fImoo.eps\fR. .PP Observe that in the specification .PP .Vb 1 \& eek.ps:3,1,5-9,4 .Ve there is \fIno space\fR anywhere. The format is \fIfilename\fR followed by the \&\fIseparator\fR followed by a sequence of comma-separated numbers in which a dash between two numbers \fI5\-9\fR is interpreted as the range \fI5,6,7,8,9\fR. If the separator is not immediately followed by a sequence of integers as described, then it is interpreted as a part of the filename. You can also use a dollar sign to mean the last page. .PP The above example assumes that the \fIseparator\fR is the single character `:'. However, this might have been changed when epsmerge was installed (see section the Further customization entry elsewhere in this document for details). Type .PP .Vb 1 \& epsmerge -? .Ve displays the separator (along with lots of options and things). .SH "The Path" .IX Header "The Path" \&\fBepsmerge\fR is distributed as several files: the main file and several files with .pm extension (Perl modules). If you use \fBepsmerge\fR often, you may consider writing a script telling Perl where to find epsmerge. On a \s-1UNIX\s0 system your script could look like this (one line): .PP .Vb 1 \& /usr/bin/perl -I/home/foo/epsm/ /home/foo/epsm/epsmerge $@ .Ve assuming you unpacked epsmerge in the directory /home/foo/epsm and that \fIperl\fR is in /usr/bin. Make the script executable (with \fIchmod\fR) and put it in your path. If the script is called \fIepsmerge\fR then you can go to your favourite \s-1EPS\s0 directory and merge away by just writing \fIepsmerge\fR (plus all the options and filenames). .SH "Terminology and abbreviations" .IX Header "Terminology and abbreviations" \&\fBBounding Box\fR: Part of Adobe's \s-1DSC\s0 (qv). As far as epsmerge is concerned, this is the most important part of any (encapsulated or not) postscript file. .PP \&\fB\s-1DSC\s0\fR: Document Structuring Conventions. Adobe's \s-1DSC\s0 specify how an \s-1EPS\s0 file is formatted by requiring certain comments, all starting with %% and then a keyword. Example: '%%BoundingBox: 0 0 485 384'. .PP \&\fB\s-1EPS\s0\fR: Encapsulated Postscript. This is a file that contains postscript commands to draw a figure which may later be included in other postscript documents. The first line of an \s-1EPS\s0 file must look something like '%!PS-Adobe-3.0 \s-1EPSF-3\s0.0'. Observe that, unlike postscript files, an \s-1EPS\s0 file can only be \fIone\fR page. .PP \&\fBPerl\fR: Practical Extraction and Report Language. Or as its many fans will have it: Pathologically Eclectic Rubbish Lister. Chosen for portability; although developed for a \s-1UNIX\s0 (Linux) system, \fBepsmerge\fR \fImight\fR run happily on many other platforms (currently it doesn't, though). Oh, and Perl is \fIfun\fR, too. See http://www.perl.com/ .SH "Author" .IX Header "Author" Jens G Jensen .SH "Warranty and Copyright" .IX Header "Warranty and Copyright" \&\fBepsmerge\fR is distributed under the \s-1GNU\s0 General Public Licence: http://www.gnu.org/copyleft/gpl.html .PP .Vb 4 \& This program is free software; you can redistribute it and/or modify \& it under the terms of the GNU General Public License as published by \& the Free Software Foundation; either version 2 of the License, or \& (at your option) any later version. .Ve .Vb 4 \& This program is distributed in the hope that it will be useful, \& but WITHOUT ANY WARRANTY; without even the implied warranty of \& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the \& GNU General Public License for more details. .Ve .SH "Bugs" .IX Header "Bugs" .Ip "\(bu" 4 Doesn't yet support page specific \s-1DSC\s0, like %%PageOrientation or %%Begin(End)PageSetup, etc. .Ip "\(bu" 4 Using the stack formatter with options from the other formatter is, cough, undefined. In fact, the stack formatter is a bit of a hack. Expect unusual behaviour occasionally. .Ip "\(bu" 4 A company called ``Microsoft'' produces a program, ``Word'', which, judging from the name, must be a text editor. It would appear, though, that this editor can also somehow produce \s-1EPS\s0 files. epsmerge does not read these files well, or at all. Not sure why. .SH "References" .IX Header "References" .SH "See also" .IX Header "See also" \&\fBa2ps\fR, the all-to-postscript program at http://www-inf.enst.fr/~demaille/a2ps/ .PP \&\fBpsutils\fR, Angus Duggan's postscript utility programs; in particular, there is a program for putting several postscript \fIpages\fR into one page (\fBpsnup\fR), and also a program for fitting one \s-1EPS\s0 file into a constrained box (\fBepsffit\fR), and \fBpsmerge\fR, a program for merging several postscript documents (created with the same application) into one document. .SH "Trademarks" .IX Header "Trademarks" \&\fBPostscript\fR is a trademark of Adobe Systems Inc.