'\" t .\" Title: dvisvgm .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.74.3 .\" Date: 11/09/2009 .\" Manual: dvisvgm Manual .\" Source: dvisvgm 0.8.7 .\" Language: English .\" .TH "DVISVGM" "1" "11/09/2009" "dvisvgm 0\&.8\&.7" "dvisvgm Manual" .\" ----------------------------------------------------------------- .\" * 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 program \fBdvisvgm\fR generates an SVG file from a given DVI file\&. DVI is the device independent output format produced by TeX and some other typesetting systems\&. Output from groff can be converted to DVI using grodvi\&. .sp The recent version of \fBdvisvgm\fR provides advanced conversion functionality but currently only one page can be converted even if the DVI file is made up of multiple pages\&. You can select the page to be processed with option \fB\-p\fR\&. \fBdvisvgm\fR should properly convert all pages that are made up of fonts and rules only\&. Additionally, some sets of specials are understood as well\&. For a more detailed overview, see section \fBsupport of specials\fR below\&. .sp Since SVG is a vector based graphics format, \fBdvisvgm\fR 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 \fBdvisvgm\fR is able to find a PFB file for a used font, it will read the necessary information from it\&. .sp TeX\(cqs main source for font descriptions is Metafont which produces bitmap output \&.That\(cqs why not all obtainable TeX fonts are available in PFB format\&. In these cases \fBdvisvgm\fR tries to vectorize Metafont\(cqs output 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 .RS 4 This option forces dvisvgm to trace not just 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\&. .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 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{ the page size stored in the DVI file will be used T} T{ \fBmin\fR T}:T{ the minimal bounding box will be computed and assigned T} T{ \fBnone\fR T}:T{ no bounding box will be 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 above mentioned size specifiers 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, \-\-scale\fR=\fIsx\fR[,\fIsy\fR] .RS 4 Scales page content horizontally by \fIsx\fR and vertically by \fIsy\fR\&. This option is equivalent to *\-TS*\fIsx\fR,\fIsy\fR\&. .RE .PP \fB\-C, \-\-cache\fR[=\fIdir\fR] .RS 4 To speed up the conversion process of bitmap fonts, \fBdvisvgm\fR saves intermediate conversion information in cache files\&. By default, these files are stored in $HOME/\&.dvisvgm\&. 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\&. .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\&. 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, \-\-map\-file\fR=\fIfile\fR .RS 4 Sets the map file that is used to look up font names and encodings\&. \fBdvisvgm\fR does not provide its own map file but tries to use available ones coming with \fBdvips\fR or \fBdvipdfm\fR\&. If option \fB\-m\fR is not given \fBdvisvgm\fR looks for ps2pk\&.map, dvipdfm\&.map, and psfonts\&.map (in this order)\&. Without further options, the file specified by option \fB\-m\fR will be used instead of the default maps\&. If you want \fBdvisgvm\fR to load the given file additionally to the default maps, add a leading \fI+\fR to the file/path, e\&.g\&. \-\-map\-file=+myfonts\&.map\&. For further information about the file format see the manuals of \fBdvips\fR and \fBdvipdfm\fR\&. .RE .PP \fB\-M, \-\-mag\fR=\fIfactor\fR .RS 4 Sets the maginfication factor used for 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\-n, \-\-no\-fonts\fR .RS 4 If this option is given, \fBdvisvgm\fR doesn\(cqt create font elements but uses paths instead\&. The resulting SVG file is usually bigger but concurrently more compatible with most applications that don\(cqt support SVG fonts yet\&. This option implies \fB\-\-no\-styles\fR\&. .RE .PP \fB\-S, \-\-no\-specials\fR[=\fInames\fR] .RS 4 Disable processing of special commands that are 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 a unique identifier referencing a 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, \fBdvisvgm\fR uses 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\-\-no\-mktexmf\fR .RS 4 Suppresses the generation of missing font files\&. If \fBdvisvgm\fR can\(cqt find a font file through the kpathsea lookup mechanism, it calls the external tools mktextfm or mktexmf by default\&. This option disables these calls\&. .RE .PP \fB\-o, \-\-output\fR=\fIfile\fR .RS 4 Sets the name of the output file\&. .RE .PP \fB\-p, \-\-page\fR=\fInumber\fR .RS 4 With this option you can choose the page to be processed\&. Please consider that the parameter of this option 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\&. If this option is omitted, the first page will be selected\&. .RE .PP \fB\-P, \-\-progress\fR[=\fIskip\fR] .RS 4 Enables a simple progress indicator shown when DVI specials are processed, since this can be a time\-consuming operation, especially when PostScript specials are involved\&. The optional non\-negative parameter \fIskip\fR controls the indicator length: Every time a set of \fIskip\fR specials has been processed, an indicator character is printed\&. Therefore, smaller values lead to a longer, more frequently updated progress indicator\&. .RE .PP \fB\-r, \-\-rotate\fR=\fIangle\fR .RS 4 Rotates 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 output to a file but redirect it to \fBstdout\fR\&. .RE .PP \fB\-t, \-\-translate\fR=\fItx\fR[,\fIty\fR] .RS 4 Translates (moves) 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\-T, \-\-transform\fR=\fIcommands\fR .RS 4 Applies a sequence of transformations to the SVG content\&. Each transformation is described by a \fIcommand\fR that begins 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) 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 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 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 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 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) 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) 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\&. .RE .sp .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 (substraction), \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 .SH "SUPPORT OF SPECIALS" .sp \fBdvisvgm\fR supports several sets of special commands that can be used to enrich DVI files with additional features, like color, graphics or hyperlinks\&. The evaluation of special commands is done by various handlers, where 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, \fBdvisvgm\fR 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 \fBdvips\fR, 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 \fBdvips\fR, for instance\&. .RE .PP \fBdvisvgm\fR .RS 4 \fBdvisvgm\fR 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\&. \fBdvisvgm\fR does not perform any validation here, thus the user of this special has to ensure that the resulting SVG is still valid\&. The parameter \fItext\fR may contain the macros \fB{?x}\fR, \fB{?y}\fR, and \fB{?color}\fR which are expanded to the current \fIx\fR or \fIy\fR coordinate and the current color, respectively\&. Also, the 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, \fBdvisvgm\fR 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 \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 properly update the viewport of the page\&. .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 } \especial{dvisvgm:bbox 20 10 10} \especial{dvisvgm:raw } \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\&. \fBdvisvgm\fR supports only the line drawing statements, all other em specials are silently ignored\&. A description of the command syntax can be found in the DVI driver documentation coming with emTeX (see CTAN)\&. .RE .PP \fBps\fR .RS 4 The famous DVI driver \fBdvips\fR 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 \fBdvisvgm\fR is to completely evaluate the PostScript code and to convert a large amount of it to SVG\&. Since PostScript is a rather complex language, \fBdvisvgm\fR does not try to implement its own PostScript interpreter but uses Ghostscript instead\&. The Ghostscript shared library (libgs\&.so on Linux systems, gsdll32\&.dll on Windows) is loaded dynamically during runtime\&. For this reason, it must be installed and reachable through the PATH environment variable\&. If the Ghostscript library cannot be found, the evaluation 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 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 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 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 first page of \fIfile\&.dvi\fR to \fIfile\&.svg\fR where three transformations are applied\&. .SH "ENVIRONMENT" .sp \fBdvisvgm\fR 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 The pre\-compiled Windows version of \fBdvisvgm\fR requires a working installation of MiKTeX 2\&.7 or above\&. To enable evaluation of PostScript specials, the original Ghostscript DLL must be present\&. .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 "AUTHOR" .sp Written by Martin Gieseking .SH "COPYING" .sp Copyright \(co 2005\-2009 by 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\&.