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.in93
1 files changed, 54 insertions, 39 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 b0e3cb6d8b8..bb7e4b60412 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-2017 Martin Gieseking <martin.gieseking@uos.de> //
+// Copyright (C) 2005-2018 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 //
@@ -62,7 +62,7 @@ The results are not as perfect as most (manually optimized) PFB or OTF counterpa
nonetheless really nice in most cases.
When running dvisvgm without option *--no-fonts*, it creates 'font' elements (+<font>+...+</font>+)
-to embed the font data into the SVG files. Unfortunately, only few SVG renderes support these
+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'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
@@ -77,7 +77,8 @@ specifying the options is not significant, i.e. you can add them in any order wi
dvisvgm's behavior. Certain options accept or require additional parameters which are directly
appended to or separated by whitespace from a short option (e.g. +-v0+ or +-v 0+). Long options
require an additional equals sign (+=+) between option name and argument but without any surrounding
-whitespace (e.g. +--verbosity=0+).
+whitespace (e.g. +--verbosity=0+). Multiple short options that don't expect a further parameter can
+be combined after a single dash (e.g. +-ejs+ rather than +-e -j -s+).
*-a, --trace-all*=['retrace']::
This option forces dvisvgm to vectorize not only the glyphs actually required to render the
@@ -202,9 +203,9 @@ Option *--font-format* is only available if dvisvgm was built with WOFF support
Loads and evaluates a single font map file or a sequence of font map files. These files are required
to resolve font file names and encodings. dvisvgm does not provide its own map files but tries to read
available ones coming with dvips or dvipdfm. If option *--fontmap* is omitted, dvisvgm looks for the
-default map files 'ps2pk.map', 'dvipdfm.map', and 'psfonts.map' (in this order). Otherwise, the
-files as option arguments are evaluated in the given order. Multiple filenames must be separated by
-commas without leading and/or trailing whitespace.
+default map files 'ps2pk.map', 'pdftex.map', 'dvipdfm.map', and 'psfonts.map' (in this order).
+Otherwise, the files as option arguments are evaluated in the given order. Multiple filenames must be
+separated by commas without leading and/or trailing whitespace.
By default, redefined mappings do not replace previous ones. However, each filename can be preceded by
an optional mode specifier (*+*, *-*, or *=*) to change this behavior:
@@ -372,7 +373,7 @@ For example, +--output="%f-%(p-1)"+ creates filenames where the numbering starts
than 1.
+
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'
++%f.svg+ otherwise. That means, a DVI file 'foo.dvi' is converted to 'foo.svg' if 'foo.dvi'
is a single-page document. Otherwise, multiple SVG files 'foo-01.svg', 'foo-02.svg', etc. are
produced. In Windows environments, the percent sign indicates dereferenced environment
variables, and must therefore be protected by a second percent sign, e.g. +--output=%%f-%%p+.
@@ -396,7 +397,7 @@ gets number 1.
*-d, --precision*='digits'::
Specifies the maximal number of decimal places applied to floating-point attribute values.
All attribute values written to the generated SVG file(s) are rounded accordingly. The
-parameter 'digits' allows integer values from 0 to 6, where 0 enables the automatic selection
+parameter 'digits' accepts integer values from 0 to 6, where 0 enables the automatic selection
of significant decimal places. This is also the default value if dvisvgm is called without
option *--precision*.
@@ -425,7 +426,7 @@ the system's temporary folder by default, e.g. +/tmp+ on Linux systems. Option *
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.
+
-If the optional parameter 'path' is omitted, dvisvgm prints the location of the system's
+If the optional parameter 'path' is omitted, dvisvgm prints the location of the system's
temp folder and exits.
*-T, --transform*='commands'::
@@ -587,7 +588,8 @@ dvisvgm offers its own small set of specials. The following list gives a brief o
*dvisvgm:img* 'width' 'height' 'file';;
Creates an image element at the current graphic position referencing the given file. JPEG, PNG, and SVG images
can be used here. However, dvisvgm does not check the file format or the file name suffix. The lengths 'width'
- and 'height' must be given as plain floating point numbers in TeX point units (1in = 72.27pt).
+ and 'height' can be given together with a unit specifier (see option *--bbox*) or as plain floating point numbers.
+ In the latter case, TeX point units are assumed (1in = 72.27pt).
*dvisvgm:bbox* n[ew] 'name';;
Defines or resets a local bounding box called 'name'. The name may consist of letters and digits.
@@ -604,31 +606,32 @@ dvisvgm offers its own small set of specials. The following list gives a brief o
*dvisvgm:bbox* 'width' 'height' ['depth'];;
Updates the bounding box of the current page by embedding a virtual rectangle ('x', 'y', 'width', 'height')
where the lower left corner is located at the current DVI drawing position ('x','y'). If the optional parameter 'depth'
- is specified, dvisvgm embeds a second rectangle ('x', 'y', 'width', -__depth__). The lengths 'width', 'height' and
- 'depth' must be given as plain floating point numbers in TeX point units (1in = 72.27pt). Depending on size and position
- of the virtual rectangle, this command either enlarges the overall bounding box or leaves it as is. It's not possible
- to reduce its extent. This special should be used in conjunction with *dvisvgm:raw* in order to update the viewport
- of the page properly.
+ is specified, dvisvgm embeds a second rectangle ('x', 'y', 'width', -__depth__). The lengths 'width', 'height', and
+ 'depth' can be given together with a unit specifier (see option *--bbox*) or as plain floating point numbers.
+ In the latter case, TeX point units are assumed (1in = 72.27pt). Depending on size and position of the virtual rectangle,
+ this command either enlarges the overall bounding box or leaves it as is. It's not possible to reduce its extent. This
+ special should be used together with *dvisvgm:raw* in order to update the viewport of the page properly.
*dvisvgm:bbox* a[bs] 'x1' 'y1' 'x2' 'y2';;
This variant of the bbox special updates the bounding box by embedding a virtual rectangle ('x1','y1','x2','y2').
- The points ('x1','y1') and ('x2','y2') denote two diagonal corners of the rectangle given in TeX point units.
+ The points ('x1','y1') and ('x2','y2') denote the absolute coordinates of two diagonal corners of the rectangle.
*dvisvgm:bbox* f[ix] 'x1' 'y1' 'x2' 'y2';;
This variant of the bbox special assigns an absolute (final) bounding box to the resulting SVG. After executing
this command, dvisvgm doesn't further alter the bounding box coordinates, except this special is called again later.
- The points ('x1','y1') and ('x2','y2') denote two diagonal corners of the rectangle given in TeX point units.
+ The points ('x1','y1') and ('x2','y2') denote the absolute coordinates of two diagonal corners of the rectangle.
+
The following TeX snippet adds two raw SVG elements to the output and updates the bounding box accordingly:
+
[source,tex]
-------------------------------------------------------------------------------------
-\special{dvisvgm:raw <circle cx='{?x}' cy='{?y}' r='10' stroke='black' fill='red'/>}
-\special{dvisvgm:bbox 20 10 10}
+-------------------------------------------------------------------------------------
+\special{dvisvgm:raw <circle cx='{?x}' cy='{?y}' r='10' stroke='black' fill='red'/>}%
+\special{dvisvgm:bbox 10bp 10bp 10bp}%
+\special{dvisvgm:bbox -10bp 10bp 10bp}
\special{dvisvgm:raw <path d='M50 200 L10 250 H100 Z' stroke='black' fill='blue'/>}
-\special{dvisvgm:bbox abs 10 200 100 250}
-------------------------------------------------------------------------------------
+\special{dvisvgm:bbox abs 10bp 200bp 100bp 250bp}
+-------------------------------------------------------------------------------------
+
*em*::
@@ -654,11 +657,18 @@ evaluate these specials, their processing must be explicitly enabled by adding o
the command-line. Otherwise, dvisvgm ignores them and computes tight bounding boxes.
*pdf*::
-pdfTeX and dvipdfmx introduced several special commands related to the generation of PDF files. Currently, only
-two of them, 'pdf:mapfile' and 'pdf:mapline' are supported by dvisvgm. These specials allow modifying the font map
-tree during the processing of DVI files. They are used by CTeX, for example. dvisvgm supports both, the dvips and
-dvipdfm font map format. For further information on the command syntax and semantics, see the documentation of
-+\pdfmapfile+ in the http://www.ctan.org/pkg/pdftex[pdfTeX user manual].
+pdfTeX and dvipdfmx introduced several special commands related to the generation of PDF files. Currently,
+only 'pdf:mapfile', 'pdf:mapline', 'pdf:pagesize', and PDF hyperlink specials are supported by dvisvgm.
+The latter are the PDF pendants to the HTML HyperTeX specials generated by the hyperref package in PDF mode.
++
+'pdf:pagesize' is similar to the 'papersize' 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 *--bbox=papersize* must be given.
++
+'pdf:mapfile' and 'pdf:mapline' allow modifying the font map tree while processing the DVI file.
+They are used by CTeX, for example. dvisvgm supports both, the dvips and dvipdfm font map format. For further
+information on the command syntax and semantics, see the documentation of +\pdfmapfile+ in the
+http://www.ctan.org/pkg/pdftex[pdfTeX user manual].
*ps*::
The famous DVI driver 'dvips' introduced its own set of specials in order to embed PostScript code into DVI files,
@@ -671,21 +681,26 @@ by dvips.
Since PostScript is a rather complex language, dvisvgm does not implement its own PostScript interpreter
but relies on http://ghostscript.com[Ghostscript] instead. If the Ghostscript library was not linked to the
dvisvgm binary, it is looked up and loaded dynamically during runtime. In this case, dvisvgm looks for
-'libgs.so.X' on Unix-like systems (supported ABI versions: 7,8,9), and for 'gsdll32.dll' or 'gsdll64.dll' on
-Windows. You can override the default file names with environment variable *LIBGS* or the command-line
-option *--libgs*. The library must be reachable through the ld search path (\*nix) or the PATH environment
-variable (Windows). Alternatively, the absolute file path can be specified. If the library cannot be found,
-dvisvgm disables the processing of PostScript specials and prints a warning message.
+'libgs.so.X' on Unix-like systems (supported ABI versions: 7,8,9), for 'libgs.X.dylib' on macOS, and for
+'gsdll32.dll' or 'gsdll64.dll' on Windows. You can override the default file names with environment variable
+*LIBGS* or the command-line option *--libgs*. The library must be reachable through the ld search path (\*nix)
+or the PATH environment variable (Windows). Alternatively, the absolute file path can be specified. If the library
+cannot be found, dvisvgm disables the processing of PostScript specials and prints a warning message.
Use option *--list-specials* to check whether PostScript support is available, i.e. entry 'ps' is present.
+
The PostScript handler also recognizes and evaluates bounding box data generated by the
http://www.ctan.org/pkg/preview[preview package] with option 'tightpage'. If such data is present in the DVI file
-and if dvisvgm is called with option *--bbox=preview*, dvisvgm adapts the bounding box of the generated SVG file
-accordingly, and prints a message showing the width, height, and depth of the box in TeX point units. Especially,
-the depth value can be used to vertically align the SVG graphics with the baseline of surrounding text in HTML or
-XSL-FO documents, for example. If you call dvisvgm with option *--bbox=min* (the default), the tight bounding box
-computed while processing the page is applied and not the one provided by the preview package. Thus, the height,
-depth and width values written to the console are adapted accordingly.
+and if dvisvgm is called with option *--bbox=preview*, dvisvgm sets the width and total height of the SVG file to
+the values derived from the preview data. Additionally, it prints a message showing the width, height,
+and depth of the box in TeX point units to the console. Especially, the depth value can be read by a post-processor
+to vertically align the SVG graphics with the baseline of surrounding text in HTML or XSL-FO documents, for example.
+Please note that SVG bounding boxes are defined by a width and (total) height. In contrast to TeX, SVG provides
+no means to differentiate between height and depth, i.e. the vertical extents above and below the baseline,
+respectively. Therefore, it is generally not possible to retrieve the depth value from the SVG file itself.
++
+If you call dvisvgm with option *--bbox=min* (the default) and preview data is present in the DVI file, dvisvgm
+doesn't apply the preview extents but computes a bounding box that tightly encloses the page contents. The height,
+depth and width values written to console are adapted accordingly.
*tpic*::
The TPIC special set defines instructions for drawing simple geometric objects. Some LaTeX packages, like
@@ -792,7 +807,7 @@ Written by {author} <{email}>
Copying
-------
-Copyright (C) 2005-2017 Martin Gieseking. Free use of this software is
+Copyright (C) 2005-2018 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.