=head1	NAME

fig2vect - Yet another Fig to vector converter

=head1	SYNOPSIS

fig2vect I<options> I<inputfile> I<outputfile>

fig2vect I<options> I<directory>

=head1	DESCRIPTION

The fig2vect program converts Fig images (created by i.e. XFig, jFig
or WinFig) to other vector formats (*.mp, *.eps, *.pdf, *.tex, *.svg).
Most output formats are intended for use with LaTeX.

=head1	OPTIONS

=over	6

=item	B<-v>

shows version information.

=item	B<-h>

shows a help text.

=item	B<-c> I<options>

configures the I<options> as permanent options.

=item	B<-u>

removes the permanent options (unconfigure).

=item	B<-r> I<options>

skips all permanent options (resets configuration to build-in
defaults) before processing the command line options.

=item	B<-C>

shows the permanent options.

=item	B<-l> I<language>

chooses a language configuration from the configuration file.

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

overrides a configuration setting.

=item	B<-m>

activates ``make'' behaviour when the program is run on a directory.

=item	B<-m->

deactivates ``make'' behaviour when the program is run on a directory.

=back

=head1	RETURN VALUE

The program returns exit code 0 on success or a positive exit code
on errors.

=head1	ERRORS AND DIAGNOSTICS

Error messages an diagnostics are written to log file, standard output
and standard error output depending on the preferences configured
for the fig2vect application.
The command line option

  --/log/stderr/level=debug

can be used for extended diagnostic messages to the standard error
stream.


=head1	EXAMPLES

  fig2vect -lmp input.fig output.mp

converts input.fig to output.mp

  fig2vect -lsvg input.fig.bz2 output.svg.gz

converts the bzip2-compressed input file input.fig.bz2 to the
gzip-compressed output file output.svg.gz

  fig2vect -lmp -m- .

converts all *.fig files in the current directory into corresponding
*.mp files, no modification time check is applied.

  fig2vect -lmp -m .

converts all *.fig files in the current directory into corresponding
*.mp files, a conversion is run only for those file pairs where the
*.fig file is newer than the *.mp file.

=head1	FILES

=head2	fig2vect.cfg

=head3	File structure

The configuration file fig2vect.cfg is used from either
$HOME/.defaults or from ${prefix}/fig2vect.

The file consists of several configuration entries, each one consisting
of the name in square brackets and a list of lines consisting
of key/value pairs, i.e.

  [mp]
  normal text = handling:tex,font:similar,size:fig,mbox
  use metapost arrowheads = yes

  [mp.pdf]
  latex font setup = ams12

A three-level inheritance mechanism is used:

=over	6

=item	[*]

This section is processed first.

=item	[I<driver-name>]

This section is processed after the [*] section, settings here override
previous settings.

=item	[I<driver-name>.I<identifier>]

This section is processed after [I<driver-name>]. Settings here override
previous sections.

=back

If the program is run with ``-l mp.pdf'' the configuration sections
[*], [mp] and [mp.pdf] are processed.

=head3	List of keys

=head4	Keys for all drivers

=head5	General setup

=over	6

=item	lighten look = I<boolean>

chooses, whether or not to use only 0.5 times the line width
specified in the Fig file as the Fig file format specification suggests.
This option is turned off by default.

=item	web palette = I<boolean>

chooses, whether or not to use a Web-optimized color palette.
By default the colors are used as specified in the Fig file.

=item	use cs settings = I<boolean>

chooses, whether to use or ignore the coordinates setting from the
Fig file. The default is to ignore this information, so the origin
is always the upper left corner.

=item	verbose output = I<boolean>

configures the program to write additional comments to output.

=item	accept unknown paper size = I<boolean>

configures the program to accept any name for paper formats.

=item	remove background rectangle = I<boolean>

specifies that a background rectangle (polygon ``2'', subtype
box ``2'' in layer 999,
default stroke color ``-1'' or white ``7'', line width 0) is
used for image size calculation
only; this rectangle is not printed to output.

=item	background rectangle color = I<string>

chooses, whether background rectangles must be drawn in
``white'' or in the ``default'' color. When drawing in XFig,
use ``default'', when drawing in jFig use ``white''.

=back

=head5	Number precision

=over	6

=item	color digits = I<integer>

specifies the number of digits for colors (default: 3).

=item	position digits = I<integer>

specifies the number of digits for coordinates (default: 2).

=item	additional trigonometric digits = I<integer>

specifies the number of additional digits to print coordinates
which were calculated using trigonometric operation (default: 3).

=back

=head5	Spline handling

=over	6

=item	spline segments = I<integer>

specifies how many Bezier spline segments to use for each X-spline segment
(default: 8).

=back

=head5	Arrowheads

=over	6

=item	arrowhead linejoin = I<string>

chooses the linejoin style for arrowheads, may be ``mitered'' (default),
``rounded'' or ``beveled''.

=item	min iteration steps = I<integer>

