fig2vect 1.1.23

Usage

For the impatient: The examples page shows hot to get started using fig2vect.

• Command line options
• Configuration file
•     Option processing order
•     Configuration entry lines
•         For all drivers
•             General options
•             Number precision
•             Spline processing
•             Arrowheads
•             Fill patterns and dash patterns
•             Embedded images
•             Text typesetting
•         MetaPost driver
•             Arrowheads
•             Text typesetting
•             Bounding box
•         PS/EPS driver
•             PS level and PS structure
•             Page size and page alignment
•             Virtual memory
•             Encoding of embedded bitmaps
•         PDF driver
•             General options
•             Fill patterns
•             Embedded bitmap images
•         TeX driver
•         SVG driver
•             SVG header and structure
•             Object attributes
•             Text typesetting
•             ECMA script (JavaScript)

Command line options

The program is invoked by typing
 
  fig2vect  options
  fig2vect  options inputfile
  fig2vect  options inputfile outputfile
  fig2vect  options directory

 
The program runs as a filter if no input file name is specified. If the output file name is omitted the program writes output to standard output.
When the program is run on a directory name the directory is traversed. Each *.fig file is converted into an appropriate output file. If make-style behaviour is turned on a conversion is started only for *.fig files which are newer than the output files to produce.
 
The following options are available:

-h
--help

prints a help text.

-v
--version

prints the version number.

-C
--show-configuration

shows the permanent options in use.

-c
--configure

configures permanent options.

-u
--unconfigure

removes all permanent options.

-r
--reset

resets all permanent options for this one program invokation.

-m
--make

enables make-style behaviour when running on a directory.

-m-
--make=off

disables make-style behaviour when running on a directory.

-a

automatically chooses an output file name if no output file name was specified. The file name is based on the input file name and the output driver.

-l configuration
--language=configuration

chooses a configuration for output.

-o key=value
--option=key=value

overrides a configuration entry configured in the fig2vect.cfg file.

---

Configuration file

Option processing order

The program uses a configuration file /etc/fig2vect/fig2vect.cfg. Users can keep their own copy of the file in $HOME/.defaults/fig2vect.cfg and apply modifications as needed to that file.
The file consists of a general options section (introduced by [*]), driver-specific sections (introduced i.e. by [mp]) and configuration definition sections (introduced i.e. by [mp.pdf]). The name of a configuration consists of the driver name and additional identifiers separated by a dot.
Option processing order is:

1. General options section
2. Driver options section
3. Configuration definition section
4. Option overrides on the command line

So if you run

fig2vect -l mp.pdf -o tex.command=tex test.fig test.mp

settings are obtained from the "[*]" section, the "[mp]" section, the "[mp.pdf]" section. Finally the tex command is overwritten by the "-o tex.command=tex" command line argument.

Configuration entry lines

For all drivers

General options

lighten look = boolean

chooses whether or not to lighten the look as suggested in the Fig format specification. Turned off by default.

web palette = boolean

chooses whether or not to use a web optimized color palette instead of the normal colors. Turned off by default.

use cs setting = boolean

chooses whether or not to obtain the origin setting from the Fig file. Turned off by default because the Fig format specification suggests this.

verbose output = boolean

chooses whether or not to write additional comments to output. Turned off by default.

accept unknown paper size = boolean

allows to accept unknown paper format names. As fig2vect gets image width and height from the inspection of all graphics elements (except texts) we don't need to worry about unknown names. Turned on by default.

Number precision

color digits = integer

configures the number of digits after the decimal dot in color specifications. The default is 3.

position digits = integer

configures the number of digits after the decimal dot in object placements. The default is 2.

additional trigonometric digits = integer

configures the number of additional digits after the decimal dot in object placements if trigonometric calculations were involved. The default is 3, so we have 5 digits after the decimal dot at all.

Spline processing

spline segments = integer

configures the number of Bezier-spline segments to use for each X-spline segment. The default is 2.

Arrowheads

arrowhead linejoin = string

chooses a line join style for arrowheads, may be ``mitered'' (default), ``rounded'' or ``beveled''.

min iteration steps = integer
max iteration steps = integer

chooses the minimum and maximum number of iteration steps to shorten splines. If the maximum number is reached without success, the spline is not shortened and the arrowhead is removed.

Fill patterns and dash patterns

remove zero border = boolean

chooses whether or not to remove the object border for filled objects if a linewidth 0 is specified.

fill patterns = string

chooses, whether or not to use fill patterns. The setting ``contiguous'' will arrange contiguous fill patterns, if different objects use the same pattern.

pattern repeat = integer

configures the pattern distance. The default value is 4.

dashpattern dot length = string

configure how long to draw dots in dash pattern, may be ``0'' or ``linewidth'' (default).

Embedded images

keep bitmap aspect ration = boolean

configure whether to keep the width/height relation for embedded bitmaps (default) or to use the full box using different scale factors for width and height.

image alignment = alignment

