=head1	NAME

bmeps - Converter from PNG/JPEG/NetPBM to EPS and PDF

=head1	SYNOPSYS

  bmeps [I<options>] [I<inputfile> [I<outputfile>]]
  bmeps [I<options>] I<directory>
  bmeps -c -lI<name>
  bmeps -u
  bmeps -C
  bmeps -h
  bmeps -v

=head1	DESCRIPTION

Bmeps reads the specified input file, converts it and write output
to the specified file. If no output file name is specified bmeps
writes to standard output. If no input file name is specified bmeps reads
from standard input.

If bmeps is run on a directory it searches the directory for files it
can handle. A conversion is done for each file found, except when running
in make mode. In make mode bmeps checks for a conversion output file, a
conversion is run only if the output file does not yet exist or is not
up to date.

=head1	OPTIONS

=over	6

=item	B<-h>

shows a help text.

=item	B<-v>

shows version number and license conditions.

=item	B<-c> B<-l>I<name>

saves the configuration name as default configuration. If no configuration
is specified on a command line, bmeps uses either the default configuration
or the configuration specified in the EPSOUTPUT environment variable.
The environment variable has higher priority.

=item	B<-C>

shows the current configuration, can be used to view the permanent settings.

=item	B<-u>

removes the permanent settings (default configuration, make mode setting).

=item	B<-r> ...

ignores the permanent settings for one program invokation.

=item	B<-l>I<name>

chooses a configuration. Configuration entry overrides can be appended,
separated by comma.

=item	B<-o>I<name>B<=>I<value>

overrides one configuration entry.

=item	B<-f>I<number>[B<->I<number>]

chooses the frames to convert. By default bmeps converts all frames found
in the input file.

=item	B<-m>

=item	B<-t>I<type>

chooses the type of input data (when running as a pipe).

=item	B<-a>

chooses the output file name (if missing) automatically based on the
input file name.

=item	B<-A>

suppresses the notification about alpha channels transferred from
PNG or TIFF to PDF.

=item	B<-A->

enables the notification about alpha channels transferred from
PNT or TIFF to PDF.

B<-m->

activates/deactivates make mode.

=back

=head1	RETURN VALUE

On success bmeps returns exit code 0. Positive values are returned
on errors.

=head1	ERRORS AND DIAGNOSTICS

Error messages and diagnostic messages are printed to the standard
output stream and the error output stream.

=head1	FILES

=head2	Configuration file syntax

The configuration file consists of a list of sections, each section
defines one configuration. The section is started by the configuration
name in square brackets. The name of a ``parent'' configuration to
inherit from can be specified using a colon as separator.

The remaining lines of a section are key/value pairs to set the
configuration entries.

An example to set up a configuration named ``simple_configuration''
might look like:

  [simple_configuration:eps2]
  color = no
  encoding = ascii85:run-length

=head2	Configuration entries

Each configuration entry has a name assigned. I recommend to write the
full name in configuration files. The abbreviations should only be used
when typing commands on the command line.

The list below shows both full names and abbreviations.

=over	6

=item	output type = I<string>

o.t=I<string>

the output type, either ``ps'', ``pdf'' or ``bb''
(for LaTeX bounding boxes).

=item	level = I<string>

l=I<string>

the output level, either ``1'', ``2'' or ``3'' for EPS or
``1.2'', ``1.3'' or ``1.4'' for PDF.

=item	color = I<boolean>

c=I<boolen>

color mode (output is grayscaled if color mode is deactivated).

=item	dsc comments = I<boolean>

dsc.c=I<boolean>

dsc mode, DSC comments are written to PS/EPS output if dsc mode is enabled.

=item	encoding = I<list>

e=I<list>

list of allowed encoding and compression mechanisms. Items in the list
are separated by colon, abbreviations can be used,
i.e. ``a:r:d'' instead of ``ascii85:run-length:dct''.

The following encodings can be used:

=over	12

=item	ascii85

ASCII85-Encoding. If ASCII85-encoding is disabled bmeps uses
ASCII-Hex-encoding.

=item	run-length

run-length encoding.

=item	flate

flate compression (from zlib).

=item	dct

DCT encoding. Bmeps does not DCT-encode data itself, it lets DCT-encoded
data from JPEG files pass through if some tests on the JPEG file
were successfully.

=back

Note: The usable compression and encoding mechanisms depend on the PS level.

=item	mix = I<boolean>

m=I<boolean>

background color mixing. If the input image contains an alpha channel
the foreground color specified for the pixel is mixed against the
background color. Alpha data is used as foreground opacity.

=item	background = I<rgb-triple>

b=I<rgb-triple>

default background color. This color is used as background color if the
input image does not contain background color information.