chooses the minimum number of iteration steps when calculating
a spline cut for arrowheads.

=item	max iteration steps = I<integer>

chooses the maximum number of iteration steps when calculating
a spline cut for arrowheads.

=back

=head5	Fill patterns and filling

=over	6

=item	remove zero border = I<boolean>

chooses whether to remove or to draw the borders of filled or pattern filled
objects if the linewidth is 0. A line width of zero means either
not to draw the border (common sense) or to draw the thinnest line a device
provides (PostScript interpretation of line width 0).

=item	fill patterns = I<boolean>|``contiguous''

Fill patterns can be either ignored (``no''), drawn (``yes'') or
drawn contiguously (``contiguous'').

=item	pattern repeat = I<integer>

The distance between pattern lines in 1/80 inch (the same unit the
Fig file format uses for line widths). The default is 4.

=item	dashpattern dot length = I<string>

Dots in dash patterns can be either drawn in length 0 (``0'') or as
long as the line is wide (``linewidth''). The default is ``linewidth''.

=back

=head5	Embedded bitmap images

The fig2vect program can handle embedded PNG and JPEG images. The EPS
driver can also use EPS images.

=over	6

=item	keep bitmap aspect ration = I<boolean>

decides whether the width/height relation of the image must be kept
(default) leaving some free space in the box rectangle or whether
the rectangle is fully used scaling the image at different factors
for width and height.

=item	remove bitmap border = I<boolean>

chooses whether or not to remove the border stroke for bitmap
boxes (default: remove).

=item	fill bitmap background = I<boolean>

chooses whether or not to fill the image box in the specified color
before applying the image.

=back

=head5	Text handling

=over	6

=item	font scale factor = I<numeric>

specifies a factor to scale all texts. The default is 0.92.

=item	normal text = I<string>

specifies how to handle normal (non-special) text. The string
consists of key/value pairs, separated by comma. Key and value
in each pair are separated by a colon.

The following keys can be used:

=over	12

=item	handling:I<string>

specifies whether to leave text handling up to TeX/LaTex (``tex'') or to
do text handling in the driver (``none'').

=item	font:I<string>

specifies how to find a font:

=over	18

=item	fig

uses exactly the fonts specified in the Fig file

=item	similar

uses a font matching the characteristics (serif/sansserif, upright/italic,
normal/bold) of the font specified in the Fig file.

=item	tex

leaves font handling up to TeX/LaTeX.

=back

=item	size:I<string>

chooses the font size,

=over	18

=item	fig

uses the same font size as specified in the Fig file

=item	tex

leaves font size setting up to TeX/LaTeX.

=back

=item	mbox

does not have a value. If this key occurs, the text is placed
into an \\mbox structure for TeX/LaTeX.

=back

=item	special text = I<string>

specifies, how to handle special text. The string can contain the
same key/value pairs as ``normal text'' except ``handling'' (because
special text is always handled by TeX/LaTeX).

=item	tex command = I<string>

chooses whether to use TeX (``tex'') or LaTeX (``latex'').

=item	latex font setup = I<string>

selects one predefined LaTeX preamble, may be ``pdf'', ``ams'', ``newcent'',
``pdf12'', ``ams12'' or ``newcent12''.

In most cases it is besser to use your own preamble, see
``preamble file''.

=item	preamble file = I<file_name>

specifies the file name of a preamble file to use for text handling.
This file must not contain \\begin{document}.

=item	repeat error messages = I<boolean>

If a driver detects special text but can not handle it we can
write the error message once for each text or only once per input file.

=item	skip all texts = I<boolean>

allows the program to silently ignore all text it can not handle.

=back

=head4	Keys for the MetaPost driver

=head5	Arrowheads

=over	6

=item	use metapost arrowheads = I<boolean>

allows or denies the use of MetaPost arrowheads. MetaPost uses curved
arrowheads for arcs and splines but does not support all arrowhead types
defined by the Fig file format.

=back

=head5	Text handling

=over	6

=item	embed fonts = I<boolean>

decides whether or not MetaPost embeds fonts into PostScript output.
The MetaPost driver writes either ``prologues:=1'' or ``prologues:=0''
to control this.

=back

=head4	Keys for the EPS driver

=head5	PS level and PS structure

=over	6

=item	ps level = I<integer>

chooses PS level 1, 2 or 3.

=item	dsc comments = I<integer>|I<boolean>

chooses the PS level for DSC comments or enables/disables
DSC comments.

=item	ps showpage = I<boolean>

decides whether or not a showpage operator is used at the end of the
output file.

=item	ps setpagedevice = I<boolean>

decides whether or not the setpagedevice operator is used to restrict
output media size to image size. This is usefull if you want to use
GhostScript to convert the EPS image into a bitmap.

=back

=head5	Virtual memory

=over	6

=item	bitmap image dictionary = I<boolean>

decides whether or not to embed the drawing operations into a

   ... dict begin
   % drawing operations
   end

