summaryrefslogtreecommitdiff
path: root/dviware/dvisvgm/doc/dvisvgm.1
diff options
context:
space:
mode:
Diffstat (limited to 'dviware/dvisvgm/doc/dvisvgm.1')
-rw-r--r--dviware/dvisvgm/doc/dvisvgm.145
1 files changed, 29 insertions, 16 deletions
diff --git a/dviware/dvisvgm/doc/dvisvgm.1 b/dviware/dvisvgm/doc/dvisvgm.1
index 995ad789fd..73a0443b68 100644
--- a/dviware/dvisvgm/doc/dvisvgm.1
+++ b/dviware/dvisvgm/doc/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-04-10
+.\" Date: 2022-01-18
.\" Manual: dvisvgm Manual
-.\" Source: dvisvgm 2.12
+.\" Source: dvisvgm 2.13
.\" Language: English
.\"
-.TH "DVISVGM" "1" "2021\-04\-10" "dvisvgm 2\&.12" "dvisvgm Manual"
+.TH "DVISVGM" "1" "2022\-01\-18" "dvisvgm 2\&.13" "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\&.
@@ -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
@@ -668,6 +668,8 @@ may consist of an arbitrary sequence of characters which make up the filenames\&
\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
@@ -677,7 +679,13 @@ 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 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:
+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
@@ -840,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
@@ -868,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
@@ -1163,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
@@ -1365,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
@@ -1693,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\&.