fig2vect

Usage

PDF manual "fig2vect.pdf" available german version "f2vde.pdf" available too

	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
			PS/EPS driver
				PS level and PS structure
				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

All settings are written as key=value lines. Keys are multipart strings, the parts are separated by whitespaces in the configuration file, by dots when overriding options on the command line.
 
The following configuration entries lines can be used:

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

    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.

  • Text typesetting

    font scale factor = float

    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 shwon in XFig or jFig.

    normal text = string

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

    handling:string

    configures the driver to handle the text 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 (features: serif/sans-serif/monospaces, 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 spezified in the Fig file.
    • ``tex'' leaves the decision up to TeX/LaTeX.

    mbox

    does not have a value. If this key is found, the text is embedded into 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 the 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 be ``pdf'', ``newcent'', ``ams'', ``pdf12'', ``newcent12'' or ``ams12''.
    Note: A better way to set up fonts for text handling is the ``preamble file'' configuration entry.

    preamble file = filename

    specifies a filename for a stripped-down preamble. This preamble 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 LateX text handling. If this option is turned off, only one warning is generated for the first text.

    skip all texts = boolean

    turns off all error messages related to text. This is usefull 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'' UTF-8 support is turned on, otherwise it is turned off.
    See the UTF-8 support FAQ for details how to enable/disable 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 write the appropriate LaTeX code directly to produce Unicode glyphs.

• 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

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

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

    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.