From 0bb29634e3fdca8563bdc863ac09b90e57141d85 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 28 Apr 2014 22:59:31 +0000 Subject: general man update for TL14 git-svn-id: svn://tug.org/texlive/trunk@33735 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/man/man1/dvisvgm.1 | 98 +++++++++++++++++++++++--------- 1 file changed, 72 insertions(+), 26 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 54a376f687b..c0814786d09 100644 --- a/Master/texmf-dist/doc/man/man1/dvisvgm.1 +++ b/Master/texmf-dist/doc/man/man1/dvisvgm.1 @@ -1,13 +1,13 @@ '\" t .\" Title: dvisvgm -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 03/01/2013 +.\" Author: Martin Gieseking +.\" Generator: DocBook XSL Stylesheets v1.78.1 +.\" Date: 04/11/2014 .\" Manual: dvisvgm Manual -.\" Source: dvisvgm 1.2 +.\" Source: dvisvgm 1.5.3 .\" Language: English .\" -.TH "DVISVGM" "1" "03/01/2013" "dvisvgm 1\&.2" "dvisvgm Manual" +.TH "DVISVGM" "1" "04/11/2014" "dvisvgm 1\&.5\&.3" "dvisvgm Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -32,15 +32,19 @@ dvisvgm \- converts DVI files to the XML\-based SVG format .SH "SYNOPSIS" .sp \fBdvisvgm\fR [ \fIoptions\fR ] \fIfile\fR [\&.dvi] +.sp +\fBdvisvgm\fR \-E [ \fIoptions\fR ] \fIfile\fR [\&.eps] .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\&. Since the current SVG standard 1\&.1 doesn\(cqt specify multi\-page graphics, dvisvgm creates separate SVG files for each DVI page\&. Because of compatibility reasons, only the first page is converted by default\&. In order to select a different page or arbitrary page sequences, use option \fB\-p\fR which is described below\&. +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 format 2 as well as format 3 (created by pTeX in vertical mode), and format 5 which is also known as XDV (created by XeTeX)\&. Besides the basic DVI commands, dvisvgm also evaluates many so\-called \fIspecials\fR which heavily extend the capabilities of the DVI format\&. For a more detailed overview, see section \fBsupport of specials\fR below\&. +.sp +Since the current SVG standard 1\&.1 doesn\(cqt specify multi\-page graphics, dvisvgm creates separate SVG files for each DVI page\&. Because of compatibility reasons, only the first page is converted by default\&. In order to select a different page or arbitrary page sequences, use option \fB\-p\fR which is described below\&. .sp -dvisvgm should properly convert all pages that are made up of fonts and rules only\&. However, the utility also supports a couple of DVI extensions defined in terms of \fIDVI specials\fR\&. For a more detailed overview, see section \fBsupport of specials\fR below\&. +SVG is a vector\-based graphics format and therefore dvisvgm tries to convert the glyph outlines of all used fonts to scalable path descriptions\&. The fastest way to do that is to extract the path information from font files in PFB, TTF, or OTF format\&. If dvisvgm is able to find such a file, it extracts all necessary outline information about the glyphs from it\&. .sp -As SVG is a vector based graphics format, dvisvgm tries to convert the glyph outlines of all used fonts into scalable path descriptions\&. The fastest way to do that is to extract the path information from PFB (PostScript Type 1) files\&. So, if dvisvgm is able to find a PFB file for a required font, it will read the necessary information from this file\&. +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 -TeX\(cqs main source for font descriptions is Metafont though, which produces bitmap output\&. That\(cqs why not all obtainable TeX fonts are available in PFB format\&. In these cases, dvisvgm tries to vectorize Metafont\(cqs output (GF fonts) by tracing the glyph bitmaps\&. The results are not as perfect as most (manually optimized) PFB outlines but are nonetheless really nice in most cases\&. +When running dvisvgm without option \fB\-\-no\-fonts\fR, \fIfont\fR elements (\&...) are used to embed the font data into the SVG files\&. Unfortunately, only few SVG renderes 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\&. .SH "OPTIONS" .PP \fB\-a, \-\-trace\-all\fR=[\fIretrace\fR] @@ -128,7 +132,6 @@ T} .TE .sp 1 .RE -.RE .PP \fBPage orientation\fR .RS 4 @@ -170,6 +173,7 @@ only affects the bounding box and does not transform the page content\&. Hence, .sp .5v .RE .RE +.RE .PP \fB\-C, \-\-cache\fR[=\fIdir\fR] .RS 4 @@ -178,7 +182,7 @@ To speed up the conversion process of bitmap fonts, dvisvgm saves intermediate c to overwrite the default\&. Furthermore, it is also possible to disable the font caching mechanism completely with option \fB\-\-cache=none\fR\&. If argument \fIdir\fR -is omitted, dvisvgm prints the path of the default cache directory and some information about the stored fonts\&. Additionally, outdated and corrupted cache files are removed\&. +is omitted, dvisvgm prints the path of the default cache directory together with further information about the stored fonts\&. Additionally, outdated and corrupted cache files are removed\&. .RE .PP \fB\-\-color\fR @@ -198,15 +202,16 @@ for further information\&. .PP \fB\-e, \-\-exact\fR .RS 4 -If this option is given, dvisvgm computes the precise bounding box of each character\&. By default, the values stored in a font\(cqs TFM file are used to determine a glyph\(cqs extent\&. As these values are intended to realize optimal character placements and are not designed to represent the exact dimensions, they don\(cqt necessarily correspond with the bounds of the visual glyphs\&. Thus, width and/or height of some glyphs may be larger than the respective TFM values\&. As a result, this can lead to clipped characters at the bounds of the SVG graphic\&. With option -\fB\-\-exact\fR, dvisvgm analyzes the actual shape of each character and derives a usually tight bounding box\&. +If this option is given, dvisvgm computes the precise bounding box of each character\&. By default, the values stored in a font\(cqs TFM file are used to determine a glyph\(cqs extent\&. As these values are intended to implement optimal character placements and are not designed to represent the exact dimensions, they don\(cqt necessarily correspond with the bounds of the visual glyphs\&. Thus, width and/or height of some glyphs may be larger (or smaller) than the respective TFM values\&. As a result, this can lead to clipped characters at the bounds of the SVG graphics\&. With option +\fB\-\-exact\fR +given, dvisvgm analyzes the actual shape of each character and derives a usually tight bounding box\&. .RE .PP \fB\-m, \-\-fontmap\fR=\fIfilenames\fR .RS 4 -Loads and evaluates a single or multiple font map files\&. These files are required to resolve font file names and encodings\&. dvisvgm does not provide its own map file but tries to read available ones coming with dvips or dvipdfm\&. If option -\fB\-\-fonrmapm\fR -is not given, dvisvgm looks for the default map files +Loads and evaluates a single or multiple 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 +\fB\-\-fontmap\fR +is omitted, dvisvgm looks for the default map files ps2pk\&.map, dvipdfm\&.map, and psfonts\&.map @@ -248,9 +253,9 @@ where all redefinitions of myfile1\&.map replace previous entries\&. Afterwards, all definitions for the fonts given in myfile2\&.map -are removed again\&. +are removed from the font map tree\&. .sp -For further information about the map file formats, see the manuals of dvips and dvipdfm\&. +For further information about the map file formats and the mode specifiers, see the manuals of dvips and dvipdfm\&. .RE .RE .PP @@ -258,7 +263,7 @@ For further information about the map file formats, see the manuals of dvips and .RS 4 Prints a short summary of all available command\-line options\&. The optional \fImode\fR -parameter is an integer value between 0 and 2\&. It selects the display variant of the help text\&. Mode 0 lists all options divided into categories with section headers\&. This is also the default if dvisvgm is called without parameters\&. Mode 1 lists all options ordered by the short option name, while mode 2 sorts the lines by the long option name\&. +parameter is an integer value between 0 and 2\&. It selects the display variant of the help text\&. Mode 0 lists all options divided into categories with section headers\&. This is also the default if dvisvgm is called without parameters\&. Mode 1 lists all options ordered by the short option names, while mode 2 sorts the lines by the long option names\&. .RE .PP \fB\-\-keep\fR @@ -274,6 +279,30 @@ can be used to give a different name\&. Alternatively, it\(cqs also possible to LIBGS\&. The latter has less precedence than the command\-line option\&. .RE .PP +\fB\-L, \-\-linkmark\fR=\fItype\fR +.RS 4 +Selects the method how to mark hyperlinked areas\&. The +\fItype\fR +argument can take one of the values +\fInone\fR, +\fIbox\fR, and +\fIline\fR, where the latter is the default, i\&.e\&. all links are underlined when dvisvgm is called without option +\fB\-\-linkmark\fR\&. Type +\fIbox\fR +draws a rectangle around the linked area, and +\fInone\fR +tells dvisvgm not to add any visible objects to hyperlinks\&. Additionally, the argument +\fItype\fR +can take a dvips color name as listed here: +http://en\&.wikibooks\&.org/wiki/LaTeX/Colors#The_68_standard_colors_known_to_dvips +It\(cqs also possible to give an explicit hexadecimal RGB value of the form +\fI#RRGGBB\fR, e\&.g\&. +\fI#0000ff\fR +or simply +\fI#ff\fR +for blue\&. The color is used to highlight the linked area\&. +.RE +.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 word separated from the rest of the statement by a colon or a blank, e\&.g\&. @@ -298,7 +327,7 @@ If this option is given, dvisvgm doesn\(cqt create SVG \fIfont\fR elements but uses \fIpaths\fR -instead\&. The resulting SVG files tends to be larger but concurrently more compatible with most applications that don\(cqt support SVG fonts yet\&. The optional argument +instead\&. The resulting SVG files tend to be larger but they are concurrently more compatible with most applications that don\(cqt support SVG fonts yet\&. The optional argument \fIvariant\fR selects the method how to substitute fonts by paths\&. Variant 0 creates \fIpath\fR @@ -654,11 +683,11 @@ This option cannot be combined with .RE .SH "SUPPORT OF SPECIALS" .sp -dvisvgm supports several sets of \fIspecial commands\fR that can be used to enrich DVI files with additional features, like color, graphics or hyperlinks\&. The evaluation of special commands is delegated to various handlers\&. 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 actually provided special handlers, use option \fB\-\-list\-specials\fR (see above)\&. +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 various handlers\&. 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 actually provided special handlers, use option \fB\-\-list\-specials\fR (see above)\&. This section gives an overview of the special commands currently supported\&. .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\&. In the current version, this rectangle always gets the size of the minimal bounding box\&. This 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 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\&. .RE .PP \fBcolor\fR @@ -763,6 +792,14 @@ The following TeX snippet adds two raw SVG elements to the output and updates th These specials were introduced with the emTeX distribution by Eberhard Mattes\&. They provide line drawing statements, instructions for embedding MSP, PCX, and BMP image files, as well as two PCL commands\&. dvisvgm supports only the line drawing statements and ignores all other em specials silently\&. A description of the command syntax can be found in the DVI driver documentation coming with emTeX (see CTAN)\&. .RE .PP +\fBhtml\fR +.RS 4 +The hyperref specials allow the definition of hyperlinks inside DVI files in various flavors\&. dvisvgm supports the plain HyperTeX special constructs as created with hyperref package option +\fIhypertex\fR\&. Internal links, i\&.e\&. references to other parts of the same document, are only converted if the link and the corresponding link target are located on the same page\&. Links between different pages are not supported yet\&. By default, all linked areas of the document are underlined\&. 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 hyperref manual\&. +.RE +.PP \fBpdf\fR .RS 4 pdfTeX and dvipdfmx introduced several special commands related to the generation of PDF files\&. Currently, only two of them, @@ -790,6 +827,11 @@ or the command\-line option to check whether PS support is available, i\&.e\&. the entry \fIps\fR is present\&. +.sp +The PostScript handler also recognizes and evaluates bounding box data generated by the +\fIpreview\fR +package with option +\fItightpage\fR\&. If the data is present in a DVI file, 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\&. .RE .PP \fBtpic\fR @@ -853,7 +895,7 @@ If dvisvgm was linked without the Ghostscript library, and if PostScript support .sp The pre\-compiled Windows versions of dvisvgm require a working installation of MiKTeX 2\&.9 or above\&. dvisvgm does not work together with the portable edition of MiKTeX because it relies on MiKTeX\(cqs COM interface only accessible in a local installation\&. To enable the evaluation of PostScript specials, the original Ghostscript DLL \fIgsdll32\&.dll\fR must be present and reachable through the search path\&. 64\-bit Windows builds require the 64\-bit Ghostscript DLL \fIgsdll64\&.dll\fR\&. Both DLLs come with the corresponding Ghostscript installers available from www\&.ghostscript\&.com\&. .sp -The environment variable DVISVGM_COLORS specifies the colors used to highlight various parts of dvisvgm\(cqs message output\&. It is only evaluated if option \fB\-\-color\fR is given\&. The value of DVISVGM_COLORS is a list of colon\-separated entries of the form \fIgg\fR=\fIBF\fR, where \fIgg\fR denotes one of the color group indicators listed below, and \fIBF\fR are two hexadecimal digits specifying the background (first digit) and foreground/text color (second digit)\&. The color color values are defined as follows: 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=gray, 8=bright red, 9=bright green, A=bright yellow, B=bright blue, C=bright magenta, D=bright cyan, E=bright gray, F=white\&. Depending on the terminal, the colors may differ\&. Rather than changing both the text and background color, it\(cqs also possible to change only one of them: An asterisk (*) in place of a hexadecimal digit indicates the default text or background color of the terminal\&. +The environment variable DVISVGM_COLORS specifies the colors used to highlight various parts of dvisvgm\(cqs message output\&. It is only evaluated if option \fB\-\-color\fR is given\&. The value of DVISVGM_COLORS is a list of colon\-separated entries of the form \fIgg\fR=\fIBF\fR, where \fIgg\fR denotes one of the color group indicators listed below, and \fIBF\fR are two hexadecimal digits specifying the background (first digit) and foreground/text color (second digit)\&. The color values are defined as follows: 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=gray, 8=bright red, 9=bright green, A=bright yellow, B=bright blue, C=bright magenta, D=bright cyan, E=bright gray, F=white\&. Depending on the terminal, the colors may differ\&. Rather than changing both the text and background color, it\(cqs also possible to change only one of them: An asterisk (*) in place of a hexadecimal digit indicates the default text or background color of the terminal\&. .sp All malformed entries in the list are silently ignored\&. .TS @@ -1012,13 +1054,11 @@ T} .PP Project home page .RS 4 - http://dvisvgm\&.sourceforge\&.net .RE .PP SourceForge project site .RS 4 - http://sourceforge\&.net/projects/dvisvgm .RE .SH "BUGS" @@ -1029,4 +1069,10 @@ Please report bugs using the bug tracker at Launchpad (see https://launchpad\&.n Written by Martin Gieseking .SH "COPYING" .sp -Copyright \(co 2005\-2013 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\-2014 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\&. +.SH "AUTHOR" +.PP +\fBMartin Gieseking\fR <\&martin\&.gieseking@uos\&.de\&> +.RS 4 +Author. +.RE -- cgit v1.2.3