From 5027858830867ff20c7eca53eed6f8b798c5ad9c Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 4 Mar 2022 16:00:29 +0000 Subject: 2022 doc (+sync) update git-svn-id: svn://tug.org/texlive/trunk@62387 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/man/man1/dvisvgm.1 | 56 ++++++++++++++++++++------------ 1 file changed, 35 insertions(+), 21 deletions(-) (limited to 'Master/texmf-dist/doc/man/man1/dvisvgm.1') 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 .\" Generator: DocBook XSL Stylesheets vsnapshot -.\" 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\fR\&...\fB\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\fR\&...\fB\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\&. -- cgit v1.2.3