summaryrefslogtreecommitdiff
path: root/dviware/dvisvgm/doc/dvisvgm.txt.in
diff options
context:
space:
mode:
Diffstat (limited to 'dviware/dvisvgm/doc/dvisvgm.txt.in')
-rw-r--r--dviware/dvisvgm/doc/dvisvgm.txt.in86
1 files changed, 50 insertions, 36 deletions
diff --git a/dviware/dvisvgm/doc/dvisvgm.txt.in b/dviware/dvisvgm/doc/dvisvgm.txt.in
index 2c98ac0500..1fdd5b551b 100644
--- a/dviware/dvisvgm/doc/dvisvgm.txt.in
+++ b/dviware/dvisvgm/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-04-10 01:45 +0200
+: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
@@ -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.
@@ -458,12 +458,15 @@ Sets the pattern that determines the names of the generated SVG files. The requi
'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+, +%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.
-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.
+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+.
+
@@ -568,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
@@ -583,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.
@@ -713,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
@@ -840,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].
@@ -1006,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.