summaryrefslogtreecommitdiff
path: root/Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in')
-rw-r--r--Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in99
1 files changed, 59 insertions, 40 deletions
diff --git a/Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in b/Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in
index 739f6e5c16d..1fdd5b551bf 100644
--- a/Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in
+++ b/Build/source/texk/dvisvgm/dvisvgm-src/doc/dvisvgm.txt.in
@@ -1,6 +1,6 @@
//////////////////////////////////////////////////////////////////////////
// This file is part of dvisvgm -- a fast DVI to SVG converter //
-// Copyright (C) 2005-2021 Martin Gieseking <martin.gieseking@uos.de> //
+// Copyright (C) 2005-2022 Martin Gieseking <martin.gieseking@uos.de> //
// //
// This program is free software; you can redistribute it and/or //
// modify it under the terms of the GNU General Public License as //
@@ -22,7 +22,7 @@ Martin Gieseking <@PACKAGE_BUGREPORT@>
:man source: dvisvgm
:man version: @VERSION@
:man manual: dvisvgm Manual
-:revdate: 2021-01-03 19:25 +0100
+:revdate: 2022-01-18 10:32 +0100
Name
----
@@ -31,11 +31,11 @@ dvisvgm - converts DVI and EPS files to the XML-based SVG format
Synopsis
--------
-*dvisvgm* [ 'options' ] 'file' [.dvi]
+*dvisvgm* ['options'] 'file'[.dvi]
-*dvisvgm* --eps [ 'options' ] 'file' [.eps]
+*dvisvgm* --eps ['options'] 'file1'[.eps] 'file2'[.eps] ...
-*dvisvgm* --pdf [ 'options' ] 'file' [.pdf]
+*dvisvgm* --pdf ['options'] 'file'[.pdf]
Description
@@ -69,7 +69,7 @@ to embed the font data into the SVG files. Unfortunately, only few SVG renderers
elements yet. Most web browsers and vector graphics applications don't 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 *--no-fonts* can be given to replace the font elements
-by plain graphics paths. Most web browsers (but only few external SVG renderers) also suppport
+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 *--font-format*
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
@@ -207,9 +207,9 @@ Adds comments with further information about selected data to the SVG file. Curr
font elements and font CSS rules related to native fonts are annotated.
*-E, --eps*::
-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 'psfile' special command is created and forwarded to the
-PostScript special handler.
+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 'psfile' 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 *--libgs* for further information.
@@ -356,12 +356,12 @@ yellow filled rectangles with blue frames.
*-l, --list-specials*::
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's usually a leading string followed by a colon or a blank,
+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. 'color' or 'ps'. The listed handler names, however, don't 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 *--no-specials*. All special statements not covered by one
-of the special handlers are silently ignored.
+them to be disabled separately using option *--no-specials*. All special statements not covered by
+one of the special handlers are silently ignored.
*-M, --mag*='factor'::
Sets the magnification factor applied in conjunction with Metafont calls prior tracing the glyphs.
@@ -454,14 +454,21 @@ The following list describes the currently available optimizer modules.
expression is used.
*-o, --output*='pattern'::
-Sets the pattern specifying the names of the generated SVG files. Parameter 'pattern' is a string
-that may contain static character sequences as well as the variables +%f+, +%p+, +%P+, +%hd+,
-+%ho+, and +%hc+. +%f+ expands to the base name of the DVI file, i.e. the filename without
-suffix, +%p+ is the current page number, and +%P+ 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: +%3p+ enforces 3 digits for the current page number (001, 002, etc.). Without an
-explicit width specifier, +%p+ gets the same number of digits as +%P+.
+Sets the pattern that determines the names of the generated SVG files. The required parameter
+'pattern' 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 +%f+, +%p+, +%P+, +%n+, +%N+, +%hd+, +%ho+, and +%hc+ are variables that can be used as
+part of the pattern. +%f+ expands to the base name of the DVI file, i.e. the filename without suffix,
++%p+ is the current page number, and +%P+ the total number of pages in the DVI file. The variables
++%n+ and +%N+ expand to the number of the current file being converted (starting at 1) and the total
+number of files given, respectively.
++
+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: +%3p+ enforces 3 digits for the current page number (001, 002, etc.). Without an explicit
+width specifier, +%p+ gets the same number of digits as +%P+.
+
If you need more control over the numbering, you can use arithmetic expressions as part of a pattern.
The syntax is +%(+'expr'+)+ where 'expr' may contain additions, subtractions, multiplications, and
@@ -471,7 +478,8 @@ where the numbering starts with 0 rather than 1.
+
The variables +%hX+ contain different hash values computed from the DVI page data and the options
given on the command-line. +%hd+ and +%hc+ are only set if option *--page-hashes* is present.
-Otherwise, it's empty. For further information, see the description of option *--page-hashes* below.
+Otherwise, they are empty. For further information, see the description of option *--page-hashes*
+below.
+
The default pattern is +%f-%p.svg+ if the DVI file consists of more than one page, and
+%f.svg+ otherwise. That means, a DVI file 'foo.dvi' is converted to 'foo.svg' if 'foo.dvi'
@@ -563,7 +571,7 @@ Rotates the page content clockwise by 'angle' degrees around the page center.
This option is equivalent to *-TR*'angle'.
*-R, --relative*::
-SVG allows to define graphics paths by a sequence of absolute and/or relative path commands,
+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 *--relative* is given, relative commands are created instead. This slightly reduces
@@ -578,10 +586,10 @@ is 'stdin.svg' which can be changed with option *--output*.
Don't write the SVG output to a file but redirect it to *stdout*.
*--tmpdir*[='path']::
-In some cases, dvisvgm needs to create temporary files to work properly. These files go to
-the system's temporary folder by default, e.g. +/tmp+ on Linux systems. Option *--tmpdir*
-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.
+In some cases, dvisvgm needs to create temporary files to work properly. These files go to the
+system's temporary folder by default, e.g. +/tmp+ on Linux systems. Option *--tmpdir* can be used
+to specify a different location. Please note that dvisvgm does not create this folder if it doesn't
+exist. Therefore, you must ensure that it's actually present before running dvisvgm.
+
If the optional parameter 'path' is omitted, dvisvgm prints the location of the system's
temp folder and exits.
@@ -708,19 +716,30 @@ graphics accordingly. If a negative zoom factor is given, the 'width' and 'heigh
[[specials]]
Supported Specials
------------------
-dvisvgm supports several sets of 'special commands' 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 *--list-specials* (see above). This section gives an overview of the special commands currently
-supported.
+dvisvgm supports several 'special commands' that enrich the DVI command set with additional instructions
+for features, like color, graphics, and hyperlinks. The term 'special command', or just 'special', originates
+from the TeX command +\special{...}+ 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's +\special+ command is given in curly
+braces and may consist of an arbitrary character sequence representing the actual instruction, for example
++color Red+.
++
+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 &#x2013; but not necessarily &#x2013;
+beginning with a common prefix. For example, all PDF specials start with the prefix +pdf:+, while the TPIC
+special set consists of 13 different commands without common identifier. The PDF specials are processed by
+dvisvgm's 'pdf' handler, the TPIC ones by the 'tpic' handler. To get a list of the actually provided special
+handlers, use option *--list-specials* (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 *--no-specials*.
*bgcolor*::
-Special statement for changing the background/page color. Since SVG 1.1 doesn't 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 +background+
+statement as specified in the https://tug.org/texinfohtml/dvips.html#Color-specifications[dvips manual].
+Since SVG 1.1 doesn't 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.
*color*::
Statements of this command set provide instructions to change the text/paint color. For an overview of the
@@ -835,7 +854,7 @@ https://ctan.org/pkg/emtex[emTeX].
*html*::
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 'hypertex'.
-By default, all linked areas of the document are marked by a rectangle. Option *--linkmark* allows to change
+By default, all linked areas of the document are marked by a rectangle. Option *--linkmark* 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 https://ctan.org/pkg/hyperref[hyperref manual].
@@ -1001,7 +1020,7 @@ Written by {author} <{email}>
Copying
-------
-Copyright (C) 2005-2021 Martin Gieseking. Free use of this software is
+Copyright (C) 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.