summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/man/man1/dvisvgm.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf/doc/man/man1/dvisvgm.1')
-rw-r--r--Master/texmf/doc/man/man1/dvisvgm.1139
1 files changed, 113 insertions, 26 deletions
diff --git a/Master/texmf/doc/man/man1/dvisvgm.1 b/Master/texmf/doc/man/man1/dvisvgm.1
index 6f51f38e1fa..13970ac2de4 100644
--- a/Master/texmf/doc/man/man1/dvisvgm.1
+++ b/Master/texmf/doc/man/man1/dvisvgm.1
@@ -1,13 +1,13 @@
'\" t
.\" Title: dvisvgm
.\" Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.74.3 <http://docbook.sf.net/>
-.\" Date: 11/09/2009
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\" Date: 08/06/2010
.\" Manual: dvisvgm Manual
-.\" Source: dvisvgm 0.8.7
+.\" Source: dvisvgm 1.0.3
.\" Language: English
.\"
-.TH "DVISVGM" "1" "11/09/2009" "dvisvgm 0\&.8\&.7" "dvisvgm Manual"
+.TH "DVISVGM" "1" "08/06/2010" "dvisvgm 1\&.0\&.3" "dvisvgm Manual"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
@@ -25,19 +25,27 @@ dvisvgm \- converts DVI files to the XML\-based SVG format
\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\&.
+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, \fBdvisvgm\fR 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
-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\&.
+\fBdvisvgm\fR 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
-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\&.
+As 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 required 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\&.
+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 \fBdvisvgm\fR 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
+\fB\-a, \-\-trace\-all\fR=[\fIretrace\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\&.
+\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 that are 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
.\}
@@ -69,6 +77,9 @@ takes either one of the format specifiers listed below or a sequence of four com
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
@@ -157,7 +168,8 @@ only affects the bounding box and does not transform the page content\&. Hence i
Scales page content horizontally by
\fIsx\fR
and vertically by
-\fIsy\fR\&. This option is equivalent to *\-TS*\fIsx\fR,\fIsy\fR\&.
+\fIsy\fR\&. This option is equivalent to
+\fB\-TS\fR\fIsx\fR,\fIsy\fR\&.
.RE
.PP
\fB\-C, \-\-cache\fR[=\fIdir\fR]
@@ -172,6 +184,30 @@ to overwrite the default\&. Furthermore, it is also possible to disable the font
is omitted, dvisvgm prints the path of the default cache directory and some information about the stored fonts\&.
.RE
.PP
+\fB\-\-color\fR
+.RS 4
+Enables colorization of messages printed during the conversion process\&.
+.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 the 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, the 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\-h, \-\-help\fR
+.RS 4
+Prints a short summary of all available command\-line options\&.
+.RE
+.PP
+\fB\-\-libgs=filename\fR
+.RS 4
+This option is only available if the Ghostscript library is not directly linked to dvisvgm and PostScript support was not completely disabled\&. 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 (Windows)\&. Option
+\fB\-\-libgs\fR
+can be used to give a different name\&. Alternatively, the GS library name can also be set by the environment variable
+\fBLIBGS\fR\&. The latter has a 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\&. 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\&.
@@ -180,6 +216,11 @@ or
\fIps\fR\&.
.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\-m, \-\-map\-file\fR=\fIfile\fR
.RS 4
Sets the map file that is used to look up font names and encodings\&.
@@ -245,23 +286,51 @@ Suppresses the generation of missing font files\&. If
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
+\fB\-o, \-\-output\fR=\fIpattern\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\&.
+Sets the name pattern of the output file\&. The 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\&. By default, the 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 is used to get the value of 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\&.
+\fBdvisvgm\fR
+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 not given\&. 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\-P, \-\-progress\fR[=\fIskip\fR]
+\fB\-P, \-\-progress\fR[=\fIdelay\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\&.
+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)\&. The default delay value is 0\&.5 seconds\&.
.RE
.PP
\fB\-r, \-\-rotate\fR=\fIangle\fR
@@ -507,6 +576,22 @@ and
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,
@@ -568,7 +653,7 @@ introduced its own set of specials in order to embed PostScript code into DVI fi
\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
+does not try to implement its own PostScript interpreter but uses Ghostscript instead\&. If the Ghostscript library was not linked while building dvisvgm, it is looked up and dynamically loaded during runtime\&. In this case, dvisvgm looks for libgs\&.so on Unix\-like systems, and gsdll32\&.dll on Windows\&. You can override these default file names with the environment variable LIBGS\&. 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 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
@@ -632,6 +717,8 @@ Converts first page of \fIfile\&.dvi\fR to \fIfile\&.svg\fR where three transfor
.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
+If dvisvgm was linked without the Ghostscript library and PostScript support has not been disabled, the shared Ghostscript library is looked up during runtime\&. The environment variable LIBGS can be used to specify the file name of library\&.
+.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
@@ -733,4 +820,4 @@ http://sourceforge\&.net/projects/dvisvgm
Written by Martin Gieseking <martin\&.gieseking@uos\&.de>
.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\&.
+Copyright \(co 2005\-2010 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\&.