summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/dvisvgm.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/dvisvgm.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/dvisvgm.1196
1 files changed, 137 insertions, 59 deletions
diff --git a/Master/texmf-dist/doc/man/man1/dvisvgm.1 b/Master/texmf-dist/doc/man/man1/dvisvgm.1
index 063eb4b3da5..dbcd907ab54 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: 2022-10-14
+.\" Date: 2024-01-06
.\" Manual: dvisvgm Manual
-.\" Source: dvisvgm 3.0.3
+.\" Source: dvisvgm 3.2
.\" Language: English
.\"
-.TH "DVISVGM" "1" "2022\-10\-14" "dvisvgm 3\&.0\&.3" "dvisvgm Manual"
+.TH "DVISVGM" "1" "2024\-01\-06" "dvisvgm 3\&.2" "dvisvgm Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -87,11 +87,11 @@ invoice, executive, legal, letter, ledger
.RS 4
.TS
tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx.
T{
\fBdvi\fR
T}:T{
@@ -176,16 +176,16 @@ and
should be sufficient in most cases\&. The following list gives an overview of the known format names which correspond to names of Ghostscript output devices\&.
.TS
tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx.
T{
\fBnone\fR
T}:T{
@@ -299,7 +299,26 @@ predefined colors (\m[blue]https://www.w3.org/TR/SVG11/types.html#ColorKeywords\
Adds comments with further information about selected data to the SVG file\&. Currently, only font elements and font CSS rules related to native fonts are annotated\&.
.RE
.PP
-\fBembed\-bitmaps\fR
+\fB\-\-currentcolor\fR[=\fIcolor\fR]
+.RS 4
+This option tells dvisvgm to replace the specified color with CSS variable
+\fBcurrentColor\fR
+which holds the current foreground color set by CSS property
+\fBcolor\fR\&. This way an application or website can change the color via CSS without the need to modify the SVG code\&.
+.sp
+The optional argument of
+\fB\-\-currentcolor\fR
+specifies the RGB color value to be replaced and must be given as either
+six or three digit hex color value (\m[blue]https://www.w3.org/TR/css-color/#typedef-hex-color\m[])
+preceded by character
+\fB#\fR, e\&.g\&.
+\fB#0000ff\fR
+or
+\fB#00f\fR
+for blue\&. If the optional argument is omitted, black is assumed\&.
+.RE
+.PP
+\fB\-\-embed\-bitmaps\fR
.RS 4
Embeds the contents of bitmap files into the generated SVG files instead of adding file references\&. Because of the base64\-encoded data, the SVG files are usually much bigger but at the same time more portable because they don\(cqt rely on external bitmap files\&.
.sp
@@ -322,6 +341,8 @@ for further information\&.
This option tells dvisvgm to compute the precise bounding box of each character\&. By default, the values stored in a font\(cqs TFM file are used to determine a glyph\(cqs extent\&. As these values are intended to implement 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, width and/or height of some glyphs may be larger (or smaller) than the respective TFM values\&. As a result, this can lead to clipped characters at the bounds of the SVG graphics\&. With option
\fB\-\-exact\-bbox\fR
given, dvisvgm analyzes the actual shape of each character and derives a usually tight bounding box\&.
+.sp
+This option only affects the processing of DVI files\&. When converting EPS or PDF files, the bounding box information stored in these files are used to derive the SVG bounding box\&.
.RE
.PP
\fB\-f, \-\-font\-format\fR=\fIformat\fR
@@ -531,6 +552,21 @@ or
Sets the magnification factor applied in conjunction with Metafont calls prior tracing the glyphs\&. The larger this value, the better the tracing results\&. Nevertheless, large magnification values can cause Metafont arithmetic errors due to number overflows\&. So, use this option with care\&. The default setting usually produces nice results\&.
.RE
.PP
+\fB\-\-message\fR=\fItext\fR
+.RS 4
+Prints a given message to the console after an SVG file has been written\&. Argument
+\fItext\fR
+may consist of static text and the macros listed below in the description of special command
+\fBdvisvgm:raw\fR\&. For example,
+\fB\-\-message="page {?pageno} written to {?svgfile}"\fR
+prints the message with the macros expanded after the conversion of each page of a DVI or PDF file or after processing an EPS file\&.
+.sp
+The output of option
+\fB\-\-message\fR
+is not affected by the specified verbosity level, i\&.e\&. it prints the text even with
+\fB\-\-verbosity=0\fR\&.
+.RE
+.PP
\fB\-\-no\-merge\fR
.RS 4
Puts every single character in a separate
@@ -600,7 +636,15 @@ By default, dvisvgm creates CSS styles and class attributes to reference fonts\&
\fB\-O, \-\-optimize\fR[=\fImodules\fR]
.RS 4
Applies several optimizations on the generated SVG tree to reduce the file size\&. The optimizations are performed by running separate optimizer modules specified by optional argument
-\fImodules\fR\&. It may consist of a single module name or a comma\-separated list of several module names\&. The corresponding modules are executed one by one in the given order and thus transform the XML tree gradually\&.
+\fImodules\fR\&. It may consist of a single module name or a comma\-separated list of several module names\&. The corresponding modules are executed one by one in the given order and thus transform the XML tree gradually\&. A leading hyphen (\fB\-\fR) can be used to exclude a module from processing\&. For example
+\fB\-Oall,\-collapse\-groups\fR
+performs all optimizations except
+\fBcollapse\-groups\fR\&. If the first module name in the list starts with a hyphen, dvisvgm automatically inserts
+\fBall\fR
+at the beginning, i\&.e\&.
+\fB\-O\-collapse\-groups\fR
+is identical to
+\fB\-Oall,\-collapse\-groups\fR\&.
.sp
The following list describes the currently available optimizer modules\&.
.PP
@@ -620,9 +664,9 @@ can\(cqt be combined with other module names\&.
.RS 4
Performs all optimizations listed below\&. This is also the default if option
\fB\-\-optimize\fR
-is used without argument\&. The modules are executed in a predefined order that usually leads to the best results\&.
+is used without any arguments\&. The modules are executed in a predefined order that usually leads to the best results\&.
\fBall\fR
-can\(cqt be combined with other module names\&.
+must be the only or the first entry in the list of module names\&.
.RE
.PP
\fBcollapse\-groups\fR
@@ -853,15 +897,16 @@ If this option is given, dvisvgm does not expect a DVI but a PDF input file, and
\fB\-\-page\fR
can be used to select different pages, page ranges, and/or page sequences\&.
.sp
-If a Ghostcript version < 10\&.1\&.0 is found, dvisvgm uses Ghostscript to process the PDF file\&. In this case, the conversion is realized by creating a single
+If a Ghostcript version < 10\&.01\&.0 is found, dvisvgm uses Ghostscript to process the PDF file\&. In this case, the conversion is realized by creating a single
\fIpdffile\fR
special command which is forwarded to dvisvgm\(cqs PostScript special handler\&. Therefore, this option is only available if dvisvgm was built with PostScript support enabled, and requires Ghostscript to be accessible\&. See option
\fB\-\-libgs\fR
for further information\&.
.sp
-As of Ghostscript 10\&.1\&.0, this will no longer work due to the introduction of a new PDF interpreter\&. Therefore, an alternative conversion module based on
-mutool (\m[blue]https://mupdf.com/docs/mutool.html\m[])
-has been introduced\&. It\(cqs automatically invoked if Ghostscript can\(cqt be used and if a working
+As of Ghostscript 10\&.01\&.0, this will no longer work due to the introduction of a new PDF interpreter\&. Therefore, an alternative conversion module based on
+\fImutool\fR, a utility which is part of the
+MuPDF (\m[blue]https://mupdf.com\m[])
+package, has been introduced\&. It\(cqs automatically invoked if Ghostscript can\(cqt be used and if a working
\fBmutool\fR
executable is present in a directory which is part of the system\(cqs search path\&.
.sp
@@ -1093,10 +1138,10 @@ are applied in the order of their appearance\&. Multiple commands can optionally
Additionally, some pre\-defined constants are provided:
.TS
tab(:);
-lt lt
-lt lt
-lt lt
-lt lt.
+lt ltx
+lt ltx
+lt ltx
+lt ltx.
T{
\fBux\fR
T}:T{
@@ -1161,10 +1206,11 @@ Translates (moves) the page content in direction of vector (\fItx\fR,\fIty\fR)\&
Controls the type of messages printed during a dvisvgm run:
.TS
tab(:);
-lt lt
-lt lt
-lt lt
-lt lt.
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx.
T{
\fB0\fR
T}:T{
@@ -1185,6 +1231,12 @@ T{
T}:T{
informational messages only
T}
+T{
+\fB8\fR
+T}:T{
+user messages only (e\&.g\&. created by special
+\fBdvisvgm:message\fR)
+T}
.TE
.sp 1
.if n \{\
@@ -1199,7 +1251,7 @@ T}
\fBNote\fR
.ps -1
.br
-By adding these values you can combine the categories\&. The default level is 7, i\&.e\&. all messages are printed\&.
+By adding these values you can combine the categories\&. The default level is 15, i\&.e\&. all messages are printed\&.
.sp .5v
.RE
.RE
@@ -1233,7 +1285,7 @@ attributes are omitted\&.
.sp
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\&.
+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
@@ -1263,13 +1315,16 @@ special\&. Both syntactically incorrect and wrongly nested tags lead to error me
may also contain the expressions
\fB{?x}\fR,
\fB{?y}\fR,
-\fB{?color}\fR, and
-\fB{?matrix}\fR
+\fB{?color}\fR,
+\fB{?matrix}\fR,
+\fB{?pageno}\fR,
+\fB{?svgfile}\fR, and
+\fB{?svgpath}\fR
that expand to the current
\fIx\fR
or
\fIy\fR
-coordinate, the current color, and current transformation matrix, respectively\&. Character sequence
+coordinate, the current color, the current transformation matrix, the current page number, and the relative and absolute path of the SVG file being created, respectively\&. Character sequence
\fB{?nl}\fR
expands to a newline character\&. Finally, constructions of the form
\fB{?(\fR\fB\fIexpr\fR\fR\fB)}\fR
@@ -1423,6 +1478,29 @@ The following TeX snippet adds two raw SVG elements to the output and updates th
.RE
.\}
.RE
+.PP
+\fBdvisvgm:currentcolor\fR [on|off]
+.RS 4
+This special works similar to option
+\fB\-\-currentcolor\fR
+but doesn\(cqt require an explicit color argument\&. Instead, it takes the currently active color and replaces it with
+\fBcurrentColor\fR\&. Therefore, the result depends on the placement of the special and the preceding color changes\&. Argument
+\fBon\fR
+\(en which activates the
+\fIcurrentColor\fR
+functionality \(en can be omitted\&. When called with argument
+\fBoff\fR, the functionality is deactivated again\&.
+.RE
+.PP
+\fBdvisvgm:message\fR \fImsg\fR
+.RS 4
+Prints the given text
+\fImsg\fR
+to the console\&. It may also contain the macros
+\fI{?\&...}\fR
+mentioned above (see
+\fBdvisvgm:raw\fR)\&.
+.RE
.RE
.PP
\fBem\fR
@@ -1461,7 +1539,7 @@ pdfTeX and dvipdfmx introduced several special commands related to the generatio
\fIpdf:pagesize\fR
is similar to the
\fIpapersize\fR
-special (see above) which specifies the size of the current and all folowing pages\&. In order to actually apply the extents to the generated SVG files, option
+special (see above) which specifies the size of the current and all following pages\&. In order to actually apply the extents to the generated SVG files, option
\fB\-\-bbox=papersize\fR
must be given\&.
.sp
@@ -1597,14 +1675,14 @@ The environment variable \fBDVISVGM_COLORS\fR specifies the colors used to highl
All malformed entries in the list are silently ignored\&.
.TS
tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx.
T{
.sp
\fBer\fR
@@ -1666,21 +1744,21 @@ T}
.sp
\fBExample:\fR \fBer=01:pi=*5\fR sets the colors of error messages (\fBer\fR) to red (\fB1\fR) on black (\fB0\fR), and those of progress indicators (\fBpi\fR) to cyan (\fB5\fR) on default background (\fB*\fR)\&.
.sp
-Variable \fBDVISVGM_PDF_PROC\fR allows you to select the desired PDF processor\&. dvisvgm requires either Ghostscript (version < 10\&.1\&.0) or mutool to process PDF files\&. IF \fBDVISVGM_PDF_PROC\fR is not set, dvisvgm tries to detect the available processors\&. See option \fB\-\-pdf\fR for further information\&. To select a specific PDF processor, you can set \fBDVISVGM_PDF_PROC\fR to \fBgs\fR or \fBmutool\fR which forces the use of Ghostscript and mutool respectively\&.
+Variable \fBDVISVGM_PDF_PROC\fR allows you to select the desired PDF processor\&. dvisvgm requires either Ghostscript (version < 10\&.01\&.0) or mutool to process PDF files\&. IF \fBDVISVGM_PDF_PROC\fR is not set, dvisvgm tries to detect the available processors\&. See option \fB\-\-pdf\fR for further information\&. To select a specific PDF processor, you can set \fBDVISVGM_PDF_PROC\fR to \fBgs\fR or \fBmutool\fR which forces the use of Ghostscript and mutool respectively\&.
.SH "FILES"
.sp
The location of the following files is determined by the kpathsea library\&. To check the actual kpathsea configuration you can use the \fBkpsewhich\fR utility\&.
.TS
tab(:);
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt
-lt lt.
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx
+lt ltx.
T{
.sp
\fB*\&.enc\fR
@@ -1768,4 +1846,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\-2023 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\-2024 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\&.