=item	always use default background = I<boolean>

a.u.d.b=I<boolean>

flag, ignores the background color information from input file,
the default background is always used.

=item	create image mask = I<boolean>

c.i.m=I<boolean>

flag, uses input alpha channel to create an image mask.

=item	image mask trigger level = I<numeric>

i.m.t.l=I<numeric>

the trigger level to convert alpha data to image mask. Must be in
the range [0;1].

=item	transfer alpha channel = I<boolean>

t.a.c=I<boolean>

flag, transfers alpha data from input to output. This is only possible
when creating PDF-1.4 output. Alpha data transfer deactivates
mixing and image mask creation.

=item	interpolate = I<boolean>

i=I<boolean>

image interpolation flag in output.

=item	jpeg interpolate = I<boolean>

j.i=I<boolean>

enables interpolation also when passing-through DCT encoded data from JPEG
files.

=item	use resolution chunk = I<boolean>

u.r.c=I<boolean>

uses image resolution data from input to resize output.

=item	media size = I<media>

m.s=I<media>

the paper size to fit the image:

=over	12

=item	name, ``A3'', ``A4'', ``A5'', ``B4'', ``B5'', ``Letter'', ``Legal'',
``Tabloid'', ``Ledger'', ``Statement'', ``Executive'', ``Folio'', ``Quarto''
or ``10x14''.

=item	four numeric values x0, y0, x1 and y1 to specify the bounding box.

=item	eight numeric values bbx0, bby0, bbx1, bby1, ix0, iy0, ix1 and iy1.
The bb...-values specify the bounding box, the i...-rectangle is used
to place the image. This allows to reserve some border on the paper.

=back

=item	pdf fit = I<pdf-zoom>

p.f=I<pdf-zoom>

initial view, ``width'', ``height'' or ``page''.

=item	draft = I<boolean>

d=I<boolean>

draft mode, draw a placeholder rectangle only.

=item	showpage = I<boolean>

sh=I<boolean>

activates/deactivates showpage operator in output.

=item	operator dictionary = I<boolean>

o.d=I<boolean>

use dictionary argument for image operator or multiple plain arguments.

=item	separated dictionary = I<boolean>

s.d=I<boolean>

creates a separated dictionary for definitions in the bmeps output.
This preserves existing dicionary entries from the enclosing document
from being overwritten accidently.

=item	vmreclaim = I<boolean>

v=I<boolean>

writes ``1 vmreclaim'' to output to suggest a garbage collection.

=item	jfif sof set = I<list>

j.s.s=I<list>

specifies the allowed SOF_n markers in DCT encoded data,
i.e. ``0:1'' to allow SOF_0 and SOF_1.

=back

=head2	Configuration example

  [copy_of_ps2]
  output type			= ps
  level				= 2
  interpolate			= yes
  color				= yes
  multiple data sources		= yes
  dsc comments			= yes
  encoding			= ascii85:run-length:dct
  mix				= yes
  background			= 1.0:1.0:1.0
  always use default background	= yes
  create image mask		= no
  image mask trigger level	= 0.000001
  transfer alpha channel		= no
  showpage			= no
  operator dictionary		= yes
  separated dictionary		= yes
  vmreclaim			= no
  draft				= no
  jfif sof set			= 0:1
  jpeg interpolate		= no
  use resolution chunk		= no
  # No media size specified -> 1 pixel = 1 PS point
  # media size
  # No PDF zoom factor, we create PS output
  # pdf fit

=head1	EXAMPLES

=over	6

=item	Create a new default configuration to produce PS/EPS level 2 images
for a grayscaled printer:

  bmeps -c -leps2,color=no

=item	Convert inpug.png to output.eps using the default configuration:

  bmeps input.png output.eps

=item	Convert input.png to output.pdf

  bmeps -lpdf input.png output.pdf

=item	Convert all processable bitmap image files in the current directory:

  bmeps .

=item	Create bounding box files for all processable bitmap image files in
the current directory:

  bmeps -lbb .

=item	Convert a TIFF file created by a fax gateway to PDF for more
convenient viewing:

  bmeps -lfaxpdf input.tiff output.pdf

=back

=head1	RESTRICTIONS

Only TIFF files which can be read using the TIFFReadRGBAImage() function
from the libtiff library can be used.

A self-made analysis function is used to test whether or not a JPEG file
can be used directly as DCT encoded data.
If this function fails the JPEG image is decoded using the jpeglib
library, output is encoded using run-length, flate and ASCII85/ASCII-Hex
encoding.

=head1	SEE ALSO

http://dktools.sourceforge.net/bmeps.html

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2001-2006, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=head1	LAST MODIFICATION

2006-11-25