specifies how to align a bitmap into the available space rectangle.
When fitting a bitmap into the specified space keeping the aspect ratio where might be unused horizontal or vertical space. By default the image is placed centered in the available space. You can use ``top'' or ``bottom'' to change the vertical alignment and ``left'' or ``right'' to change the horizontal alignment.

remove bitmap border = boolean

chooses whether or not to remove box stroking for embedded images. Turned on by default.

fill bitmap background = boolean

chooses whether or not to fill the bitmap polygon before writing the image. Turned off by default.

background rectangle color = color

specifies the stroke color of the background rectangle, either ``default'' (should be used for drawings created by XFig) or ``white'' (should be used for drawings created by jFig).

Text typesetting

font scale factor = number

specifies a factor to scale all texts. The factor should be in the range 0.9...0.92...0.95.
If the default value 1 is used texts look larger in comparison to other graphics elements than shown in XFig or jFig.

normal text = string

configure how to handle non-special text. The string consists of key/value pairs separated by ``,''. Key and value in a pair are separated by a colon. The following keys can be used:

• handling:string
  configureds the driver to handle the text either itself (``none'') or to leave text handling up to TeX/LaTeX (``tex'').
• font:string
  decides how to choose a font:
  • ``fig'' uses exactly the font as specified in the Fig file.
  • ``similar'' uses a font with similar features as the font specified in the Fig file (serif/sans-serif/monospace, normal/bold, upright/italic).
  • ``tex'' leaves the decision up to TeX/LaTeX.
• size:string
  decides how to choose the text size:
  • ``fig'' chooses the font size as specified in the Fig file and applies the font scale factor.
  • ``tex'' leaves the decision up to TeX/LaTeX.
• mbox:
  does not have a value. If this key is found the text is embedded in a mbox instruction.

special text = string

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

tex command = string

chooses a command to handle special text, either ``tex'' or ``latex''.

latex font setup = string

chooses one of the predefined font setups, may by ``pdf'', ``newcent'', ``ams'', ``pdf12'', ``newcent12'' or ``ams12''.
Note: A better way to set up fonts is the ``preamble file'' configuration entry.

preamble file = string

specifies a filename for a stripped-down preamble. This preamble file only contains font setup instructions. It must not include ``\begin{document}''.

repeat error messages = boolean

configures whether to print error messages for each text if a driver can not do TeX/LaTeX text handling. if this option is turned of only one warning is generated for the first text.

skip all texts = boolean

turns off all error messages related to text. This is useful if the combination of EPS/TeX or PDF/TeX drivers is used.

utf-8 = boolean

turns support for UTF-8 encoded text on or off.
By default (``auto'') fig2vect inspects the LANG environment variable. If this variable ends on ``.UTF-8'' (case-insensitiv) UTF-8 support is turned on, otherwise it is turned off.
See the dklibs UTF-8 support FAQ for details how to enable/disable and how to use UTF-8 support.
If UTF-8 support is turned on fig2vect attempts to UTF-8 decode all non-special texts. If non-special text is handled by TeX/LaTeX (``handling:tex'') fig2vect attempts to find LaTeX code to represent the glyphs. If non-special text is handled by the driver (``handling:none'') only Unicode characters 0x00000000...0x000000FF can be used.
In special text you can directly write the appropriate LaTeX code to produce the glyphs you need.

MetaPost driver

Arrowheads

use metapost arrowheads = boolean

allows the use of MetaPost arrowheads. MetaPost applies curved arrowheads to curved lines (arcs, splines) but does not support all Fig arrowhead types. Some arrowhead types must be converted automatically.

Text typesetting

skip all texts = boolean

prevents the MetaPost driver from writing any text related instructions to the *.mp output. This option can be used to combine the MetaPost and the TeX driver.

normal text = string
special text = string

• handling:tex
  converts texts into ``\btex...\etex'' labels.
• handling:none
  converts texts into "..." labels.
  
  • font:fig
    uses PostScript names for fonts, i.e. ``label "..." infont "Times-Roman"''.
  • font:tex
    uses TeX names for fonts, i.e. ``label "..." infont "ptmr"''.
  • Note: For handling:none you should use font:fig.

embed fonts = boolean

chooses whether or not MetaPost embeds the fonts in the MetaPost output file. The driver creates a ``prologues:=0;'' or ``prologues:=1;'' entry in the *.mp file.
If the image will be embedded in a LaTeX document, leave font embedding up to dvips or pdflatex (turn this option off).

Bounding box

fill bounding box = boolean

Writes an output instruction to white-fill the bounding box region calculated by fig2vect to the *.mp output. This results in a correct BoundingBox information in the *.0 or *.mps file. This option is recommended when combining MetaPost and TeX driver for correct text placement

PS/EPS driver

PS level and PS structure

ps level = integer

chooses a PostScript level (``1'', ``2'' or ``3'').

dsc comments = string

chooses the level for DSC comments -- ``1'', ``2'' or ``3'' -- or turns DSC comments on (``yes'') or off (``no'').

ps showpage = boolean

