path: root/Master/texmf-dist/doc/man/man1/dvisvgm.1

'\" t
.\"     Title: dvisvgm
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 03/01/2013
.\"    Manual: dvisvgm Manual
.\"    Source: dvisvgm 1.2
.\"  Language: English
.\"
.TH "DVISVGM" "1" "03/01/2013" "dvisvgm 1\&.2" "dvisvgm Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dvisvgm \- converts DVI files to the XML\-based SVG format
.SH "SYNOPSIS"
.sp
\fBdvisvgm\fR [ \fIoptions\fR ] \fIfile\fR [\&.dvi]
.SH "DESCRIPTION"
.sp
The command\-line utility \fBdvisvgm\fR converts DVI files, as generated by TeX/LaTeX, to the XML\-based scalable vector graphics format SVG\&. Since the current SVG standard 1\&.1 doesn\(cqt specify multi\-page graphics, dvisvgm creates separate SVG files for each DVI page\&. Because of compatibility reasons, only the first page is converted by default\&. In order to select a different page or arbitrary page sequences, use option \fB\-p\fR which is described below\&.
.sp
dvisvgm should properly convert all pages that are made up of fonts and rules only\&. However, the utility also supports a couple of DVI extensions defined in terms of \fIDVI specials\fR\&. For a more detailed overview, see section \fBsupport of specials\fR below\&.
.sp
As SVG is a vector based graphics format, dvisvgm tries to convert the glyph outlines of all used fonts into scalable path descriptions\&. The fastest way to do that is to extract the path information from PFB (PostScript Type 1) files\&. So, if dvisvgm is able to find a PFB file for a required font, it will read the necessary information from this file\&.
.sp
TeX\(cqs main source for font descriptions is Metafont though, which produces bitmap output\&. That\(cqs why not all obtainable TeX fonts are available in PFB format\&. In these cases, dvisvgm tries to vectorize Metafont\(cqs output (GF fonts) by tracing the glyph bitmaps\&. The results are not as perfect as most (manually optimized) PFB outlines but are nonetheless really nice in most cases\&.
.SH "OPTIONS"
.PP
\fB\-a, \-\-trace\-all\fR=[\fIretrace\fR]
.RS 4
This option forces dvisvgm to trace not only the actually needed glyphs but all glyphs of all bitmap fonts used in the DVI file\&. Since the tracing results are stored in the font cache, all following DVI conversions (without option
\fB\-\-trace\-all\fR) where these fonts are involved, will be much faster\&. By default, dvisvgm traces only the actually needed glyphs, and adds them to the cache\&. The boolean option
\fIretrace\fR
determines how to handle glyphs already stored in the cache\&. By default, these glyphs are skipped\&. Setting argument
\fIretrace\fR
to
\fIyes\fR
or
\fItrue\fR
forces dvisvgm to trace the corresponding bitmaps again\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This option only takes affect if font caching is active\&. Thus,
\fB\-\-trace\-all\fR
cannot be combined with option
\fB\-\-cache=none\fR\&.
.sp .5v
.RE
.RE
.PP
\fB\-b, \-\-bbox\fR=\fIfmt\fR
.RS 4
Sets the bounding box of the generated graphic to the specified format\&. The parameter
\fIfmt\fR
takes either one of the format specifiers listed below, or a sequence of four comma\- or whitespace\-separated length values
\fIx1\fR,
\fIy1\fR,
\fIx2\fR
and
\fIy2\fR\&. The latter define two diagonal corners of the bounding box\&. Each length value consists of a floating point number and an optional length unit (pt, bp, cm, mm, in, or pc)\&. If the unit is omitted, TeX points (pt) are assumed\&.
.sp
It\(cqs also possible to give only one length value
\fIl\fR\&. In this case, the minimal bounding box is computed and enlarged by adding (\-\fIl\fR,\-\fIl\fR) to the upper left and (\fIl\fR,\fIl\fR) to the lower right corner\&.
.sp
Alternatively, the following format specifiers are supported:
.PP
\fBInternational DIN/ISO paper sizes\fR
.RS 4
A\fIn\fR, B\fIn\fR, C\fIn\fR, D\fIn\fR, where
\fIn\fR
is a non\-negative integer, e\&.g\&. A4 or a4 for DIN/ISO A4 format (210mm \(mu 297mm)\&.
.RE
.PP
\fBNorth American paper sizes\fR
.RS 4
invoice, executive, legal, letter, ledger
.RE
.PP
\fBSpecial bounding box sizes\fR
.RS 4
.TS
tab(:);
lt lt
lt lt
lt lt.
T{
\fBdvi\fR
T}:T{
page size stored in the DVI file
T}
T{
\fBmin\fR
T}:T{
computes the minimal/tightest bounding box
T}
T{
\fBnone\fR
T}:T{
no bounding box is assigned
T}
.TE
.sp 1
.RE
.RE
.PP
\fBPage orientation\fR
.RS 4
The default page orientation for DIN/ISO and American paper sizes is
\fIportrait\fR, i\&.e\&.
\fIwidth\fR
<
\fIheight\fR\&. Appending
\fB\-landscape\fR
or simply
\fB\-l\fR
to the format string switches to
\fIlandscape\fR
mode (\fIwidth\fR
>
\fIheight\fR)\&. For symmetry reasons you can also explicitly add
\fB\-portrait\fR
or
\fB\-p\fR
to indicate the default portrait format\&. Note that these suffixes are part of the size string and not separate options\&. Thus, they must directly follow the size specifier without additional blanks\&. Furthermore, the orientation suffixes can\(cqt be used with
\fBdvi\fR,
\fBmin\fR, and
\fBnone\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Option
\fB\-b, \-\-bbox\fR
only affects the bounding box and does not transform the page content\&. Hence, if you choose a landscape format, the page won\(cqt be rotated\&.
.sp .5v
.RE
.RE
.PP
\fB\-C, \-\-cache\fR[=\fIdir\fR]
.RS 4
To speed up the conversion process of bitmap fonts, dvisvgm saves intermediate conversion information in cache files\&. By default, these files are stored in $HOME/\&.dvisvgm/cache\&. If you prefer a different location, use option
\fB\-\-cache\fR
to overwrite the default\&. Furthermore, it is also possible to disable the font caching mechanism completely with option
\fB\-\-cache=none\fR\&. If argument
\fIdir\fR
is omitted, dvisvgm prints the path of the default cache directory and some information about the stored fonts\&. Additionally, outdated and corrupted cache files are removed\&.
.RE
.PP
\fB\-\-color\fR
.RS 4
Enables colorization of messages printed during the conversion process\&. The colors can be customized via the environment variable
DVISVGM_COLORS\&. See the ENVIRONMENT section below for further information\&.
.RE
.PP
\fB\-E, \-\-eps\fR
.RS 4
If this option is given, dvisvgm does not expect a DVI but an EPS input file, and tries to convert it to SVG\&. In order to do so, a single
\fIpsfile\fR
special command is created and forwarded to the PostScript special handler\&. This option is only available if dvisvgm was built with PostScript support enabled, and requires Ghostscript to be available\&. See option
\fB\-\-libgs\fR
for further information\&.
.RE
.PP
\fB\-e, \-\-exact\fR
.RS 4
If this option is given, dvisvgm computes the precise bounding box of each character\&. By default, the values stored in a font\(cqs TFM file are used to determine a glyph\(cqs extent\&. As these values are intended to realize optimal character placements and are not designed to represent the exact dimensions, they don\(cqt necessarily correspond with the bounds of the visual glyphs\&. Thus, width and/or height of some glyphs may be larger than the respective TFM values\&. As a result, this can lead to clipped characters at the bounds of the SVG graphic\&. With option
\fB\-\-exact\fR, dvisvgm analyzes the actual shape of each character and derives a usually tight bounding box\&.
.RE
.PP
\fB\-m, \-\-fontmap\fR=\fIfilenames\fR
.RS 4
Loads and evaluates a single or multiple font map files\&. These files are required to resolve font file names and encodings\&. dvisvgm does not provide its own map file but tries to read available ones coming with dvips or dvipdfm\&. If option
\fB\-\-fonrmapm\fR
is not given, dvisvgm looks for the default map files
ps2pk\&.map,
dvipdfm\&.map, and
psfonts\&.map
(in this order)\&. Otherwise, the listed files are used\&. Multiple filenames must be separated by commas without leading and/or trailing whitespace\&. The map files are evaluated in the given order\&. By default, redefined mappings do not replace previous ones\&. However, each filename can be preceded by an optional mode specifier (\fB+\fR,
\fB\-\fR, or
\fB=\fR) to change this behavior:
.PP
+mapfile
.RS 4
Only those entries in the given map file that don\(cqt redefine a font mapping are applied\&. That\(cqs also the default mode if no mode specifier is given\&.
.RE
.PP
\-mapfile
.RS 4
Ensures that none of the font mappings defined in the given map file are used, i\&.e\&. previously defined mappings for the specified fonts are removed\&.
.RE
.PP
=mapfile
.RS 4
All mappings defined in the map file are applied\&. Previously defined settings for the same font are replaced\&.
.sp
If the first filename in the filename sequence is preceded by a mode specifier, dvisvgm loads the default font map (see above) and applies the other map files afterwards\&. Otherwise, none of default map files will be loaded automatically\&.
.sp
Examples:
\fB\-\-fontmap=myfile1\&.map,+myfile2\&.map\fR
loads
myfile1\&.map
followed by
myfile2\&.map
where all redefinitions of
myfile2\&.map
are ignored\&.
\fB\-\-fontmap==myfile1\&.map,\-myfile2\&.map\fR
loads the default map file followed by
myfile1\&.map
and
myfile2\&.map
where all redefinitions of
myfile1\&.map
replace previous entries\&. Afterwards, all definitions for the fonts given in
myfile2\&.map
are removed again\&.
.sp
For further information about the map file formats, see the manuals of dvips and dvipdfm\&.
.RE
.RE
.PP
\fB\-h, \-\-help\fR[=\fImode\fR]
.RS 4
Prints a short summary of all available command\-line options\&. The optional
\fImode\fR
parameter is an integer value between 0 and 2\&. It selects the display variant of the help text\&. Mode 0 lists all options divided into categories with section headers\&. This is also the default if dvisvgm is called without parameters\&. Mode 1 lists all options ordered by the short option name, while mode 2 sorts the lines by the long option name\&.
.RE
.PP
\fB\-\-keep\fR
.RS 4
Disables the removal of temporary files as created by Metafont (usually \&.gf, \&.tfm, and \&.log files)\&.
.RE
.PP
\fB\-\-libgs\fR=\fIfilename\fR
.RS 4
This option is only available if the Ghostscript library is not directly linked to dvisvgm and if PostScript support was not completely disabled during compilation\&. In this case, dvisvgm tries to load the shared GS library dynamically during runtime\&. By default, it expects the library\(cqs name to be libgs\&.so (on Unix\-like systems) or gsdll32\&.dll/gsdll64\&.dll (Windows)\&. Option
\fB\-\-libgs\fR
can be used to give a different name\&. Alternatively, it\(cqs also possible to set the GS library name by the environment variable
LIBGS\&. The latter has less precedence than the command\-line option\&.
.RE
.PP
\fB\-l, \-\-list\-specials\fR
.RS 4
Prints a list of registered special handlers and exits\&. Each handler processes a set of special statements belonging to the same category\&. In most cases, the categories are identified by the prefix of the special statements\&. It\(cqs usually a leading word separated from the rest of the statement by a colon or a blank, e\&.g\&.
\fIcolor\fR
or
\fIps\fR\&.
.RE
.PP
\fB\-M, \-\-mag\fR=\fIfactor\fR
.RS 4
Sets the magnification factor applied in conjunction with Metafont calls prior tracing the glyphs\&. The larger this value, the better the tracing results\&. Nevertheless, large magnification values can cause Metafont arithmetic errors due to number overflows\&. So, use this option with care\&. The default setting usually produces nice results\&.
.RE
.PP
\fB\-\-no\-mktexmf\fR
.RS 4
Suppresses the generation of missing font files\&. If dvisvgm can\(cqt find a font file through the kpathsea lookup mechanism, it calls the external tools mktextfm or mktexmf by\&. This option disables these calls\&.
.RE
.PP
\fB\-n, \-\-no\-fonts\fR[=\fIvariant\fR]
.RS 4
If this option is given, dvisvgm doesn\(cqt create SVG
\fIfont\fR
elements but uses
\fIpaths\fR
instead\&. The resulting SVG files tends to be larger but concurrently more compatible with most applications that don\(cqt support SVG fonts yet\&. The optional argument
\fIvariant\fR
selects the method how to substitute fonts by paths\&. Variant 0 creates
\fIpath\fR
and
\fIuse\fR
elements\&. Variant 1 creates
\fIpath\fR
elements only\&. Option
\fB\-\-no\-fonts\fR
implies
\fB\-\-no\-styles\fR\&.
.RE
.PP
\fB\-c, \-\-scale\fR=\fIsx\fR[,\fIsy\fR]
.RS 4
Scales the page content horizontally by
\fIsx\fR
and vertically by
\fIsy\fR\&. This option is equivalent to
\fB\-TS\fR\fIsx\fR,\fIsy\fR\&.
.RE
.PP
\fB\-S, \-\-no\-specials\fR[=\fInames\fR]
.RS 4
Disable processing of special commands embedded in the DVI file\&. If no further parameter is given, all specials are ignored\&. To selectively disable sets of specials, an optional comma\-separated list of names can be appended to this option\&. A
\fIname\fR
is the unique identifier referencing the intended special handler\&. Option
\fB\-\-list\-specials\fR
lists all currently available handlers and their names\&. All unsupported special statements are silently ignored\&.
.RE
.PP
\fB\-\-no\-styles\fR
.RS 4
By default, dvisvgm creates CSS styles and class attributes to reference fonts because it\(cqs more compact than repeatedly set the complete font information in each text element\&. However, if you prefer direct font references, the default behavior can be disabled with option
\fB\-\-no\-styles\fR\&.
.RE
.PP
\fB\-o, \-\-output\fR=\fIpattern\fR
.RS 4
Sets the name pattern of the output file\&. Parameter
\fIpattern\fR
is a string that may contain the variables
\fB%f\fR
and
\fB%p\fR\&.
\fB%f\fR
stands for the base name of the DVI file, i\&.e\&. the DVI filename without suffix, and
\fB%p\fR
is the current page number\&. The default pattern is
\fB%f\-%p\&.svg\fR
if the DVI file consists of more than one page, and
\fB%f\&.svg\fR
otherwise\&. That means, a DVI file
\fIfoo\&.dvi\fR
is converted to
\fIfoo\&.svg\fR
if
\fIfoo\&.dvi\fR
is a single\-page document\&. Otherwise, multiple SVG files
\fIfoo\-01\&.svg\fR,
\fIfoo\-02\&.svg\fR, etc\&. are produced\&. In Windows environments, the percent sign indicates dereferenced environment variables, and must therefore be protected by a second percent sign, e\&.g\&.
\fB\-\-output=%%f\-%%p\fR\&.
.RE
.PP
\fB\-p, \-\-page\fR=\fIranges\fR
.RS 4
This option sets the pages to be processed\&. Parameter
\fIranges\fR
consists of a comma\-separated list of single page numbers and/or page ranges\&. A page range is a pair of numbers separated by a hyphen, e\&.g\&. 5\-12\&. Thus, a page sequence might look like this: 2\-4,6,9\-12,15\&. It doesn\(cqt matter if a page is given more than once or if page ranges overlap\&. dvisvgm always extracts the page numbers in ascending order and converts them only once\&. In order to stay compatible with previous versions, the default page sequence is 1\&. dvisvgm therefore converts only the first page and not the whole document in case option
\fB\-\-page\fR
is omitted\&. Usually, page ranges consist of two numbers denoting the first and last page to be converted\&. If the conversion is to be started at page 1, or if it should continue up to the last DVI page, the first or second range number can be omitted, respectively\&. Example:
\fB\-\-page=\-10\fR
converts all pages up to page 10,
\fB\-\-page=10\-\fR
converts all pages starting with page 10\&. Please consider that the page values don\(cqt refer to the page numbers printed on the page\&. Instead, the physical page count is expected, where the first page always gets number 1\&.
.RE
.PP
\fB\-d, \-\-precision\fR=\fIdigits\fR
.RS 4
Specifies the maximal number of decimal places applied to floating\-point attribute values\&. All attribute values written to the generated SVG file(s) are rounded accordingly\&. The parameter
\fIdigits\fR
allows integer values from 0 to 6, where 0 enables the automatic selection of significant decimal places\&. This is also the default value if dvisvgm is called without option
\fB\-\-precision\fR\&.
.RE
.PP
\fB\-P, \-\-progress\fR[=\fIdelay\fR]
.RS 4
Enables a simple progress indicator shown when time\-consuming operations like PostScript specials are processed\&. The indicator doesn\(cqt appear before the given delay (in seconds) has elapsed\&. The default delay value is 0\&.5 seconds\&.
.RE
.PP
\fB\-r, \-\-rotate\fR=\fIangle\fR
.RS 4
Rotates the page content clockwise by
\fIangle\fR
degrees around the page center\&. This option is equivalent to
\fB\-TR\fR\fIangle\fR\&.
.RE
.PP
\fB\-s, \-\-stdout\fR
.RS 4
Don\(cqt write the SVG output to a file but redirect it to
\fBstdout\fR\&.
.RE
.PP
\fB\-T, \-\-transform\fR=\fIcommands\fR
.RS 4
Applies a sequence of transformations to the SVG content\&. Each transformation is described by a
\fIcommand\fR
beginning with a capital letter followed by a list of comma\-separated parameters\&. Following transformation commands are supported:
.PP
\fBT\fR \fItx\fR[,\fIty\fR]
.RS 4
Translates (moves) the page in direction of vector (\fItx\fR,\fIty\fR)\&. If
\fIty\fR
is omitted,
\fIty\fR=0 is assumed\&. The expected unit length of
\fItx\fR
and
\fIty\fR
are TeX points (1pt = 1/72\&.27in)\&. However, there are several constants defined to simplify the unit conversion (see below)\&.
.RE
.PP
\fBS\fR \fIsx\fR[,\fIsy\fR]
.RS 4
Scales the page horizontally by
\fIsx\fR
and vertically by
\fIsy\fR\&. If
\fIsy\fR
is omitted,
\fIsy\fR=\fIsx\fR
is assumed\&.
.RE
.PP
\fBR\fR \fIangle\fR[,\fIx\fR,\fIy\fR]
.RS 4
Rotates the page clockwise by
\fIangle\fR
degrees around point (\fIx\fR,\fIy\fR)\&. If the optional arguments
\fIx\fR
and
\fIy\fR
are omitted, the page will be rotated around its center depending on the chosen page format\&. When option
\fB\-bnone\fR
is given, the rotation center is origin (0,0)\&.
.RE
.PP
\fBKX\fR \fIangle\fR
.RS 4
Skews the page along the
\fIx\fR\-axis by
\fIangle\fR
degrees\&. Argument
\fIangle\fR
can take any value except 90+180\fIk\fR, where
\fIk\fR
is an integer\&.
.RE
.PP
\fBKY\fR \fIangle\fR
.RS 4
Skews the page along the
\fIy\fR\-axis by
\fIangle\fR
degrees\&. Argument
\fIangle\fR
can take any value except 90+180\fIk\fR, where
\fIk\fR
is an integer\&.
.RE
.PP
\fBFH\fR [\fIy\fR]
.RS 4
Mirrors (flips) the page at the horizontal line through point (0,\fIy\fR)\&. Omitting the optional argument leads to
\fIy\fR=\fIh\fR/2, where
\fIh\fR
denotes the page height (see
\fIpre\-defined constants\fR
below)\&.
.RE
.PP
\fBFV\fR [\fIx\fR]
.RS 4
Mirrors (flips) the page at the vertical line through point (\fIx\fR,0)\&. Omitting the optional argument leads to
\fIx\fR=\fIw\fR/2, where
\fIw\fR
denotes the page width (see
\fIpre\-defined constants\fR
below)\&.
.RE
.PP
\fBM\fR \fIm1\fR,\&...,\fIm6\fR
.RS 4
Applies a transformation described by the 3\(mu3 matrix ((\fIm1\fR,\fIm2\fR,\fIm3\fR),(\fIm4\fR,\fIm5\fR,\fIm6\fR),(0,0,1)), where the inner triples denote the rows\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
All transformation commands of option
\fB\-T, \-\-transform\fR
are applied in the order of their appearance\&. Multiple commands can optionally be separated by spaces\&. In this case the whole transformation string has to be enclosed in double quotes\&. All parameters are expressions of floating point type\&. You can either give plain numbers or arithmetic terms combined by the operators
\fB+\fR
(addition),
\fB\-\fR
(subtraction),
\fB*\fR
(multiplication),
\fB/\fR
(division) or
\fB%\fR
(modulo) with common associativity and precedence rules\&. Parentheses may be used as well\&.
.sp
Additionally, some pre\-defined constants are provided:
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt.
T{
\fBux\fR
T}:T{
horizontal position of upper left page corner in TeX point units
T}
T{
\fBuy\fR
T}:T{
vertical position of upper left page corner in TeX point units
T}
T{
\fBh\fR
T}:T{
page height in TeX point units (0 in case of
\fB\-bnone\fR)
T}
T{
\fBw\fR
T}:T{
page width in TeX point units (0 in case of
\fB\-bnone\fR)
T}
.TE
.sp 1
Furthermore, you can use the length constants
\fBpt\fR,
\fBmm\fR,
\fBcm\fR
and
\fBin\fR, e\&.g\&.
2cm
or
1\&.6in\&. Thus, option
\-TT1in,0R45
moves the page content 1 inch to the right and rotates it by 45 degrees around the page center afterwards\&.
.sp
For single transformations you can also use options
\fB\-c\fR,
\fB\-t\fR
and
\fB\-r\fR\&. Note that the order in which these options are given is not significant, i\&.e\&. you can\(cqt use them to describe transformation sequences\&. They are simply independent shorthand options for common transformations\&.
.sp .5v
.RE
.RE
.RE
.PP
\fB\-t, \-\-translate\fR=\fItx\fR[,\fIty\fR]
.RS 4
Translates (moves) the page content in direction of vector (\fItx\fR,\fIty\fR)\&. This option is equivalent to
\fB\-TT\fR\fItx\fR,\fIty\fR\&.
.RE
.PP
\fB\-v, \-\-verbosity\fR=\fIlevel\fR
.RS 4
Controls the type of messages printed during a dvisvgm run:
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt.
T{
\fB0\fR
T}:T{
no message output
T}
T{
\fB1\fR
T}:T{
error messages only
T}
T{
\fB2\fR
T}:T{
warning messages only
T}
T{
\fB4\fR
T}:T{
informational messages only
T}
.TE
.sp 1
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
By adding these values you can combine the categories\&. The default level is 7, i\&.e\&. all messages are printed\&.
.sp .5v
.RE
.RE
.PP
\fB\-V, \-\-version\fR[=\fIextended\fR]
.RS 4
Prints the version of dvisvgm and exits\&. If the optional argument is set to
\fIyes\fR, the version numbers of the linked libraries are printed as well\&.
.RE
.PP
\fB\-z, \-\-zip\fR[=\fIlevel\fR]
.RS 4
Creates a compressed SVG file with suffix \&.svgz\&. The optional argument specifies the compression level\&. Valid values are in the range of 1 to 9 (default value is 9)\&. Larger values cause better compression results but take more computation time\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBCaution\fR
.ps -1
.br
This option cannot be combined with
\fB\-s, \-\-stdout\fR\&.
.sp .5v
.RE
.RE
.SH "SUPPORT OF SPECIALS"
.sp
dvisvgm supports several sets of \fIspecial commands\fR that can be used to enrich DVI files with additional features, like color, graphics or hyperlinks\&. The evaluation of special commands is delegated to various handlers\&. Each handler is responsible for all special statements of the same command set, i\&.e\&. commands beginning with the same prefix\&. To get a list of actually provided special handlers, use option \fB\-\-list\-specials\fR (see above)\&.
.PP
\fBbgcolor\fR
.RS 4
Special statement for changing the background/page color\&. Since SVG 1\&.1 doesn\(cqt support background colors, dvisvgm inserts a rectangle of the chosen color\&. In the current version, this rectangle always gets the size of the minimal bounding box\&. This command is part of the color special set but is handled separately in order to let the user turn it off\&. For an overview of the command syntax, see the documentation of dvips, for instance\&.
.RE
.PP
\fBcolor\fR
.RS 4
Statements of this command set provide instructions to change the text/paint color\&. For an overview of the exact syntax, see the documentation of dvips, for instance\&.
.RE
.PP
\fBdvisvgm\fR
.RS 4
dvisvgm offers its own small set of specials\&. The following list gives a brief overview\&.
.PP
\fBdvisvgm:raw\fR \fItext\fR
.RS 4
Adds an arbitrary sequence of characters to the SVG output\&. dvisvgm does not perform any validation here, thus the user has to ensure that the resulting SVG is still valid\&. Parameter
\fItext\fR
may contain the macros
\fB{?x}\fR,
\fB{?y}\fR, and
\fB{?color}\fR
that are expanded to the current
\fIx\fR
or
\fIy\fR
coordinate and the current color, respectively\&. Also, macro
\fB{?nl}\fR
expands to a newline character\&.
.RE
.PP
\fBdvisvgm:img\fR \fIwidth\fR \fIheight\fR \fIfile\fR
.RS 4
Creates an image element at the current graphic position referencing the given file\&. JPEG, PNG, and SVG images can be used here\&. However, dvisvgm does not check the file format or the file name suffix\&. The lengths
\fIwidth\fR
and
\fIheight\fR
must be given as plain floating point numbers in TeX point units (1in = 72\&.27pt)\&.
.RE
.PP
\fBdvisvgm:bbox\fR n[ew] \fIname\fR
.RS 4
Defines or resets a local bounding box called
\fIname\fR\&. The name may consist of letters and digits\&. While processing a DVI page, dvisvgm continuously updates the (global) bounding box of the current page in order to determine the minimal rectangle containing all visible page components (characters, images, drawing elements etc\&.) Additionally to the global bounding box, the user can request an arbitrary number of named local bounding boxes\&. Once defined, these boxes are updated together with the global bounding box starting with the first character that follows the definition\&. Thus, the local boxes can be used to compute the extent of parts of the page\&. This is useful for scenarios where the generated SVG file is post\-processed\&. In conjunction with special dvisvgm:raw, the macro
\fB{?bbox \fR\fB\fIname\fR\fR\fB}\fR
expands to the four values
\fIx\fR,
\fIy\fR,
\fIw\fR, and
\fIh\fR
(separated by spaces) specifying the coordinates of the upper left corner, width, and height of the local box
\fIname\fR\&. If box
\fIname\fR
wasn\(cqt previously defined, all four values equal zero\&.
.RE
.PP
\fBdvisvgm:bbox\fR \fIwidth\fR \fIheight\fR [\fIdepth\fR]
.RS 4
Updates the bounding box of the current page by embedding a virtual rectangle (\fIx\fR,
\fIy\fR,
\fIwidth\fR,
\fIheight\fR) where the lower left corner is located at the current DVI drawing position (\fIx\fR,\fIy\fR)\&. If the optional parameter
\fIdepth\fR
is specified, dvisvgm embeds a second rectangle (\fIx\fR,
\fIy\fR,
\fIwidth\fR, \-\fIdepth\fR)\&. The lengths
\fIwidth\fR,
\fIheight\fR
and
\fIdepth\fR
must be given as plain floating point numbers in TeX point units (1in = 72\&.27pt)\&. Depending on size and position of the virtual rectangle, this command either enlarges the overall bounding box or leaves it as is\&. It\(cqs not possible to reduce its extent\&. This special should be used in conjunction with
\fBdvisvgm:raw\fR
in order to update the viewport of the page properly\&.
.RE
.PP
\fBdvisvgm:bbox\fR a[bs] \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
.RS 4
This variant of the bbox special updates the bounding box by embedding a virtual rectangle (\fIx1\fR,\fIy1\fR,\fIx2\fR,\fIy2\fR)\&. The points (\fIx1\fR,\fIy1\fR) and (\fIx2\fR,\fIy2\fR) denote two diagonal corners of the rectangle given in TeX point units\&.
.RE
.PP
\fBdvisvgm:bbox\fR f[ix] \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
.RS 4
This variant of the bbox special assigns an absolute (final) bounding box to the resulting SVG\&. After executing this command, dvisvgm doesn\(cqt further alter the bounding box coordinates, except this special is called again later\&. The points (\fIx1\fR,\fIy1\fR) and (\fIx2\fR,\fIy2\fR) denote two diagonal corners of the rectangle given in TeX point units\&.
.sp
The following TeX snippet adds two raw SVG elements to the output and updates the bounding box accordingly:
.sp
.if n \{\
.RS 4
.\}
.nf
\especial{dvisvgm:raw <circle cx=\*(Aq{?x}\*(Aq cy=\*(Aq{?y}\*(Aq r=\*(Aq10\*(Aq stroke=\*(Aqblack\*(Aq fill=\*(Aqred\*(Aq/>}
\especial{dvisvgm:bbox 20 10 10}

\especial{dvisvgm:raw <path d=\*(AqM50 200 L10 250 H100 Z\*(Aq stroke=\*(Aqblack\*(Aq fill=\*(Aqblue\*(Aq/>}
\especial{dvisvgm:bbox abs 10 200 100 250}
.fi
.if n \{\
.RE
.\}
.RE
.RE
.PP
\fBem\fR
.RS 4
These specials were introduced with the emTeX distribution by Eberhard Mattes\&. They provide line drawing statements, instructions for embedding MSP, PCX, and BMP image files, as well as two PCL commands\&. dvisvgm supports only the line drawing statements and ignores all other em specials silently\&. A description of the command syntax can be found in the DVI driver documentation coming with emTeX (see CTAN)\&.
.RE
.PP
\fBpdf\fR
.RS 4
pdfTeX and dvipdfmx introduced several special commands related to the generation of PDF files\&. Currently, only two of them,
\fIpdf:mapfile\fR
and
\fIpdf:mapline\fR
are supported by dvisvgm\&. These specials allow modifying the font map tree during the processing of DVI files\&. They are used by CTeX, for example\&. dvisvgm supports both, the dvips and dvipdfm font map format\&. For further information on the command syntax and semantics, see the documentation of \epdfmapfile in the pdfTeX user manual\&.
.RE
.PP
\fBps\fR
.RS 4
The famous DVI driver dvips introduced its own set of specials in order to embed PostScript code into DVI files, which greatly improves the capabilities of DVI documents\&. One aim of dvisvgm is to completely evaluate all PostScript snippets and to convert a large amount of it to SVG\&. However, in contrast to dvips, dvisvgm uses floating point arithmetics to compute the precise position of each graphic element, i\&.e\&. it doesn\(cqt round the coordinates\&. Therefore, the relative locations of the graphic elements may slightly differ from those computed by dvips\&.
.sp
Since PostScript is a rather complex language, dvisvgm does not try to implement its own PostScript interpreter but relies on Ghostscript instead\&. If the Ghostscript library was not linked while building dvisvgm, it is looked up and loaded dynamically during runtime\&. In this case, dvisvgm looks for
\fIlibgs\&.so\fR
on Unix\-like systems, and for
\fIgsdll32\&.dll\fR
or
\fIgsdll64\&.dll\fR
on Windows\&. You can override these default file names with environment variable
LIBGS
or the command\-line option
\fB\-\-libgs\fR\&. The library must be installed and reachable through the ld search path (*nix) or the PATH environment variable (Windows)\&. If it cannot be found, the processing of PostScript specials is disabled\&. Use option
\fB\-\-list\-specials\fR
to check whether PS support is available, i\&.e\&. the entry
\fIps\fR
is present\&.
.RE
.PP
\fBtpic\fR
.RS 4
The TPIC special set defines instructions for drawing simple geometric objects\&. Some LaTeX packages, like eepic and tplot, use these specials to describe graphics\&.
.RE
.SH "EXAMPLES"
.sp
.if n \{\
.RS 4
.\}
.nf
dvisvgm file
.fi
.if n \{\
.RE
.\}
.sp
Converts the first page of \fIfile\&.dvi\fR to \fIfile\&.svg\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
dvisvgm \-z file
.fi
.if n \{\
.RE
.\}
.sp
Converts the first page of \fIfile\&.dvi\fR to \fIfile\&.svgz\fR with default compression level 9\&.
.sp
.if n \{\
.RS 4
.\}
.nf
dvisvgm \-p5 \-z3 \-ba4\-l \-onewfile file
.fi
.if n \{\
.RE
.\}
.sp
Converts the fifth page of \fIfile\&.dvi\fR to \fInewfile\&.svgz\fR with compression level 3\&. The bounding box is set to DIN/ISO A4 in landscape format\&.
.sp
.if n \{\
.RS 4
.\}
.nf
dvisvgm \-\-transform="R20,w/3,2h/5 T1cm,1cm S2,3" file
.fi
.if n \{\
.RE
.\}
.sp
Converts the first page of \fIfile\&.dvi\fR to \fIfile\&.svg\fR where three transformations are applied\&.
.SH "ENVIRONMENT"
.sp
dvisvgm uses the \fBkpathsea\fR library for locating the files that it opens\&. Hence, the environment variables described in the library\(cqs documentation influence the converter\&.
.sp
If dvisvgm was linked without the Ghostscript library, and if PostScript support has not been disabled, the shared Ghostscript library is looked up during runtime via dlopen()\&. The environment variable LIBGS can be used to specify path and file name of the library\&.
.sp
The pre\-compiled Windows versions of dvisvgm require a working installation of MiKTeX 2\&.9 or above\&. dvisvgm does not work together with the portable edition of MiKTeX because it relies on MiKTeX\(cqs COM interface only accessible in a local installation\&. To enable the evaluation of PostScript specials, the original Ghostscript DLL \fIgsdll32\&.dll\fR must be present and reachable through the search path\&. 64\-bit Windows builds require the 64\-bit Ghostscript DLL \fIgsdll64\&.dll\fR\&. Both DLLs come with the corresponding Ghostscript installers available from www\&.ghostscript\&.com\&.
.sp
The environment variable DVISVGM_COLORS specifies the colors used to highlight various parts of dvisvgm\(cqs message output\&. It is only evaluated if option \fB\-\-color\fR is given\&. The value of DVISVGM_COLORS is a list of colon\-separated entries of the form \fIgg\fR=\fIBF\fR, where \fIgg\fR denotes one of the color group indicators listed below, and \fIBF\fR are two hexadecimal digits specifying the background (first digit) and foreground/text color (second digit)\&. The color color values are defined as follows: 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=gray, 8=bright red, 9=bright green, A=bright yellow, B=bright blue, C=bright magenta, D=bright cyan, E=bright gray, F=white\&. Depending on the terminal, the colors may differ\&. Rather than changing both the text and background color, it\(cqs also possible to change only one of them: An asterisk (*) in place of a hexadecimal digit indicates the default text or background color of the terminal\&.
.sp
All malformed entries in the list are silently ignored\&.
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
.sp
\fBer\fR
T}:T{
.sp
error messages
T}
T{
.sp
\fBwn\fR
T}:T{
.sp
warning messages
T}
T{
.sp
\fBpn\fR
T}:T{
.sp
messages about page numbers
T}
T{
.sp
\fBps\fR
T}:T{
.sp
page size messages
T}
T{
.sp
\fBfw\fR
T}:T{
.sp
information about the files written
T}
T{
.sp
\fBsm\fR
T}:T{
.sp
state messages
T}
T{
.sp
\fBtr\fR
T}:T{
.sp
messages of the glyph tracer
T}
T{
.sp
\fBpi\fR
T}:T{
.sp
progress indicator
T}
.TE
.sp 1
.sp
\fBExample:\fR er=01:pi=*5 sets the colors of error messages (er) to red (1) on black (0), and those of progress indicators (pi) to cyan (5) on default background (*)\&.
.SH "FILES"
.sp
The location of the following files is determined by the kpathsea library\&. To check the actual kpathsea configuration you can use the \fBkpsewhich\fR utility\&.
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
.sp
\fB*\&.enc\fR
T}:T{
.sp
Font encoding files
T}
T{
.sp
\fB*\&.fgd\fR
T}:T{
.sp
Font glyph data files (cache files created by dvisvgm)
T}
T{
.sp
\fB*\&.map\fR
T}:T{
.sp
Font map files
T}
T{
.sp
\fB*\&.mf\fR
T}:T{
.sp
Metafont input files
T}
T{
.sp
\fB*\&.pfb\fR
T}:T{
.sp
PostScript Type 1 font files
T}
T{
.sp
\fB*\&.pro\fR
T}:T{
.sp
PostScript header/prologue files
T}
T{
.sp
\fB*\&.tfm\fR
T}:T{
.sp
TeX font metric files
T}
T{
.sp
\fB*\&.ttf\fR
T}:T{
.sp
TrueType font files
T}
T{
.sp
\fB*\&.vf\fR
T}:T{
.sp
Virtual font files
T}
.TE
.sp 1
.SH "SEE ALSO"
.sp
\fBtex(1), mf(1), mktexmf(1), grodvi(1), potrace(1)\fR, and the \fBkpathsea library\fR info documentation\&.
.SH "RESOURCES"
.PP
Project home page
.RS 4

http://dvisvgm\&.sourceforge\&.net
.RE
.PP
SourceForge project site
.RS 4

http://sourceforge\&.net/projects/dvisvgm
.RE
.SH "BUGS"
.sp
Please report bugs using the bug tracker at Launchpad (see https://launchpad\&.net/dvisvgm)\&.
.SH "AUTHOR"
.sp
Written by Martin Gieseking <martin\&.gieseking@uos\&.de>
.SH "COPYING"
.sp
Copyright \(co 2005\-2013 Martin Gieseking\&. Free use of this software is granted under the terms of the GNU General Public License (GPL) version 3 or, (at your option) any later version\&.