1DVISVGM(1) dvisvgm Manual DVISVGM(1)
2
6 dvisvgm - converts DVI and EPS files to the XML-based SVG format
7
9 dvisvgm [ options ] file [.dvi]
10 dvisvgm -E [ options ] file [.eps]
12
14 The command-line utility dvisvgm converts DVI files, as generated by
15 TeX/LaTeX, to the XML-based scalable vector graphics format SVG. It
16 supports the classic DVI format 2 as well as format 3 (created by pTeX
17 in vertical mode), and the XeTeX formats 5 and 6 which are also known
18 as XDV. Besides the basic DVI commands, dvisvgm also evaluates many
19 so-called specials which heavily extend the capabilities of the plain
20 DVI format. For a more detailed overview, see section Supported
21 Specials below.
22 Since the current SVG standard 1.1 doesn’t specify multi-page graphics,
24 dvisvgm creates separate SVG files for each DVI page. Because of
25 compatibility reasons, only the first page is converted by default. In
26 order to select a different page or arbitrary page sequences, use
27 option -p which is described below.
28 SVG is a vector-based graphics format and therefore dvisvgm tries to
30 convert the glyph outlines of all fonts referenced in a DVI page
31 section to scalable path descriptions. The fastest way to achieve this
32 is to extract the path information from vector-based font files
33 available in PFB, TTF, or OTF format. If dvisvgm is able to find such a
34 file, it extracts all necessary outline information about the glyphs
35 from it.
36 However, TeX’s main source for font descriptions is Metafont, which
38 produces bitmap output (GF files). That’s why not all obtainable TeX
39 fonts are available in a scalable format. In these cases, dvisvgm tries
40 to vectorize Metafont’s output by tracing the glyph bitmaps. The
41 results are not as perfect as most (manually optimized) PFB or OTF
42 counterparts, but are nonetheless really nice in most cases.
43 When running dvisvgm without option --no-fonts, it creates font
45 elements (<font>...</font>) to embed the font data into the SVG files.
46 Unfortunately, only few SVG renderes support these elements yet. Most
47 web browsers and vector graphics applications don’t evaluate them
48 properly so that the text components of the resulting graphics might
49 look strange. In order to create more compatible SVG files,
50 command-line option --no-fonts can be given to replace the font
51 elements by plain graphics paths.
52
54 dvisvgm provides a POSIX-compliant command-line interface with short
55 and long option names. They may be given before and/or after the name
56 of the file to be converted. Also, the order of specifying the options
57 is not significant, i.e. you can add them in any order without changing
58 dvisvgm’s behavior. Certain options accept or require additional
59 parameters which are directly appended to or separated by whitespace
60 from a short option (e.g. -v0 or -v 0). Long options require an
61 additional equals sign (=) between option name and argument but without
62 any surrounding whitespace (e.g. --verbosity=0).
63 -a, --trace-all=[retrace]
65 This option forces dvisvgm to vectorize not only the glyphs
66 actually required to render the SVG file correctly – which is the
67 default –, but processes all glyphs of all fonts referenced in the
68 DVI file. Because dvisvgm stores the tracing results in a font
69 cache, all following conversions of these fonts will speed up
70 significantly. The boolean option retrace determines how to handle
71 glyphs already stored in the cache. By default, these glyphs are
72 skipped. Setting argument retrace to yes or true forces dvisvgm to
73 retrace the corresponding bitmaps again.
74 Note
76 This option only takes effect if font caching is active.
77 Therefore, --trace-all cannot be combined with option
78 --cache=none.
79 -b, --bbox=fmt
81 Sets the bounding box of the generated graphic to the specified
82 format. The parameter fmt takes either one of the format specifiers
83 listed below, or a sequence of four comma- or whitespace-separated
84 length values x1, y1, x2 and y2. The latter define the absolute
85 coordinates of two diagonal corners of the bounding box. Each
86 length value consists of a floating point number and an optional
87 length unit (pt, bp, cm, mm, in, or pc). If the unit is omitted,
88 TeX points (pt) are assumed.
89 It’s also possible to give only one length value l. In this case,
91 the minimal bounding box is computed and enlarged by adding (-l,-l)
92 to the upper left and (l,l) to the lower right corner.
93 Additionally, dvisvgm also supports the following format
95 specifiers:
96 International DIN/ISO paper sizes
98 An, Bn, Cn, Dn, where n is a non-negative integer, e.g. A4 or
99 a4 for DIN/ISO A4 format (210mm × 297mm).
100 North American paper sizes
102 invoice, executive, legal, letter, ledger
103 Special bounding box sizes
105 dvi page size stored in the
107 DVI file
108 min computes the
109 minimal/tightest bounding
110 box
111 none no bounding box is
112 assigned
113 preview bounding box data computed
114 by the preview package (if
115 present in the dvi file)
116 Page orientation
119 The default page orientation for DIN/ISO and American paper
120 sizes is portrait, i.e. width < height. Appending -landscape
121 or simply -l to the format string switches to landscape mode
122 (width > height). For symmetry reasons you can also explicitly
123 add -portrait or -p to indicate the default portrait format.
124 Note that these suffixes are part of the size string and not
125 separate options. Thus, they must directly follow the size
126 specifier without additional blanks. Furthermore, the
127 orientation suffixes can’t be used with dvi, min, and none.
128 Note
130 Option -b, --bbox only affects the bounding box and does
131 not transform the page content. Hence, if you choose a
132 landscape format, the page won’t be rotated.
133 -C, --cache[=dir]
135 To speed up the conversion process of bitmap fonts, dvisvgm saves
136 intermediate conversion information in cache files. By default,
137 these files are stored in $HOME/.dvisvgm/cache. If you prefer a
138 different location, use option --cache to overwrite the default.
139 Furthermore, it is also possible to disable the font caching
140 mechanism completely with option --cache=none. If argument dir is
141 omitted, dvisvgm prints the path of the default cache directory
142 together with further information about the stored fonts.
143 Additionally, outdated and corrupted cache files are removed.
144 -j, --clipjoin
146 This option tells dvisvgm to compute all intersections of clipping
147 paths itself rather than delegating this task to the SVG renderer.
148 The resulting SVG files are more portable because some SVG viewers
149 don’t support intersecting clipping paths which are defined by
150 clipPath elements containing a clip-path attribute.
151 --color
153 Enables colorization of messages printed during the conversion
154 process. The colors can be customized via the environment variable
155 DVISVGM_COLORS. See the Environment section below for further
156 information.
157 --colornames
159 By default, dvisvgm exclusively uses RGB values of the form #RRGGBB
160 to represent colors in the SVG file. According to the SVG standard,
161 it’s also possible to use color names (like black and darkblue) for
162 a limited number of predefined colors. In order to apply these
163 color names rather than their RGB values, call dvisvgm with option
164 --colornames. All colors without an SVG color name will still be
165 represented by RGB values.
166 --comments
168 Adds comments with further information about selected data to the
169 SVG file. Currently, only font elements and font CSS rules related
170 to native fonts are annotated.
171 -E, --eps
173 If this option is given, dvisvgm does not expect a DVI but an EPS
174 input file, and tries to convert it to SVG. In order to do so, a
175 single psfile special command is created and forwarded to the
176 PostScript special handler. This option is only available if
177 dvisvgm was built with PostScript support enabled, and requires
178 Ghostscript to be available. See option --libgs for further
179 information.
180 -e, --exact
182 This option tells dvisvgm to compute the precise bounding box of
183 each character. By default, the values stored in a font’s TFM file
184 are used to determine a glyph’s extent. As these values are
185 intended to implement optimal character placements and are not
186 designed to represent the exact dimensions, they don’t necessarily
187 correspond with the bounds of the visual glyphs. Thus, width and/or
188 height of some glyphs may be larger (or smaller) than the
189 respective TFM values. As a result, this can lead to clipped
190 characters at the bounds of the SVG graphics. With option --exact
191 given, dvisvgm analyzes the actual shape of each character and
192 derives a usually tight bounding box.
193 -m, --fontmap=filenames
195 Loads and evaluates a single font map file or a sequence of font
196 map files. These files are required to resolve font file names and
197 encodings. dvisvgm does not provide its own map files but tries to
198 read available ones coming with dvips or dvipdfm. If option
199 --fontmap is omitted, dvisvgm looks for the default map files
200 ps2pk.map, dvipdfm.map, and psfonts.map (in this order). Otherwise,
201 the files as option arguments are evaluated in the given order.
202 Multiple filenames must be separated by commas without leading
203 and/or trailing whitespace. By default, redefined mappings do not
204 replace previous ones. However, each filename can be preceded by an
205 optional mode specifier (+, -, or =) to change this behavior:
206 +mapfile
208 Only those entries in the given map file that don’t redefine a
209 font mapping are applied, i.e. fonts already mapped keep
210 untouched. That’s also the default mode if no mode specifier is
211 given.
212 -mapfile
214 Ensures that none of the font mappings defined in the given map
215 file are used, i.e. previously defined mappings for the
216 specified fonts are removed.
217 =mapfile
219 All mappings defined in the map file are applied. Previously
220 defined settings for the same fonts are replaced.
221 If the first filename in the filename sequence is preceded by a
223 mode specifier, dvisvgm loads the default font map (see above)
224 and applies the other map files afterwards. Otherwise, none of
225 default map files will be loaded automatically.
226 Examples: --fontmap=myfile1.map,+myfile2.map loads myfile1.map
228 followed by myfile2.map where all redefinitions of myfile2.map
229 are ignored. --fontmap==myfile1.map,-myfile2.map loads the
230 default map file followed by myfile1.map and myfile2.map where
231 all redefinitions of myfile1.map replace previous entries.
232 Afterwards, all definitions for the fonts given in myfile2.map
233 are removed from the font map tree.
234 For further information about the map file formats and the mode
236 specifiers, see the manuals of dvips and dvipdfm.
237 --grad-overlap
239 Tells dvisvgm to create overlapping grid segments when
240 approximating color gradient fills (also see option --grad-segments
241 below). By default, adjacent segments don’t overlap but only touch
242 each other like separate tiles. However, this alignment can lead to
243 visible gaps between the segments because the background color
244 usually influences the color at the boundary of the segments if the
245 SVG renderer uses anti-aliasing to create smooth contours. One way
246 to avoid this and to create seamlessly touching color regions is to
247 enlarge the segments so that they extent into the area of their
248 right and bottom neighbors. Since the latter are drawn on top of
249 the overlapping parts, the visible size of all segments keeps
250 unchanged. Just the former gaps disappear as the background is now
251 completely covered by the correct colors. Currently, dvisvgm
252 computes the overlapping segments separately for each patch of the
253 mesh (a patch mesh may consist of multiple patches of the same
254 type). Therefore, there still might be visible gaps at the seam of
255 two adjacent patches.
256 --grad-segments=number
258 Determines the maximal number of segments per column and row used
259 to approximate gradient color fills. Since SVG 1.1 only supports a
260 small subset of the shading algorithms available in PostScript,
261 dvisvgm approximates some of them by subdividing the area to be
262 filled into smaller, monochromatic segments. Each of these segments
263 gets the average color of the region it covers. Thus, increasing
264 the number of segments leads to smaller monochromatic areas and
265 therefore a better approximation of the actual color gradient. As a
266 drawback, more segments imply bigger SVG files because every
267 segment is represented by a separate path element.
268 Currently, dvisvgm supports free- and lattice-form triangular patch
270 meshes as well as Coons and tensor-product patch meshes. They are
271 approximated by subdividing the area of each patch into a n×n grid
272 of smaller segments. The maximal number of segments per column and
273 row can be changed with option --grad-segments.
274 --grad-simplify=delta
276 If the size of the segments created to approximate gradient color
277 fills falls below the given delta value, dvisvgm reduces their
278 level of detail. For example, Bézier curves are replaced by
279 straight lines, and triangular segments are combined to tetragons.
280 For a small delta, these simplifications are usually not noticeable
281 but reduce the size of the generated SVG files significantly.
282 -h, --help[=mode]
284 Prints a short summary of all available command-line options. The
285 optional mode parameter is an integer value between 0 and 2. It
286 selects the display variant of the help text. Mode 0 lists all
287 options divided into categories with section headers. This is also
288 the default if dvisvgm is called without parameters. Mode 1 lists
289 all options ordered by the short option names, while mode 2 sorts
290 the lines by the long option names.
291 --keep
293 Disables the removal of temporary files as created by Metafont
294 (usually .gf, .tfm, and .log files).
295 --libgs=filename
297 This option is only available if the Ghostscript library is not
298 directly linked to dvisvgm and if PostScript support was not
299 completely disabled during compilation. In this case, dvisvgm tries
300 to load the shared GS library dynamically during runtime. By
301 default, it expects the library’s name to be libgs.so.X (on
302 Unix-like systems, where X is the ABI version of the library) or
303 gsdll32.dll/gsdll64.dll (Windows). Option --libgs can be used to
304 give a different name. Alternatively, it’s also possible to set the
305 GS library name by the environment variable LIBGS. The latter has
306 less precedence than the command-line option, i.e. dvisvgm ignores
307 variable LIBGS if --libgs is given.
308 -L, --linkmark=style
310 Selects the method how to mark hyperlinked areas. The style
311 argument can take one of the values none, box, and line, where box
312 is the default, i.e. a rectangle is drawn around the linked region
313 if option --linkmark is omitted. Style argument line just draws the
314 lower edge of the bounding rectangle, and none tells dvisvgm not to
315 add any visible objects to hyperlinks. The lines and boxes get the
316 current text color selected. In order to apply a different,
317 constant color, a colon followed by a color specifier can be
318 appended to the style string. A color specifier is either a
319 hexadecimal RGB value of the form #RRGGBB, or a dvips color name
320 (http://en.wikibooks.org/wiki/LaTeX/Colors#The_68_standard_colors_known_to_dvips).
321 Moreover, argument style can take a single color specifier to
323 highlight the linked region by a frameless box filled with that
324 color. An optional second color specifier separated by a colon
325 selects the frame color.
326 Examples: box:red or box:#ff0000 draws red boxes around the linked
328 areas. yellow:blue creates yellow filled rectangles with blue
329 frames.
330 -l, --list-specials
332 Prints a list of registered special handlers and exits. Each
333 handler processes a set of special statements belonging to the same
334 category. In most cases, the categories are identified by the
335 prefix of the special statements. It’s usually a leading word
336 separated from the rest of the statement by a colon or a blank,
337 e.g. color or ps.
338 -M, --mag=factor
340 Sets the magnification factor applied in conjunction with Metafont
341 calls prior tracing the glyphs. The larger this value, the better
342 the tracing results. Nevertheless, large magnification values can
343 cause Metafont arithmetic errors due to number overflows. So, use
344 this option with care. The default setting usually produces nice
345 results.
346 --no-merge
348 Puts every single character in a separate text element with
349 corresponding x and y attributes. By default, new text or tspan
350 elements are only created if a string starts at a location that
351 differs from the regular position defined by the characters'
352 advance values.
353 --no-mktexmf
355 Suppresses the generation of missing font files. If dvisvgm can’t
356 find a font file through the kpathsea lookup mechanism, it calls
357 the external tools mktextfm or mktexmf. This option disables these
358 calls.
359 -n, --no-fonts[=variant]
361 If this option is given, dvisvgm doesn’t create SVG font elements
362 but uses paths instead. The resulting SVG files tend to be larger
363 but they are concurrently more compatible with most applications
364 that don’t support SVG fonts yet. The optional argument variant
365 selects the method how to substitute fonts by paths. Variant 0
366 creates path and use elements in order to avoid lengthy duplicates.
367 Variant 1 creates path elements only. Option --no-fonts implies
368 --no-styles.
369 -c, --scale=sx[,sy]
371 Scales the page content horizontally by sx and vertically by sy.
372 This option is equivalent to -TSsx,sy.
373 -S, --no-specials[=names]
375 Disable processing of special commands embedded in the DVI file. If
376 no further parameter is given, all specials are ignored. To disable
377 a selected set of specials, an optional comma-separated list of
378 names can be appended to this option. A name is the unique
379 identifier referencing the intended special handler. Option
380 --list-specials lists all handlers currently available together
381 with their names. All unsupported special statements are silently
382 ignored.
383 --no-styles
385 By default, dvisvgm creates CSS styles and class attributes to
386 reference fonts. This variant is more compact than adding the
387 complete font information to each text element over and over again.
388 However, if you prefer direct font references, the default behavior
389 can be disabled with option --no-styles.
390 -o, --output=pattern
392 Sets the pattern specifying the names of the generated SVG files.
393 Parameter pattern is a string that may contain static character
394 sequences as well as the variables %f, %p, and %P. %f expands to
395 the base name of the DVI file, i.e. the filename without suffix, %p
396 is the current page number, and %P the total number of pages in the
397 DVI file. An optional number (0-9) given directly after the percent
398 sign specifies the minimal number of digits to be written. If a
399 particular value consists of less digits, the number is padded with
400 leading zeros. Example: %3p enforces 3 digits for the current page
401 number (001, 002, etc.). Without an explicit width specifier, %p
402 gets the same number of digits as %P.
403 If you need more control over the numbering, you can use arithmetic
405 expressions as part of a pattern. The syntax is %(expr) where expr
406 may contain additions, subtractions, multiplications, and integer
407 divisions with common precedence. The variables p and P contain the
408 current page number and the total number of pages, respectively.
409 For example, --output="%f-%(p-1)" creates filenames where the
410 numbering starts with 0 rather than 1.
411 The default pattern is %f-%p.svg if the DVI file consists of more
413 than one page, and %f.svg otherwise. That means, a DVI file foo.dvi
414 is converted to foo.svg if foo.dvi is a single-page document.
415 Otherwise, multiple SVG files foo-01.svg, foo-02.svg, etc. are
416 produced. In Windows environments, the percent sign indicates
417 dereferenced environment variables, and must therefore be protected
418 by a second percent sign, e.g. --output=%%f-%%p.
419 -p, --page=ranges
421 This option selects the pages to be processed. Parameter ranges
422 consists of a comma-separated list of single page numbers and/or
423 page ranges. A page range is a pair of numbers separated by a
424 hyphen, e.g. 5-12. Thus, a page sequence might look like this:
425 2-4,6,9-12,15. It doesn’t matter if a page is given more than once
426 or if page ranges overlap. dvisvgm always extracts the page numbers
427 in ascending order and converts them only once. In order to stay
428 compatible with previous versions, the default page sequence is 1.
429 dvisvgm therefore converts only the first page and not the whole
430 document if option --page is omitted. Usually, page ranges consist
431 of two numbers denoting the first and last page to be converted. If
432 the conversion should start at page 1, or if it should continue up
433 to the last DVI page, the first or second range number can be
434 omitted, respectively. Example: --page=-10 converts all pages up to
435 page 10, --page=10- converts all pages starting with page 10.
436 Please consider that the page values don’t refer to the page
437 numbers printed on the corresponding page. Instead, the physical
438 page count is expected, where the first page always gets number 1.
439 -d, --precision=digits
441 Specifies the maximal number of decimal places applied to
442 floating-point attribute values. All attribute values written to
443 the generated SVG file(s) are rounded accordingly. The parameter
444 digits allows integer values from 0 to 6, where 0 enables the
445 automatic selection of significant decimal places. This is also the
446 default value if dvisvgm is called without option --precision.
447 -P, --progress[=delay]
449 Enables a simple progress indicator shown when time-consuming
450 operations like PostScript specials are processed. The indicator
451 doesn’t appear before the given delay (in seconds) has elapsed. The
452 default delay value is 0.5 seconds.
453 -r, --rotate=angle
455 Rotates the page content clockwise by angle degrees around the page
456 center. This option is equivalent to -TRangle.
457 -R, --relative
459 SVG allows to define graphics paths by a sequence of absolute
460 and/or relative path commands, i.e. each command expects either
461 absolute coordinates or coordinates relative to the current drawing
462 position. By default, dvisvgm creates paths made up of absolute
463 commands. If option --relative is given, relative commands are
464 created instead. This slightly reduces the size of the SVG files in
465 most cases.
466 -s, --stdout
468 Don’t write the SVG output to a file but redirect it to stdout.
469 -T, --transform=commands
471 Applies a sequence of transformations to the SVG content. Each
472 transformation is described by a command beginning with a capital
473 letter followed by a list of comma-separated parameters. Following
474 transformation commands are supported:
475 T tx[,ty]
477 Translates (moves/shifts) the page in direction of vector
478 (tx,ty). If ty is omitted, ty=0 is assumed. The expected unit
479 length of tx and ty are TeX points (1pt = 1/72.27in). However,
480 there are several constants defined to simplify the unit
481 conversion (see below).
482 S sx[,sy]
484 Scales the page horizontally by sx and vertically by sy. If sy
485 is omitted, sy=sx is assumed.
486 R angle[,x,y]
488 Rotates the page clockwise by angle degrees around point (x,y).
489 If the optional arguments x and y are omitted, the page will be
490 rotated around its center depending on the chosen page format.
491 When option -bnone is given, the rotation center is origin
492 (0,0).
493 KX angle
495 Skews the page along the x-axis by angle degrees. Argument
496 angle can take any value except 90+180k, where k is an integer.
497 KY angle
499 Skews the page along the y-axis by angle degrees. Argument
500 angle can take any value except 90+180k, where k is an integer.
501 FH [y]
503 Mirrors (flips) the page at the horizontal line through point
504 (0,y). Omitting the optional argument leads to y=h/2, where h
505 denotes the page height (see pre-defined constants below).
506 FV [x]
508 Mirrors (flips) the page at the vertical line through point
509 (x,0). Omitting the optional argument leads to x=w/2, where w
510 denotes the page width (see pre-defined constants below).
511 M m1,...,m6
513 Applies a transformation described by the 3×3 matrix
514 ((m1,m2,m3),(m4,m5,m6),(0,0,1)), where the inner triples denote
515 the rows.
516 Note
518 All transformation commands of option -T, --transform are
519 applied in the order of their appearance. Multiple commands
520 can optionally be separated by spaces. In this case the
521 whole transformation string has to be enclosed in double
522 quotes to keep them together. All parameters are
523 expressions of floating point type. You can either give
524 plain numbers or arithmetic terms combined by the operators
525 + (addition), - (subtraction), * (multiplication), /
526 (division) or % (modulo) with common associativity and
527 precedence rules. Parentheses may be used as well.
528 Additionally, some pre-defined constants are provided:
530 ux horizontal position of
532 upper left page corner in
533 TeX point units
534 uy vertical position of upper
535 left page corner in TeX
536 point units
537 h page height in TeX point
538 units (0 in case of
539 -bnone)
540 w page width in TeX point
541 units (0 in case of
542 -bnone)
543 Furthermore, you can use the length constants pt, mm, cm
545 and in, e.g. 2cm or 1.6in. Thus, option -TT1in,0R45 moves
546 the page content 1 inch to the right and rotates it by 45
547 degrees around the page center afterwards.
548 For single transformations, there are also the short-hand
550 options -c, -t and -r available. In contrast to the
551 --transform* commands, the order of these options is not
552 significant, so that it’s not possible to describe
553 transformation sequences with them.
554 -t, --translate=tx[,ty]
556 Translates (moves) the page content in direction of vector (tx,ty).
557 This option is equivalent to -TTtx,ty.
558 -v, --verbosity=level
560 Controls the type of messages printed during a dvisvgm run:
561 0 no message output at all
563 1 error messages only
564 2 warning messages only
565 4 informational messages
566 only
567 Note
570 By adding these values you can combine the categories. The
571 default level is 7, i.e. all messages are printed.
572 -V, --version[=extended]
574 Prints the version of dvisvgm and exits. If the optional argument
575 is set to yes, the version numbers of the linked libraries are
576 printed as well.
577 -z, --zip[=level]
579 Creates a compressed SVG file with suffix .svgz. The optional
580 argument specifies the compression level. Valid values are in the
581 range of 1 to 9 (default value is 9). Larger values cause better
582 compression results but may take slightly more computation time.
583 Caution
585 This option cannot be combined with -s, --stdout.
586 -Z, --zoom[=factor]
588 Multiplies the width and height attributes of the SVG root element
589 by argument factor while the coordinate system of the graphic
590 content is retained. As a result, most SVG viewers zoom the
591 graphics accordingly. If a negative zoom factor is given, the width
592 and height attributes are omitted.
593
595 dvisvgm supports several sets of special commands that can be used to
596 enrich DVI files with additional features, like color, graphics, and
597 hyperlinks. The evaluation of special commands is delegated to
598 dedicated handlers provided by dvisvgm. Each handler is responsible for
599 all special statements of the same command set, i.e. commands beginning
600 with the same prefix. To get a list of the actually provided special
601 handlers, use option --list-specials (see above). This section gives an
602 overview of the special commands currently supported.
603 bgcolor
605 Special statement for changing the background/page color. Since SVG
606 1.1 doesn’t support background colors, dvisvgm inserts a rectangle
607 of the chosen color into the generated SVG document. This rectangle
608 always gets the same size as the selected or computed bounding box.
609 This background color command is part of the color special set but
610 is handled separately in order to let the user turn it off. For an
611 overview of the command syntax, see the documentation of dvips, for
612 instance.
613 color
615 Statements of this command set provide instructions to change the
616 text/paint color. For an overview of the exact syntax, see the
617 documentation of dvips, for instance.
618 dvisvgm
620 dvisvgm offers its own small set of specials. The following list
621 gives a brief overview.
622 dvisvgm:raw text
624 Adds an arbitrary sequence of characters to the page section of
625 the SVG document. dvisvgm does not perform any validation here,
626 thus the user has to ensure that the resulting SVG is still
627 valid. Parameter text may contain the expressions {?x}, {?y},
628 and {?color} that expand to the current x or y coordinate and
629 the current color, respectively. Furthermore, {?nl} expands to
630 a newline character.
631 dvisvgm:rawdef text
633 This command is similar to dvisvgm:raw, but puts the raw text
634 into the <defs> section of the SVG document currently being
635 generated.
636 dvisvgm:rawset name ... dvisvgm:endrawset
638 This pair of specials marks the begin and end of a definition
639 of a named raw SVG fragment. All dvisvgm:raw and dvisvgm:rawdef
640 specials enclosed by dvisvgm:rawset and dvisvgm:endrawset are
641 not evaluated immediately but jointly stored under the given
642 name for later use. Once defined, the named fragment can be
643 referenced throughout the DVI file by dvisvgm:rawput (see
644 below). The two commands dvisvgm:rawset and dvisvgm:endrawset
645 must not be nested, i.e. each call of dvisvgm:rawset has to be
646 followed by a corresponding call of dvisvgm:endrawset before
647 another dvisvgm:rawset may occur. Also, the identifier name
648 must be unique throughout the DVI file. Using dvisvgm:rawset
649 multiple times together with the same name leads to warning
650 messages.
651 dvisvgm:rawput name
653 Inserts raw SVG fragments previously stored under the given
654 name. dvisvgm distinguishes between fragments that were
655 specified with dvisvgm:raw or dvisvgm:rawdef, and handles them
656 differently: It inserts all dvisvgm:raw parts every time
657 dvisvgm:rawput is called, whereas the dvisvgm:rawdef portions
658 go to the <defs> section of the current SVG document only once.
659 dvisvgm:img width height file
661 Creates an image element at the current graphic position
662 referencing the given file. JPEG, PNG, and SVG images can be
663 used here. However, dvisvgm does not check the file format or
664 the file name suffix. The lengths width and height must be
665 given as plain floating point numbers in TeX point units (1in =
666 72.27pt).
667 dvisvgm:bbox n[ew] name
669 Defines or resets a local bounding box called name. The name
670 may consist of letters and digits. While processing a DVI page,
671 dvisvgm continuously updates the (global) bounding box of the
672 current page in order to determine the minimal rectangle
673 containing all visible page components (characters, images,
674 drawing elements etc.) Additionally to the global bounding box,
675 the user can request an arbitrary number of named local
676 bounding boxes. Once defined, these boxes are updated together
677 with the global bounding box starting with the first character
678 that follows the definition. Thus, the local boxes can be used
679 to compute the extent of parts of the page. This is useful for
680 scenarios where the generated SVG file is post-processed. In
681 conjunction with special dvisvgm:raw, the macro {?bbox name}
682 expands to the four values x, y, w, and h (separated by spaces)
683 specifying the coordinates of the upper left corner, width, and
684 height of the local box name. If box name wasn’t previously
685 defined, all four values equal to zero.
686 dvisvgm:bbox width height [depth]
688 Updates the bounding box of the current page by embedding a
689 virtual rectangle (x, y, width, height) where the lower left
690 corner is located at the current DVI drawing position (x,y). If
691 the optional parameter depth is specified, dvisvgm embeds a
692 second rectangle (x, y, width, -depth). The lengths width,
693 height and depth must be given as plain floating point numbers
694 in TeX point units (1in = 72.27pt). Depending on size and
695 position of the virtual rectangle, this command either enlarges
696 the overall bounding box or leaves it as is. It’s not possible
697 to reduce its extent. This special should be used in
698 conjunction with dvisvgm:raw in order to update the viewport of
699 the page properly.
700 dvisvgm:bbox a[bs] x1 y1 x2 y2
702 This variant of the bbox special updates the bounding box by
703 embedding a virtual rectangle (x1,y1,x2,y2). The points (x1,y1)
704 and (x2,y2) denote two diagonal corners of the rectangle given
705 in TeX point units.
706 dvisvgm:bbox f[ix] x1 y1 x2 y2
708 This variant of the bbox special assigns an absolute (final)
709 bounding box to the resulting SVG. After executing this
710 command, dvisvgm doesn’t further alter the bounding box
711 coordinates, except this special is called again later. The
712 points (x1,y1) and (x2,y2) denote two diagonal corners of the
713 rectangle given in TeX point units.
714 The following TeX snippet adds two raw SVG elements to the
716 output and updates the bounding box accordingly:
717 \special{dvisvgm:raw <circle cx='{?x}' cy='{?y}' r='10' stroke='black' fill='red'/>}
719 \special{dvisvgm:bbox 20 10 10}
720 \special{dvisvgm:raw <path d='M50 200 L10 250 H100 Z' stroke='black' fill='blue'/>}
722 \special{dvisvgm:bbox abs 10 200 100 250}
723 em
725 These specials were introduced with the emTeX distribution by
726 Eberhard Mattes. They provide line drawing statements, instructions
727 for embedding MSP, PCX, and BMP image files, as well as two PCL
728 commands. dvisvgm supports only the line drawing statements and
729 ignores all other em specials silently. A description of the
730 command syntax can be found in the DVI driver documentation coming
731 with emTeX (http://www.ctan.org/pkg/emtex).
732 html
734 The hyperref specification defines several variants on how to mark
735 hyperlinked areas in a DVI file. dvisvgm supports the plain
736 HyperTeX special constructs as created with hyperref package option
737 hypertex. By default, all linked areas of the document are marked
738 by a rectangle. Option --linkmark allows to change this behavior.
739 See above for further details. Information on syntax and semantics
740 of the HyperTeX specials can be found in the hyperref manual
741 (http://www.ctan.org/pkg/hyperref).
742 pdf
744 pdfTeX and dvipdfmx introduced several special commands related to
745 the generation of PDF files. Currently, only two of them,
746 pdf:mapfile and pdf:mapline are supported by dvisvgm. These
747 specials allow modifying the font map tree during the processing of
748 DVI files. They are used by CTeX, for example. dvisvgm supports
749 both, the dvips and dvipdfm font map format. For further
750 information on the command syntax and semantics, see the
751 documentation of \pdfmapfile in the pdfTeX user manual
752 (http://www.ctan.org/pkg/pdftex).
753 ps
755 The famous DVI driver dvips introduced its own set of specials in
756 order to embed PostScript code into DVI files, which greatly
757 improves the capabilities of DVI documents. One aim of dvisvgm is
758 to completely evaluate all PostScript snippets and to convert as
759 many of them as possible to SVG. In contrast to dvips, dvisvgm uses
760 floating point arithmetics to compute the precise position of each
761 graphic element, i.e. it doesn’t round the coordinates. Therefore,
762 the relative locations of the graphic elements may slightly differ
763 from those computed by dvips.
764 Since PostScript is a rather complex language, dvisvgm does not try
766 to implement its own PostScript interpreter but relies on
767 Ghostscript (http://ghostscript.com) instead. If the Ghostscript
768 library was not linked to the dvisvgm binary, it is looked up and
769 loaded dynamically during runtime. In this case, dvisvgm looks for
770 libgs.so.X on Unix-like systems (supported ABI versions: 7,8,9),
771 and for gsdll32.dll or gsdll64.dll on Windows. You can override the
772 default file names with environment variable LIBGS or the
773 command-line option --libgs. The library must be reachable through
774 the ld search path (*nix) or the PATH environment variable
775 (Windows). Alternatively, the absolute file path can be specified.
776 If the library cannot be found, dvisvgm disables the processing of
777 PostScript specials and prints a warning message. Use option
778 --list-specials to check whether PostScript support is available,
779 i.e. entry ps is present.
780 The PostScript handler also recognizes and evaluates bounding box
782 data generated by the preview package
783 (http://www.ctan.org/pkg/preview) with option tightpage. If such
784 data is present in the DVI file and if dvisvgm is called with
785 option --bbox=preview, dvisvgm adapts the bounding box of the
786 generated SVG file accordingly, and prints a message showing the
787 width, height, and depth of the box in TeX point units. Especially,
788 the depth value can be used to vertically align the SVG graphics
789 with the baseline of surrounding text in HTML or XSL-FO documents,
790 for example. If you call dvisvgm with option --bbox=min (the
791 default), the tight bounding box computed while processing the page
792 is applied and not the one provided by the preview package. Thus,
793 the height, depth and width values written to the console are
794 adapted accordingly.
795 tpic
797 The TPIC special set defines instructions for drawing simple
798 geometric objects. Some LaTeX packages, like eepic and tplot, use
799 these specials to describe graphics.
800
802 dvisvgm file
803 Converts the first page of file.dvi to file.svg.
805 dvisvgm -z file
807 Converts the first page of file.dvi to file.svgz with default
809 compression level 9.
810 dvisvgm -p5 -z3 -ba4-l -onewfile file
812 Converts the fifth page of file.dvi to newfile.svgz with compression
814 level 3. The bounding box is set to DIN/ISO A4 in landscape format.
815 dvisvgm --transform="R20,w/3,2h/5 T1cm,1cm S2,3" file
817 Converts the first page of file.dvi to file.svg where three
819 transformations are applied.
820
822 dvisvgm uses the kpathsea library for locating the files that it opens.
823 Hence, the environment variables described in the library’s
824 documentation influence the converter.
825 If dvisvgm was linked without the Ghostscript library, and if
827 PostScript support has not been disabled, the shared Ghostscript
828 library is looked up during runtime via dlopen(). The environment
829 variable LIBGS can be used to specify path and file name of the
830 library.
831 The pre-compiled Windows versions of dvisvgm require a working
833 installation of MiKTeX 2.9 or above. dvisvgm does not work together
834 with the portable edition of MiKTeX because it relies on MiKTeX’s COM
835 interface that is only accessible in a local installation. To enable
836 the evaluation of PostScript specials, the original Ghostscript DLL
837 gsdll32.dll must be present and reachable through the search path.
838 64-bit Windows builds require the 64-bit Ghostscript DLL gsdll64.dll.
839 Both DLLs come with the corresponding Ghostscript installers available
840 from http://ghostscript.com.
841 The environment variable DVISVGM_COLORS specifies the colors used to
843 highlight various parts of dvisvgm’s message output. It is only
844 evaluated if option --color is given. The value of DVISVGM_COLORS is a
845 list of colon-separated entries of the form gg=BF, where gg denotes one
846 of the color group indicators listed below, and BF are two hexadecimal
847 digits specifying the background (first digit) and foreground/text
848 color (second digit). The color values are defined as follows: 0=black,
849 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=gray, 8=bright
850 red, 9=bright green, A=bright yellow, B=bright blue, C=bright magenta,
851 D=bright cyan, E=bright gray, F=white. Depending on the terminal, the
852 colors may differ. Rather than changing both the text and background
853 color, it’s also possible to change only one of them: An asterisk (*)
854 in place of a hexadecimal digit indicates the default text or
855 background color of the terminal.
856 All malformed entries in the list are silently ignored.
858 er error messages
861 wn warning messages
863 pn messages about page
865 numbers
866 ps page size messages
868 fw information about the
871 files written
872 sm state messages
874 tr messages of the glyph
876 tracer
877 pi progress indicator
879 Example: er=01:pi=*5 sets the colors of error messages (er) to red (1)
882 on black (0), and those of progress indicators (pi) to cyan (5) on
883 default background (*).
884
886 The location of the following files is determined by the kpathsea
887 library. To check the actual kpathsea configuration you can use the
888 kpsewhich utility.
889 *.enc Font encoding files
892 *.fgd Font glyph data files
894 (cache files created by
895 dvisvgm)
896 *.map Font map files
898 *.mf Metafont input files
900 *.pfb PostScript Type 1 font
902 files
903 *.pro PostScript header/prologue
905 files
906 *.tfm TeX font metric files
908 *.ttf TrueType font files
910 *.vf Virtual font files
912
915 tex(1), mf(1), mktexmf(1), grodvi(1), potrace(1), and the kpathsea
916 library info documentation.
917
919 Project home page
920 http://dvisvgm.bplaced.net
921 Code repository
923 https://github.com/mgieseki/dvisvgm
924
926 Please report bugs using the bug tracker at GitHub
927 (https://github.com/mgieseki/dvisvgm/issues).
928
930 Written by Martin Gieseking <martin.gieseking@uos.de>
931
933 Copyright © 2005-2016 Martin Gieseking. Free use of this software is
934 granted under the terms of the GNU General Public License (GPL) version
935 3 or, (at your option) any later version.
936dvisvgm 1.15.1 04/19/2016 DVISVGM(1)