structure. This structure allows a better use of the virtual memory
in the PostScript interpreter, but it cannot be used if the Fig file
contains embedded EPS images.

=item	force garbage collection = I<boolean>

enables/disables the use of

  1 vmreclaim

at the end of EPS output.

=back

=head5	Embedded bitmap images

=over	6

=item	ps run-length encoding = I<boolean>

allows/denies the use of run-length encoding.

=item	separated rgb channels = I<boolean>

specifies data order for run-length encoding. For separated
RGB channels the data stream first contains all pixel's red values,
followed by all pixel's green values and all pixel's blue values.

If separation is deactivated the stream contains the RGB triples
pixel by pixel.

Separated RGB channels allow run-length compression of colored runs
and colored areas. If separation is deactivated run-length compression
only compresses gray areas.

=back

=head4	Keys for the PDF driver

=head5	General setup

=over	6

=item	plain text streams = I<boolean>

decides whether to write graphics data streams as plain text
or compressed.

=item	full screen = I<boolean>

forces switching to full-screen mode when opening the PDF file.

=item	arc bezier steps = I<integer>

specifies the number of Bezier spline segments used to
approximate a quarter of a circle.

=back

=head5	Fill patterns and filling

=over	6

=item	tiled patterns = I<boolean>

chooses whether a fill pattern is made of small tiled pattern cells (yes)
or one large pattern cell (no). One large pattern cell will result in
better rendering quality on screen but also in a larger file.

=back

=head5	Embedded bitmap images

=over	6

=item	interpolate images = I<boolean>

enables/disables the image interpolation flag. Interpolation improves
rendering quality if images are scaled upward.

=item	flip direction = I<string>

sets the flip direction, either "horizontal" or "diagonal".

=back

=head4	Keys for the TeX driver

=over	6

=item	full tex file = I<boolean>

decides whether to write a complete LaTeX source document for
standalone processing (yes) or only a fragment which can be included
into a LaTeX source using \input{} (no).

=back

=head4	Keys for the SVG driver

=head5	SVG header and SVG structure

=over	6

=item	svg version = I<string>

specifies the SVG version to use, either "1.0", "1.1" or "1.2".
I recommend to use "1.0".

=item	embedded svg = I<boolean>

decides whether to produce a piece of SVG code which is embedded
into other XML documents (yes) or a complete SVG file (no).
The default is to produce a complete SVG file.

=item	wh specification = I<string>

chooses how to set width and height of the SVG file, either
using inches (inches), PostScript points (points) or
pixels (pixels).

=back

=head5	Object attributes

=over	6

=item	prepare for modifications = I<boolean>

forces fig2vect to write all style attributes as single attributes.
Turned off by default, automatically turned on if fig2vect finds
ECMA-script usage.

=item	use css = I<boolean>

switches between complex style attribute and use of CSS classes
if there is no need to prepare for modifications.

=back

=head5	ECMA-Script

=over	6

=item	js library = I<string>

specifies a file name for a *.js file to include into SVG output.
This entry can appear multiple times.

=back

When using ECMA script some objects need an id. Use special comments
(control comments) in the Fig file to assign id's to objects, i.e.

  ## svg: id = obj0001

and to assign event handlers to objects, i.e.

  ## svg: onmouseover = changebgcolor(evt)

The control comment(s) must be placed in the line(s) immediately before
the Fig object is started.
Control comments for the entire drawing (i.e. for the onload event handler)
must be placed in the global document commennt set between
line 8 (transparent color) and 9 (resolution and coordinates system).

=head5	Fonts

=over	6

=item	gs svg-font directory = I<string>

The path of a directory containing SVG ports of the GhostScript fonts.
See fig2vect.pdf/f2vde.pdf how to produce these ports.

=back

=head1	RESTRICTIONS

=over	6

=item	Text must not be on the outermost left, right, top or bottom position.

When calculating the image size all texts are ignored.
So if there is text in an outermost left, right, top or bottom position
you should add a background rectangle to allow fig2vect to calculate
the image size correctly. A background rectangle is a rectangle
(type 2: polygon, subtype 2: box) in layer 999. The linewidth is 0,
fill style -1 (no filling), fill color does not care. The line color
must be either default (-1) or white. In XFig one can set line color
default using the edit function. In jFig it is not possible to choose
line color default, use white instead and use the configuration
entry

  background rectangle color = white

=item	No filenames containing white spaces supported by Windows version.

The Windows version distributed in the dklibs-win32 package can not
handle file names containing white spaces if the program is run from
the default command interpreters. Use a real shell (i.e. bash
or tcsh) if you need white spaces in file names.

=back

=head1	SEE ALSO

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

=head1	AUTHOR

Dirk Krause.

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2001-2008, 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	HISTORY

Initially I added enhancements to the genmp.c module (MetaPost) output
driver in fig2dev. But I had some ideas which required multi-pass
processing (traversing the list of graphics elements multiple times)
which would be difficult to realize in fig2dev. So I decided to write
a new program from scratch.