chooses whether or not to print a showpage operator at the end of output. This is recommended for standalone images but should not be used for images included into LaTeX documents. This operator is only allowed when producing PS files, not EPS files.

Page size and page alignment

page size = boolean boolean [boolean boolean boolean boolean]

specifies the page size (width and height) and optionally the printable range on the page (lower left x, lower left y, upper right x and upper right y). This option is only available when producing PS, not EPS.

page alignment =alignment

sets the alignment of the page in the printable range. By default the graphics is centered in the printable range. Use "top" or "bottom" to change the vertical alignment or "left" or "right" to change the horizontal alignment. This option is only available when producing PS, not EPS.

ps setpagedevice = boolean

enables/disables the use of the setpagedevice operator. This operator may be useful if you want to convert the PostScript output to other formats using GhostScript. This operator is only allowed when producing PS files, not EPS files.

Virtual memory

bitmap image dictionary = boolean

decides whether to embed all drawing operations into a

... dict begin
  % drawing operations
end

construction or not.

force garbage collection = boolean

chooses whether or not to ask for a garbage collection at the end of the output file. This option is only useful in combination with ``bitmap image dictionary''.

Encoding of embedded bitmaps

ps run-length encoding = boolean

enables or disables the use of run-length encoding.

separated rgb channels = boolean

chooses how to organize bitmap image data. Turning this option on allows the run-length compression of areas in the same color. If the option is turned off, only grey areas can be run-length compressed. If this option is turned on, the PostScript interpreter needs significantly more virtual memory to process images.

PDF driver

General options

plain text streams = boolean

chooses whether to write graphics instructions as plain text or compressed (default).

full screen = boolean

chooses whether or not to change to full-screen mode when opening the PDF file.

arc bezier steps = integer

configures the number of Bezier-spline segments to use per circle quadrant. The default is 2.

allow pdf page attributes = boolean

allows/denies the creation of pdf page attributes. PDF page attributes are needed if the Fig file references PNG images containing alpha channels if the PDF output is viewed standalone.

Fill patterns

large pattern cell = boolean

chooses whether or not to use one large pattern cell. By default the program uses small pattern cells. When rendering PDFs on screen there may be irritations on cell transitions. For better screen rendering the pattern cell can be made as large as the entire image to avoid these irritations. Large pattern cells will increase the file size significantly.

Embedded bitmap images

interpolate images = boolean

turns interpolation for embedded images off or on.

flip direction = string

specifies how to flip images if the flip flag is set, either ``diagonal'' (default) or ``horizontal'' (as seen in jFig).

TeX driver

full tex file = boolean

decides whether to produce a code snippet for inclusion into a LaTeX source (default) or to produce a complete *.tex file to produce a standalone PDF file.

SVG driver

SVG header and structure

svg version = string

chooses an SVG version, either ``1.0'' (default), ``1.1'' or ``1.2''.

embedded svg = boolean

decides whether to produce a code snippet for embedding into XML documents or to produce a full SVG file (default).

wh specification = string

chooses how to specfiy image width and height, either in ``inches'', ``pixels'' or ``points'' (PostScript points).

Object attributes

prepare for modifications = boolean

requires the use of multiple simple style attributes. This is useful if you plan to use animations or event handlers. If fig2vect detects the use of ECMA script, this mode is turned on automatically.

use css = boolean

decides whether to use CSS styling or a combined style attribute if there is no need for multiple simple attributes. CSS styling may decrease file sizes if multiple objects must be drawn in the same style.

Text typesetting

gs svg-font directory = directory

specifies the directory where the SVG variants of the Ghostscript fonts reside. If you did not build and install these fonts, omit this option.
Note: This option only provides a static font mapping from PostScript fonts to SVG variants of the GhostScript fonts. This is deprecated. You should use font configuration files, see below.

font configuration file = filename

specifies the file name of a font configuration file, i.e. ``winfont.cfg''. The dklibs configuration file search mechanism is used to find that file, it is recommended to have these files in ${prefix}/etc/fig2vect or %WINDIR%\fig2vect.
See the example files ``winfont.cfg'', ``webfont.cfg'' and ``combfont.cfg'' shipped with fig2vect. The structure of font configuration files is explained in dkfont(5) and the dklibs PDF manual.

ECMA script (JavaScript)

js library = filename

specifies the name of a file containing ECMA script functions and variables. The contents of this file is included into the SVG output.
This option / control comment can be used multiple times to use a collection of files.

Special comments can be used to assign IDs and event handlers to objects, i.e.

## svg: id = obj001
## svg: onmouseover = changebgcolor(evt)

Event handlers can be used for

• onfocusin
• onfocusout
• onactivate
• onclick
• onmousedown
• onmouseup
• onmouseover
• onmousemove
• onmouseout
• onload
• onunload
• onabort
• onerror
• onresize
• onscroll
• onzoom
• onbegin
• onend
• onrepeat

To create event handlers for document events, place the control comments in the document level comment section between line 8 (transparent color) and 9 (resolution/origin).
The file doc2.fig may be used as an example for ECMA-script related control comments.