summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/dvisvgm.1
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-03-04 16:00:29 +0000
committerKarl Berry <karl@freefriends.org>2022-03-04 16:00:29 +0000
commit5027858830867ff20c7eca53eed6f8b798c5ad9c (patch)
tree842f07fed6d88920a1bcdc035157bb20e17e7904 /Master/texmf-dist/doc/man/man1/dvisvgm.1
parentf23f3a09677e44ad094dcf2aa3ac0c3dc3893238 (diff)
2022 doc (+sync) update
git-svn-id: svn://tug.org/texlive/trunk@62387 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/dvisvgm.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/dvisvgm.156
1 files changed, 35 insertions, 21 deletions
diff --git a/Master/texmf-dist/doc/man/man1/dvisvgm.1 b/Master/texmf-dist/doc/man/man1/dvisvgm.1
index ba8b102cc9c..8d9274bfd7c 100644
--- a/Master/texmf-dist/doc/man/man1/dvisvgm.1
+++ b/Master/texmf-dist/doc/man/man1/dvisvgm.1
@@ -2,12 +2,12 @@
.\" Title: dvisvgm
.\" Author: Martin Gieseking <martin.gieseking@uos.de>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.\" Date: 2021-01-03
+.\" Date: 2022-01-18
.\" Manual: dvisvgm Manual
-.\" Source: dvisvgm 2.11.1
+.\" Source: dvisvgm 2.13.2
.\" Language: English
.\"
-.TH "DVISVGM" "1" "2021\-01\-03" "dvisvgm 2\&.11\&.1" "dvisvgm Manual"
+.TH "DVISVGM" "1" "2022\-01\-18" "dvisvgm 2\&.13\&.2" "dvisvgm Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -31,11 +31,11 @@
dvisvgm \- converts DVI and EPS files to the XML\-based SVG format
.SH "SYNOPSIS"
.sp
-\fBdvisvgm\fR [ \fIoptions\fR ] \fIfile\fR [\&.dvi]
+\fBdvisvgm\fR [\fIoptions\fR] \fIfile\fR[\&.dvi]
.sp
-\fBdvisvgm\fR \-\-eps [ \fIoptions\fR ] \fIfile\fR [\&.eps]
+\fBdvisvgm\fR \-\-eps [\fIoptions\fR] \fIfile1\fR[\&.eps] \fIfile2\fR[\&.eps] \&...
.sp
-\fBdvisvgm\fR \-\-pdf [ \fIoptions\fR ] \fIfile\fR [\&.pdf]
+\fBdvisvgm\fR \-\-pdf [\fIoptions\fR] \fIfile\fR[\&.pdf]
.SH "DESCRIPTION"
.sp
The command\-line utility \fBdvisvgm\fR converts DVI files, as generated by TeX/LaTeX, to the XML\-based scalable vector graphics format SVG\&. It supports the classic DVI version 2 as well as version 3 (created by pTeX in vertical mode), and the XeTeX versions 5 to 7 which are also known as XDV\&. Besides the basic DVI commands, dvisvgm also evaluates many so\-called \fIspecials\fR which heavily extend the capabilities of the plain DVI format\&. For a more detailed overview, see section \fBSupported Specials\fR below\&.
@@ -46,7 +46,7 @@ SVG is a vector\-based graphics format and therefore dvisvgm tries to convert th
.sp
However, TeX\(cqs main source for font descriptions is Metafont, which produces bitmap output (GF files)\&. That\(cqs why not all obtainable TeX fonts are available in a scalable format\&. In these cases, dvisvgm tries to vectorize Metafont\(cqs output by tracing the glyph bitmaps\&. The results are not as perfect as most (manually optimized) PFB or OTF counterparts, but are nonetheless really nice in most cases\&.
.sp
-When running dvisvgm without option \fB\-\-no\-fonts\fR, it creates \fIfont\fR elements (\fB<font>\fR\&...\fB</font>\fR) to embed the font data into the SVG files\&. Unfortunately, only few SVG renderers support these elements yet\&. Most web browsers and vector graphics applications don\(cqt evaluate them properly so that the text components of the resulting graphics might look strange\&. In order to create more compatible SVG files, command\-line option \fB\-\-no\-fonts\fR can be given to replace the font elements by plain graphics paths\&. Most web browsers (but only few external SVG renderers) also suppport WOFF and WOFF2 fonts that can be used instead of the default SVG fonts\&. Option \fB\-\-font\-format\fR offers the functionality to change the format applied to the fonts being embedded\&. This, however, only works when converting DVI files\&. Text present in PDF and PostScript files is always converted to path elements\&.
+When running dvisvgm without option \fB\-\-no\-fonts\fR, it creates \fIfont\fR elements (\fB<font>\fR\&...\fB</font>\fR) to embed the font data into the SVG files\&. Unfortunately, only few SVG renderers support these elements yet\&. Most web browsers and vector graphics applications don\(cqt evaluate them properly so that the text components of the resulting graphics might look strange\&. In order to create more compatible SVG files, command\-line option \fB\-\-no\-fonts\fR can be given to replace the font elements by plain graphics paths\&. Most web browsers (but only few external SVG renderers) also support WOFF and WOFF2 fonts that can be used instead of the default SVG fonts\&. Option \fB\-\-font\-format\fR offers the functionality to change the format applied to the fonts being embedded\&. This, however, only works when converting DVI files\&. Text present in PDF and PostScript files is always converted to path elements\&.
.SH "OPTIONS"
.sp
dvisvgm provides a POSIX\-compliant command\-line interface with short and long option names\&. They may be given before and/or after the name of the file to be converted\&. Also, the order of specifying the options is not significant, i\&.e\&. you can add them in any order without changing dvisvgm\(cqs behavior\&. Certain options accept or require additional parameters which are directly appended to or separated by whitespace from a short option (e\&.g\&. \fB\-v0\fR or \fB\-v 0\fR)\&. Long options require an additional equals sign (\fB=\fR) between option name and argument but without any surrounding whitespace (e\&.g\&. \fB\-\-verbosity=0\fR)\&. Multiple short options that don\(cqt expect a further parameter can be combined after a single dash (e\&.g\&. \fB\-ejs\fR rather than \fB\-e \-j \-s\fR)\&.
@@ -301,7 +301,7 @@ Adds comments with further information about selected data to the SVG file\&. Cu
.PP
\fB\-E, \-\-eps\fR
.RS 4
-If this option is given, dvisvgm does not expect a DVI but an EPS input file, and tries to convert it to SVG\&. In order to do so, a single
+If this option is given, dvisvgm does not expect a DVI but a single or multiple EPS input files, and tries to convert them to SVG\&. In order to do so, a single
\fIpsfile\fR
special command is created and forwarded to the PostScript special handler\&. This option is only available if dvisvgm was built with PostScript support enabled, and requires Ghostscript to be available\&. See option
\fB\-\-libgs\fR
@@ -506,10 +506,10 @@ creates yellow filled rectangles with blue frames\&.
.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\&. In most cases, the categories are identified by the prefix of the special statements\&. It\(cqs usually a leading string followed by a colon or a blank, e\&.g\&.
+Prints a list of registered special handlers and exits\&. Each handler processes a set of special statements belonging to the same category\&. In most cases, these categories are identified by the prefix of the special statements which is usually a leading string followed by a colon or a blank, e\&.g\&.
\fIcolor\fR
or
-\fIps\fR\&. The listed handler names, however, don\(cqt need to match these prefixes, e\&.g\&. if there is no common prefix or if functionality is split into separate handlers in order to allow to disable them separately with option
+\fIps\fR\&. The listed handler names, however, don\(cqt need to match these prefixes, e\&.g\&. if there is no common prefix or if functionality is split into separate handlers in order to allow them to be disabled separately using option
\fB\-\-no\-specials\fR\&. All special statements not covered by one of the special handlers are silently ignored\&.
.RE
.PP
@@ -662,21 +662,30 @@ expression, it\(cqs assigned to the attribute\&. Otherwise, the matrix expressio
.PP
\fB\-o, \-\-output\fR=\fIpattern\fR
.RS 4
-Sets the pattern specifying the names of the generated SVG files\&. Parameter
+Sets the pattern that determines the names of the generated SVG files\&. The required parameter
\fIpattern\fR
-is a string that may contain static character sequences as well as the variables
+may consist of an arbitrary sequence of characters which make up the filenames\&. With the exception of the following mentioned variables and expressions, all characters are treated as static parts of the filenames and are therefore identical for all pages processed during a run of dvisvgm\&. The strings
\fB%f\fR,
\fB%p\fR,
\fB%P\fR,
+\fB%n\fR,
+\fB%N\fR,
\fB%hd\fR,
\fB%ho\fR, and
-\fB%hc\fR\&.
+\fB%hc\fR
+are variables that can be used as part of the pattern\&.
\fB%f\fR
expands to the base name of the DVI file, i\&.e\&. the filename without suffix,
\fB%p\fR
is the current page number, and
\fB%P\fR
-the total number of pages in the DVI file\&. An optional number (0\-9) given directly after the percent sign specifies the minimal number of digits to be written\&. If a particular value consists of less digits, the number is padded with leading zeros\&. Example:
+the total number of pages in the DVI file\&. The variables
+\fB%n\fR
+and
+\fB%N\fR
+expand to the number of the current file being converted (starting at 1) and the total number of files given, respectively\&.
+.sp
+An optional number (0\-9) specified directly after the percent sign of a variable holding a numeric value denotes the minimal number of digits to be created\&. If a particular value consists of less digits, the number is padded with leading zeros\&. Example:
\fB%3p\fR
enforces 3 digits for the current page number (001, 002, etc\&.)\&. Without an explicit width specifier,
\fB%p\fR
@@ -703,7 +712,7 @@ and
\fB%hc\fR
are only set if option
\fB\-\-page\-hashes\fR
-is present\&. Otherwise, it\(cqs empty\&. For further information, see the description of option
+is present\&. Otherwise, they are empty\&. For further information, see the description of option
\fB\-\-page\-hashes\fR
below\&.
.sp
@@ -839,7 +848,7 @@ degrees around the page center\&. This option is equivalent to
.PP
\fB\-R, \-\-relative\fR
.RS 4
-SVG allows to define graphics paths by a sequence of absolute and/or relative path commands, i\&.e\&. each command expects either absolute coordinates or coordinates relative to the current drawing position\&. By default, dvisvgm creates paths made up of absolute commands\&. If option
+SVG allows you to define graphics paths by a sequence of absolute and/or relative path commands, i\&.e\&. each command expects either absolute coordinates or coordinates relative to the current drawing position\&. By default, dvisvgm creates paths made up of absolute commands\&. If option
\fB\-\-relative\fR
is given, relative commands are created instead\&. This slightly reduces the size of the SVG files in most cases\&.
.RE
@@ -867,7 +876,7 @@ In some cases, dvisvgm needs to create temporary files to work properly\&. These
\fB/tmp\fR
on Linux systems\&. Option
\fB\-\-tmpdir\fR
-allows to specify a different location if necessary for some reason\&. Please note that dvisvgm does not create this folder, so you must ensure that it actually exists before running dvisvgm\&.
+can be used to specify a different location\&. Please note that dvisvgm does not create this folder if it doesn\(cqt exist\&. Therefore, you must ensure that it\(cqs actually present before running dvisvgm\&.
.sp
If the optional parameter
\fIpath\fR
@@ -1162,11 +1171,16 @@ attributes are omitted\&.
.RE
.SH "SUPPORTED SPECIALS"
.sp
-dvisvgm supports several sets of \fIspecial commands\fR that can be used to enrich DVI files with additional features, like color, graphics, and hyperlinks\&. The evaluation of special commands is delegated to dedicated handlers provided by dvisvgm\&. Each handler is responsible for all special statements of the same command set, i\&.e\&. commands beginning with the same prefix\&. To get a list of the actually provided special handlers, use option \fB\-\-list\-specials\fR (see above)\&. This section gives an overview of the special commands currently supported\&.
+dvisvgm supports several \fIspecial commands\fR that enrich the DVI command set with additional instructions for features, like color, graphics, and hyperlinks\&. The term \fIspecial command\fR, or just \fIspecial\fR, originates from the TeX command \fB\especial{\&...}\fR which does almost nothing\&. TeX only forwards the whole command to the DVI file and delegates its execution to the DVI driver\&. The DVI driver can then decide to either process or ignore it, depending on the supported statements\&. The parameter of TeX\(cqs \fB\especial\fR command is given in curly braces and may consist of an arbitrary character sequence representing the actual instruction, for example \fBcolor Red\fR\&.
+.sp
++ dvisvgm delegates the evaluation of special commands to dedicated handlers\&. Each handler is responsible for all special statements of the same command set, i\&.e\&. commands usually \(en but not necessarily \(en beginning with a common prefix\&. For example, all PDF specials start with the prefix \fBpdf:\fR, while the TPIC special set consists of 13 different commands without common identifier\&. The PDF specials are processed by dvisvgm\(cqs \fIpdf\fR handler, the TPIC ones by the \fItpic\fR handler\&. To get a list of the actually provided special handlers, use option \fB\-\-list\-specials\fR (see above)\&. The following list gives an overview of the special sets currently supported\&. The names of the handlers can also be used to disable the processing of individual sets of specials\&. For further information on this, see option \fB\-\-no\-specials\fR\&.
.PP
\fBbgcolor\fR
.RS 4
-Special statement for changing the background/page color\&. Since SVG 1\&.1 doesn\(cqt support background colors, dvisvgm inserts a rectangle of the chosen color into the generated SVG document\&. This rectangle always gets the same size as the selected or computed bounding box\&. This background color command is part of the color special set but is handled separately in order to let the user turn it off\&. For an overview of the command syntax, see the documentation of dvips, for instance\&.
+Special statements for changing the background/page color\&. Currently, dvisvgm only supports the
+\fBbackground\fR
+statement as specified in the
+dvips manual (\m[blue]https://tug.org/texinfohtml/dvips.html#Color-specifications\m[])\&. Since SVG 1\&.1 doesn\(cqt support background colors, dvisvgm inserts a rectangle of the chosen color into the generated SVG document\&. This rectangle always gets the same size as the selected or computed bounding box\&. This background color command is part of the color special set but is handled separately in order to let the user turn it off\&.
.RE
.PP
\fBcolor\fR
@@ -1364,7 +1378,7 @@ emTeX (\m[blue]https://ctan.org/pkg/emtex\m[])\&.
The hyperref specification defines several variants on how to mark hyperlinked areas in a DVI file\&. dvisvgm supports the plain HyperTeX special constructs as created with hyperref package option
\fIhypertex\fR\&. By default, all linked areas of the document are marked by a rectangle\&. Option
\fB\-\-linkmark\fR
-allows to change this behavior\&. See above for further details\&. Information on syntax and semantics of the HyperTeX specials can be found in the
+allows you to change this behavior\&. See above for further details\&. Information on syntax and semantics of the HyperTeX specials can be found in the
hyperref manual (\m[blue]https://ctan.org/pkg/hyperref\m[])\&.
.RE
.PP
@@ -1692,4 +1706,4 @@ Please report bugs using the bug tracker at GitHub (\m[blue]https://github.com/m
Written by Martin Gieseking <\m[blue]\fBmartin\&.gieseking@uos\&.de\fR\m[]>
.SH "COPYING"
.sp
-Copyright \(co 2005\-2021 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\-2022 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\&.