diff options
Diffstat (limited to 'Master/texmf/doc/man/man1/dvisvgm.1')
-rw-r--r-- | Master/texmf/doc/man/man1/dvisvgm.1 | 139 |
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\&. |