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