1DVISVGM(1) dvisvgm Manual DVISVGM(1)
2
6 dvisvgm - converts DVI files to the XML-based SVG format
7
9 dvisvgm [ options ] file [.dvi]
10
12 The command-line utility dvisvgm converts DVI files, as generated by
13 TeX/LaTeX, to the XML-based scalable vector graphics format SVG. Since
14 the current SVG standard 1.1 doesn’t specify multi-page graphics,
15 dvisvgm creates separate SVG files for each DVI page. Because of
16 compatibility reasons, only the first page is converted by default. In
17 order to select a different page or arbitrary page sequences, use
18 option -p which is described below.
19 dvisvgm should properly convert all pages that are made up of fonts and
21 rules only. However, the utility also supports a couple of DVI
22 extensions defined in terms of DVI specials. For a more detailed
23 overview, see section support of specials below.
24 As SVG is a vector based graphics format, dvisvgm tries to convert the
26 glyph outlines of all used fonts into scalable path descriptions. The
27 fastest way to do that is to extract the path information from PFB
28 (PostScript Type 1) files. So, if dvisvgm is able to find a PFB file
29 for a required font, it will read the necessary information from this
30 file.
31 TeX’s main source for font descriptions is Metafont though, which
33 produces bitmap output. That’s why not all obtainable TeX fonts are
34 available in PFB format. In these cases dvisvgm tries to vectorize
35 Metafont’s output (GF fonts) by tracing the glyph bitmaps. The results
36 are not as perfect as most (manually optimized) PFB outlines but are
37 nonetheless really nice in most cases.
38
40 -a, --trace-all=[retrace]
41 This option forces dvisvgm to trace not only the actually needed
42 glyphs but all glyphs of all bitmap fonts used in the DVI file.
43 Since the tracing results are stored in the font cache, all
44 following DVI conversions (without option --trace-all) where these
45 fonts are involved, will be much faster. By default, dvisvgm traces
46 only the actually needed glyphs and adds them to the cache. The
47 boolean option retrace determines how to handle glyphs already
48 stored in the cache. By default, these glyphs are skipped. Setting
49 argument retrace to yes or true forces dvisvgm to trace the
50 corresponding bitmaps again.
51 Note
53 This option only takes affect if font caching is active. Thus,
54 --trace-all cannot be combined with option --cache=none.
55 -b, --bbox=fmt
57 Sets the bounding box of the generated graphic to the specified
58 format. The parameter fmt takes either one of the format specifiers
59 listed below, or a sequence of four comma- or whitespace-separated
60 length values x1, y1, x2 and y2. The latter define two diagonal
61 corners of the bounding box. Each length value consists of a
62 floating point number and an optional length unit (pt, bp, cm, mm,
63 in, or pc). If the unit is omitted, TeX points (pt) are assumed.
64 It’s also possible to give only one length value l. In this case
66 the minimal bounding box is computed and enlarged by adding (-l,-l)
67 to the upper left and (l,l) to the lower right corner.
68 Alternatively, the following format specifiers are supported:
70 International DIN/ISO paper sizes
72 An, Bn, Cn, Dn, where n is a non-negative integer, e.g. A4 or
73 a4 for DIN/ISO A4 format (210mm × 297mm).
74 North American paper sizes
76 invoice, executive, legal, letter, ledger
77 Special bounding box sizes
79 dvi page size stored in the
81 DVI file
82 min computes the
83 minimal/tightest bounding
84 box
85 none no bounding box is
86 assigned
87 Page orientation
90 The default page orientation for DIN/ISO and American paper sizes
91 is portrait, i.e. width < height. Appending -landscape or simply
92 -l to the format string switches to landscape mode (width >
93 height). For symmetry reasons you can also explicitly add -portrait
94 or -p to indicate the default portrait format. Note that these
95 suffixes are part of the size string and not separate options.
96 Thus, they must directly follow the size specifier without
97 additional blanks. Furthermore, the orientation suffixes can’t be
98 used with dvi, min, and none.
99 Note
101 Option -b, --bbox only affects the bounding box and does not
102 transform the page content. Hence, if you choose a landscape
103 format, the page won’t be rotated.
104 -c, --scale=sx[,sy]
106 Scales the page content horizontally by sx and vertically by sy.
107 This option is equivalent to -TSsx,sy.
108 -C, --cache[=dir]
110 To speed up the conversion process of bitmap fonts, dvisvgm saves
111 intermediate conversion information in cache files. By default,
112 these files are stored in $HOME/.dvisvgm/cache. If you prefer a
113 different location, use option --cache to overwrite the default.
114 Furthermore, it is also possible to disable the font caching
115 mechanism completely with option --cache=none. If argument dir is
116 omitted, dvisvgm prints the path of the default cache directory and
117 some information about the stored fonts. Additionally, outdated and
118 corrupted cache files are removed.
119 --color
121 Enables colorization of messages printed during the conversion
122 process.
123 -e, --exact
125 If this option is given, dvisvgm computes the precise bounding box
126 of each character. By default, the values stored in the font’s TFM
127 file are used to determine a glyph’s extent. As these values are
128 intended to realize optimal character placements and are not
129 designed to represent the exact dimensions, they don’t necessarily
130 correspond with the bounds of the visual glyphs. Thus, width and/or
131 height of some glyphs may be larger than the respective TFM values.
132 As a result, this can lead to clipped characters at the bounds of
133 the SVG graphic. With option --exact, dvisvgm analyzes the actual
134 shape of each character and derives a usually tight bounding box.
135 -h, --help
137 Prints a short summary of all available command-line options.
138 --libgs=filename
140 This option is only available if the Ghostscript library is not
141 directly linked to dvisvgm and PostScript support was not
142 completely disabled during compilation. In this case, dvisvgm tries
143 to load the shared GS library dynamically during runtime. By
144 default, it expects the library’s name to be libgs.so (on Unix-like
145 systems) or gsdll32.dll (Windows). Option --libgs can be used to
146 give a different name. Alternatively, the GS library name can also
147 be set by the environment variable LIBGS. The latter has less
148 precedence than the command-line option.
149 -l, --list-specials
151 Prints a list of registered special handlers and exits. Each
152 handler processes a set of special statements belonging to the same
153 category. The categories are usually identified by the prefix of
154 the special statements. It’s usually a leading word separated from
155 the rest of the statement by a colon or a blank, e.g. color or ps.
156 --keep
158 Disables the removal of temporary files as created by Metafont
159 (usually .gf, .tfm, and .log files).
160 -m, --map-file=file
162 Sets the map file used to look up font names and encodings.
163 dvisvgm does not provide its own map file but tries to use
164 available ones coming with dvips or dvipdfm. If option -m is not
165 given, dvisvgm looks for ps2pk.map, dvipdfm.map, and psfonts.map
166 (in this order). Without further options, the file specified by
167 option -m will be used instead of the default maps. If you want
168 dvisgvm to load the given file additionally to the default maps,
169 add a leading + to the file/path, e.g. --map-file=+myfonts.map.
170 For further information about the file format, see the manuals of
171 dvips and dvipdfm.
172 -M, --mag=factor
174 Sets the maginfication factor applied in conjunction with Metafont
175 calls prior tracing the glyphs. The larger this value the better
176 the tracing results. Nevertheless, large magnification values can
177 cause Metafont arithmetic errors due to number overflows. So, use
178 this option with care. The default setting usually produces nice
179 results.
180 -n, --no-fonts[=variant]
182 If this option is given, dvisvgm doesn’t create SVG font elements
183 but uses paths instead. The resulting SVG files tends to be larger
184 but concurrently more compatible with most applications that don’t
185 support SVG fonts yet. The optional argument variant selects the
186 method how to substitute fonts by paths. Variant 0 creates path and
187 use elements. Variant 1 creates path elements only. Option
188 --no-fonts implies --no-styles.
189 -S, --no-specials[=names]
191 Disable processing of special commands embedded in the DVI file. If
192 no further parameter is given, all specials are ignored. To
193 selectively disable sets of specials, an optional comma-separated
194 list of names can be appended to this option. A name is the unique
195 identifier referencing the intended special handler. Option
196 --list-specials lists all currently available handlers and their
197 names. All unsupported special statements are silently ignored.
198 --no-styles
200 By default, dvisvgm uses CSS styles and class attributes to
201 reference fonts because it’s more compact than repeatedly set the
202 complete font information in each text element. However, if you
203 prefer direct font references, the default behavior can be disabled
204 with option --no-styles.
205 --no-mktexmf
207 Suppresses the generation of missing font files. If dvisvgm can’t
208 find a font file through the kpathsea lookup mechanism, it calls
209 the external tools mktextfm or mktexmf by. This option disables
210 these calls.
211 -o, --output=pattern
213 Sets the name pattern of the output file. Parameter pattern is a
214 string that may contain the variables %f and %p. %f stands for the
215 base name of the DVI file, i.e. the DVI filename without suffix,
216 and %p is the current page number. By default, the pattern is
217 %f-%p.svg if the DVI file consists of more than one page, and
218 %f.svg otherwise. That means, a DVI file foo.dvi is converted to
219 foo.svg if foo.dvi is a single-page document. Otherwise, multiple
220 SVG files foo-01.svg, foo-02.svg, etc. are produced. In Windows
221 environments, the percent sign indicates dereferenced environment
222 variables, and must therefore be protected by a second percent
223 sign, e.g. --output=%%f-%%p.
224 -p, --page=ranges
226 This option sets the pages to be processed. Parameter ranges
227 consists of a comma-separated list of single page numbers and/or
228 page ranges. A page range is a pair of numbers separated by a
229 hyphen, e.g. 5-12. Thus, a page sequence might look like this:
230 2-4,6,9-12,15. It doesn’t matter if a page is given more than once
231 or if page ranges overlap. dvisvgm always extracts the page
232 numbers in ascending order and converts them only once. In order to
233 stay compatible with previous versions, the default page sequence
234 is 1. dvisvgm therefore converts only the first page and not the
235 whole document in case option --page is not given. Usually, page
236 ranges consist of two numbers denoting the first and last page to
237 be converted. If the conversion is to be started at page 1, or if
238 it should continue up to the last DVI page, the first or second
239 range number can be omitted, respectively. Example: --page=-10
240 converts all pages up to page 10, --page=10- converts all pages
241 starting with page 10. Please consider that the page values don’t
242 refer to the page numbers printed on the page. Instead, the
243 physical page count is expected, where the first page always gets
244 number 1.
245 -P, --progress[=delay]
247 Enables a simple progress indicator shown when time-consuming
248 operations like PostScript specials are processed. The indicator
249 doesn’t appear before the given delay (in seconds) has elapsed. The
250 default delay value is 0.5 seconds.
251 -r, --rotate=angle
253 Rotates the page content clockwise by angle degrees around the page
254 center. This option is equivalent to -TRangle.
255 -s, --stdout
257 Don’t write the SVG output to a file but redirect it to stdout.
258 -t, --translate=tx[,ty]
260 Translates (moves) the page content in direction of vector (tx,ty).
261 This option is equivalent to -TTtx,ty.
262 -T, --transform=commands
264 Applies a sequence of transformations to the SVG content. Each
265 transformation is described by a command beginning with a capital
266 letter followed by a list of comma-separated parameters. Following
267 transformation commands are supported:
268 T tx[,ty]
270 Translates (moves) the page in direction of vector (tx,ty). If
271 ty is omitted, ty=0 is assumed. The expected unit length of tx
272 and ty are TeX points (1pt = 1/72.27in). However, there are
273 several constants defined to simplify the unit conversion (see
274 below).
275 S sx[,sy]
277 Scales the page horizontally by sx and vertically by sy. If sy
278 is omitted, sy=sx is assumed.
279 R angle[,x,y]
281 Rotates the page clockwise by angle degrees around point (x,y).
282 If the optional arguments x and y are omitted, the page will be
283 rotated around its center depending on the chosen page format.
284 When option -bnone is given, the rotation center is origin
285 (0,0).
286 KX angle
288 Skews the page along the x-axis by angle degrees. Argument
289 angle can take any value except 90+180k, where k is an integer.
290 KY angle
292 Skews the page along the y-axis by angle degrees. Argument
293 angle can take any value except 90+180k, where k is an integer.
294 FH [y]
296 Mirrors (flips) the page at the horizontal line through point
297 (0,y). Omitting the optional argument leads to y=h/2, where h
298 denotes the page height (see pre-defined constants below).
299 FV [x]
301 Mirrors (flips) the page at the vertical line through point
302 (x,0). Omitting the optional argument leads to x=w/2, where w
303 denotes the page width (see pre-defined constants below).
304 M m1,...,m6
306 Applies a transformation described by the 3×3 matrix
307 ((m1,m2,m3),(m4,m5,m6),(0,0,1)), where the inner triples denote
308 the rows.
309 Note
312 All transformation commands of option -T, --transform are
313 applied in the order of their appearance. Multiple commands can
314 optionally be separated by spaces. In this case the whole
315 transformation string has to be enclosed in double quotes. All
316 parameters are expressions of floating point type. You can
317 either give plain numbers or arithmetic terms combined by the
318 operators + (addition), - (substraction), * (multiplication), /
319 (division) or % (modulo) with common associativity and
320 precedence rules. Parentheses may be used as well.
321 Additionally, some pre-defined constants are provided:
323 ux horizontal position of
325 upper left page corner in
326 TeX point units
327 uy vertical position of upper
328 left page corner in TeX
329 point units
330 h page height in TeX point
332 units (0 in case of
333 -bnone)
334 w page width in TeX point
335 units (0 in case of
336 -bnone)
337 Furthermore, you can use the length constants pt, mm, cm and
339 in, e.g. 2cm or 1.6in. Thus, option -TT1in,0R45 moves the page
340 content 1 inch to the right and rotates it by 45 degrees around
341 the page center afterwards.
342 For single transformations you can also use options -c, -t and
344 -r. Note that the order in which these options are given is not
345 significant, i.e. you can’t use them to describe transformation
346 sequences. They are simply independent shorthand options for
347 common transformations.
348
350 dvisvgm supports several sets of special commands that can be used to
351 enrich DVI files with additional features, like color, graphics or
352 hyperlinks. The evaluation of special commands is delegated to various
353 handlers. Each handler is responsible for all special statements of the
354 same command set, i.e. commands beginning with the same prefix. To get
355 a list of actually provided special handlers, use option
356 --list-specials (see above).
357 bgcolor
359 Special statement for changing the background/page color. Since SVG
360 1.1 doesn’t support background colors, dvisvgm inserts a rectangle
361 of the chosen color. In the current version, this rectangle always
362 gets the size of the minimal bounding box. This command is part of
363 the color special set but is handled separately in order to let the
364 user turn it off. For an overview of the command syntax, see the
365 documentation of dvips, for instance.
366 color
368 Statements of this command set provide instructions to change the
369 text/paint color. For an overview of the exact syntax, see the
370 documentation of dvips, for instance.
371 dvisvgm
373 dvisvgm offers its own small set of specials. The following list
375 gives a brief overview.
376 dvisvgm:raw text
378 Adds an arbitrary sequence of characters to the SVG output.
379 dvisvgm does not perform any validation here, thus the user has
380 to ensure that the resulting SVG is still valid. Parameter text
381 may contain the macros {?x}, {?y}, and {?color} that are
382 expanded to the current x or y coordinate and the current
383 color, respectively. Also, macro {?nl} expands to a newline
384 character.
385 dvisvgm:img width height file
387 Creates an image element at the current graphic position
388 referencing the given file. JPEG, PNG, and SVG images can be
389 used here. However, dvisvgm does not check the file format or
390 the file name suffix. The lengths width and height must be
391 given as plain floating point numbers in TeX point units (1in =
392 72.27pt).
393 dvisvgm:bbox n[ew] name
395 Defines or resets a local bounding box called name. The name
396 may consist of letters and digits. While processing a DVI page,
397 dvisvgm continuously updates the (global) bounding box of the
398 current page in order to determine the minimal rectangle
399 containing all visible page components (characters, images,
400 drawing elements etc.) Additionally to the global bounding box,
401 the user can request an arbitrary number of named local
402 bounding boxes. Once defined, these boxes are updated together
403 with the global bounding box starting with the first character
404 that follows the definition. Thus, the local boxes can be used
405 to compute the extent of parts of the page. This is useful for
406 scenarios where the generated SVG file is post-processed. In
407 conjunction with special dvisvgm:raw, the macro {?bbox name}
408 expands to the four values x, y, w, and h (separated by spaces)
409 specifying the coordinates of the upper left corner, width, and
410 height of the local box name. If box name wasn’t previously
411 defined, all four values equal zero.
412 dvisvgm:bbox width height [depth]
414 Updates the bounding box of the current page by embedding a
415 virtual rectangle (x, y, width, height) where the lower left
416 corner is located at the current DVI drawing position (x,y). If
417 the optional parameter depth is specified, dvisvgm embeds a
418 second rectangle (x, y, width, -depth). The lengths width,
419 height and depth must be given as plain floating point numbers
420 in TeX point units (1in = 72.27pt). Depending on size and
421 position of the virtual rectangle, this command either enlarges
422 the overall bounding box or leaves it as is. It’s not possible
423 to reduce its extent. This special should be used in
424 conjunction with dvisvgm:raw in order to update the viewport of
425 the page properly.
426 dvisvgm:bbox a[bs] x1 y1 x2 y2
428 This variant of the bbox special updates the bounding box by
429 embedding a virtual rectangle (x1,y1,x2,y2). The points (x1,y1)
430 and (x2,y2) denote two diagonal corners of the rectangle given
431 in TeX point units.
432 dvisvgm:bbox f[ix] x1 y1 x2 y2
434 This variant of the bbox special assigns an absolute (final)
435 bounding box to the resulting SVG. After executing this
436 command, dvisvgm doesn’t further alter the bounding box
437 coordinates, except this special is called again later. The
438 points (x1,y1) and (x2,y2) denote two diagonal corners of the
439 rectangle given in TeX point units.
440 The following TeX snippet adds two raw SVG elements to the
442 output and updates the bounding box accordingly:
443 \special{dvisvgm:raw <circle cx='{?x}' cy='{?y}' r='10' stroke='black' fill='red'/>}
445 \special{dvisvgm:bbox 20 10 10}
446 \special{dvisvgm:raw <path d='M50 200 L10 250 H100 Z' stroke='black' fill='blue'/>}
448 \special{dvisvgm:bbox abs 10 200 100 250}
449 em
451 These specials were introduced with the emTeX distribution by
452 Eberhard Mattes. They provide line drawing statements, instructions
453 for embedding MSP, PCX, and BMP image files, as well as two PCL
454 commands. dvisvgm supports only the line drawing statements and
455 ignores all other em specials silently. A description of the
456 command syntax can be found in the DVI driver documentation coming
457 with emTeX (see CTAN).
458 ps
460 The famous DVI driver dvips introduced its own set of specials in
461 order to embed PostScript code into DVI files, which greatly
462 improves the capabilities of DVI documents. One aim of dvisvgm is
463 to completely evaluate all PostScript snippets and to convert a
464 large amount of it to SVG. However, in contrast to dvips, dvisvgm
465 uses floating point arithmetics to compute the precise position of
466 each graphic element, i.e. it doesn’t round the corrdinates.
467 Therefore, the relative locations of the graphic elements may
468 slightly differ from those computed by dvips.
469 Since PostScript is a rather complex language, dvisvgm does not try
471 to implement its own PostScript interpreter but relies on
472 Ghostscript instead. If the Ghostscript library was not linked
473 while building dvisvgm, it is looked up and dynamically loaded
474 during runtime. In this case, dvisvgm looks for libgs.so on
475 Unix-like systems, and for gsdll32.dll on Windows. You can override
476 these default file names with the environment variable LIBGS. The
477 library must be installed and must be reachable through the ld
478 search path (*nix) or the PATH environment variable (Windows). If
479 it cannot be found, the evaluation of PostScript specials is
480 disabled. Use option --list-specials to check whether PS support is
481 available, i.e. the entry ps is present.
482 tpic
484 The TPIC special set defines instructions for drawing simple
485 geometric objects. Some LaTeX packages, like eepic and tplot, use
486 these specials to describe graphics.
487
489 dvisvgm file
490 Converts first page of file.dvi to file.svg.
492 dvisvgm -z file
494 Converts first page of file.dvi to file.svgz with default compression
496 level 9.
497 dvisvgm -p5 -z3 -ba4-l -onewfile file
499 Converts fifth page of file.dvi to newfile.svgz with compression level
501 3. The bounding box is set to DIN/ISO A4 in landscape format.
502 dvisvgm --transform="R20,w/3,2h/5 T1cm,1cm S2,3" file
504 Converts first page of file.dvi to file.svg where three transformations
506 are applied.
507
509 dvisvgm uses the kpathsea library for locating the files that it opens.
510 Hence, the environment variables described in the library’s
511 documentation influence the converter.
512 If dvisvgm was linked without the Ghostscript library, and if
514 PostScript support has not been disabled, the shared Ghostscript
515 library is looked up during runtime. The environment variable LIBGS can
516 be used to specify path and file name of the library.
517 The pre-compiled Windows version of dvisvgm requires a working
519 installation of MiKTeX 2.7 or above. To enable evaluation of PostScript
520 specials, the original Ghostscript DLL must be present and reachable
521 through the search path.
522
524 The location of the following files is determined by the kpathsea
525 library. To check the actual kpathsea configuration you can use the
526 kpsewhich utility.
527 *.enc Font encoding files
531 *.fgd Font glyph data files
533 (cache files created by
534 dvisvgm)
535 *.map Font map files
537 *.mf Metafont input files
539 *.pfb PostScript Type 1 font
541 files
542 *.pro PostScript header/prologue
544 files
545 *.tfm TeX font metric files
547 *.ttf TrueType font files
549 *.vf Virtual font files
551
554 tex(1), mf(1), mktexmf(1), grodvi(1), potrace(1), and the kpathsea
555 library info documentation.
556
558 Project home page
559 http://dvisvgm.sourceforge.net
561 SourceForge project site
563 http://sourceforge.net/projects/dvisvgm
565
567 Written by Martin Gieseking <martin.gieseking@uos.de>
568
570 Copyright © 2005-2011 by Martin Gieseking. Free use of this software is
571 granted under the terms of the GNU General Public License (GPL) version
572 3 or, (at your option) any later version.
573dvisvgm 1.0.9 10/14/2011 DVISVGM(1)