src/devices/grodvi/grodvi.man

   1 .\" -*- nroff -*-
   2 .TH GRODVI @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   3 .SH NAME
   4 grodvi \- convert groff output to TeX dvi format
   5 .
   6 .\" copying (license)
   7 .de co
   8 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
   9
  10 Permission is granted to make and distribute verbatim copies of
  11 this manual provided the copyright notice and this permission notice
  12 are preserved on all copies.
  13
  14 Permission is granted to copy and distribute modified versions of this
  15 manual under the conditions for verbatim copying, provided that the
  16 entire resulting derived work is distributed under the terms of a
  17 permission notice identical to this one.
  18
  19 Permission is granted to copy and distribute translations of this
  20 manual into another language, under the above conditions for modified
  21 versions, except that this permission notice may be included in
  22 translations approved by the Free Software Foundation instead of in
  23 the original English.
  24 ..
  25 .
  26 .do nr grodvi_C \n[.C]
  27 .cp 0
  28 .
  29 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
  30 .el .ds tx TeX
  31 .
  32 .\" Like TP, but if specified indent is more than half
  33 .\" the current line-length - indent, use the default indent.
  34 .de Tp
  35 .  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  36 .  el .TP "\\$1"
  37 ..
  38 .
  39 .de TQ
  40 .  br
  41 .  ns
  42 .  TP \$1
  43 ..
  44 .
  45 .de FT
  46 .  if '\\*(.T'dvi' .ft \\$1
  47 ..
  48 .
  49 .ad l
  50 .
  51 .
  52 .\" --------------------------------------------------------------------
  53 .SH SYNOPSIS
  54 .\" --------------------------------------------------------------------
  55 .
  56 .B grodvi
  57 [
  58 .B \-dlv
  59 ] [
  60 .BI \-F dir
  61 ] [
  62 .BI \-p papersize
  63 ] [
  64 .BI \-w n
  65 ] [
  66 .IR files \|.\|.\|.\&
  67 ]
  68 .PP
  69 It is possible to have whitespace between a command line option and its
  70 parameter.
  71 .
  72 .
  73 .\" --------------------------------------------------------------------
  74 .SH DESCRIPTION
  75 .\" --------------------------------------------------------------------
  76 .
  77 .B grodvi
  78 is a driver for
  79 .B groff
  80 that produces \*(tx dvi format.
  81 .
  82 Normally it should be run by
  83 .BR groff\ \-Tdvi .
  84 .
  85 This will run
  86 .BR @g@troff\ \-Tdvi ;
  87 it will also input the macros in
  88 .BR @MACRODIR@/dvi.tmac .
  89 .
  90 .LP
  91 The dvi file generated by
  92 .B grodvi
  93 can be printed by any correctly-written dvi driver.
  94 .
  95 The troff drawing primitives are implemented
  96 using the tpic version\~2 specials.
  97 .
  98 If the driver does not support these, the
  99 .B \[rs]D
 100 commands will not produce any output.
 101 .
 102 .LP
 103 There is an additional drawing command available:
 104 .
 105 .TP
 106 .BI \[rs]D'R\  dh\ dv '
 107 Draw a rule (solid black rectangle), with one corner
 108 at the current position, and the diagonally opposite corner
 109 at the current position
 110 .RI +( dh , dv ).
 111 .
 112 Afterwards the current position will be at the opposite corner.
 113 .
 114 This produces a rule in the dvi file and so can be printed even with a
 115 driver that does not support the tpic specials unlike the other
 116 .B \[rs]D
 117 commands.
 118 .
 119 .LP
 120 The groff command
 121 .BI \[rs]X' anything '
 122 is translated into the same command in the dvi file as would be
 123 produced by
 124 .BI \[rs]special{ anything }
 125 in \*(tx;
 126 .I anything
 127 may not contain a newline.
 128 .
 129 .LP
 130 For inclusion of EPS image files,
 131 .B \-Tdvi
 132 loads
 133 .B pspic.tmac
 134 automatically, providing the
 135 .B PSPIC
 136 macro.
 137 .
 138 Please check
 139 .BR groff_tmac (@MAN5EXT@)
 140 for a detailed description.
 141 .
 142 .LP
 143 Font files for
 144 .B grodvi
 145 can be created from tfm files using
 146 .BR tfmtodit (@MAN1EXT@).
 147 .
 148 The font description file should contain the following
 149 additional commands:
 150 .
 151 .Tp \w'\fBinternalname'u+2n
 152 .BI internalname\   name
 153 The name of the tfm file (without the
 154 .B .tfm
 155 extension) is
 156 .IR name .
 157 .
 158 .TP
 159 .BI checksum\  n
 160 The checksum in the tfm file is
 161 .IR n .
 162 .
 163 .TP
 164 .BI designsize\  n
 165 The designsize in the tfm file is
 166 .IR n .
 167 .
 168 .LP
 169 These are automatically generated by
 170 .B tfmtodit.
 171 .
 172 .LP
 173 The default color for
 174 .B \[rs]m
 175 and
 176 .B \[rs]M
 177 is black.
 178 .
 179 Currently, the drawing color for
 180 .B \[rs]D
 181 commands is always black, and fill color values are translated to gray.
 182 .
 183 .LP
 184 In
 185 .B troff
 186 the
 187 .B \[rs]N
 188 escape sequence can be used to access characters by their position
 189 in the corresponding tfm file;
 190 all characters in the tfm file can be accessed this way.
 191 .
 192 .LP
 193 By design, the DVI format doesn\[aq]t care about physical dimensions of the
 194 output medium.
 195 .
 196 Instead,
 197 .B grodvi
 198 emits the equivalent to \*[tx]\[aq]s
 199 .BI \[rs]special{papersize= width , length }
 200 on the first page;
 201 .B dvips
 202 (and possibly other DVI drivers) then sets the page size accordingly.
 203 .
 204 If either the page width or length is not positive, no papersize special
 205 is output.
 206 .
 207 .
 208 .\" --------------------------------------------------------------------
 209 .SH OPTIONS
 210 .\" --------------------------------------------------------------------
 211 .
 212 .TP
 213 .B \-d
 214 Do not use tpic specials to implement drawing commands.
 215 .
 216 Horizontal and vertical lines will be implemented by rules.
 217 .
 218 Other drawing commands will be ignored.
 219 .
 220 .TP
 221 .BI \-F dir
 222 Prepend directory
 223 .IB dir /dev name
 224 to the search path for font and device description files;
 225 .I name
 226 is the name of the device, usually
 227 .BR dvi .
 228 .
 229 .TP
 230 .B \-l
 231 Specify landscape orientation.
 232 .
 233 .TP
 234 .BI \-p papersize
 235 Specify paper dimensions.
 236 .
 237 This overrides the
 238 .BR papersize ,
 239 .BR paperlength ,
 240 and
 241 .B paperwidth
 242 commands in the
 243 .B DESC
 244 file; it accepts the same arguments as the
 245 .B papersize
 246 command (see
 247 .BR groff_font (@MAN5EXT@)
 248 for details).
 249 .
 250 .TP
 251 .B \-v
 252 Print the version number.
 253 .
 254 .TP
 255 .BI \-w n
 256 Set the default line thickness to
 257 .I n
 258 thousandths of an em.
 259 .
 260 If this option isn\[aq]t specified, the line thickness defaults to
 261 0.04\~em.
 262 .
 263 .
 264 .\" --------------------------------------------------------------------
 265 .SH USAGE
 266 .\" --------------------------------------------------------------------
 267 .
 268 There are styles called
 269 .BR R ,
 270 .BR I ,
 271 .BR B ,
 272 and
 273 .B BI
 274 mounted at font positions 1 to\ 4.
 275 The fonts are grouped into families
 276 .B T
 277 and
 278 .B H\ \c
 279 having members in each of these styles:
 280 .
 281 .RS
 282 .TP
 283 .B TR
 284 .FT TR
 285 CM Roman (cmr10)
 286 .FT
 287 .
 288 .TQ
 289 .B TI
 290 .FT TI
 291 CM Text Italic (cmti10)
 292 .FT
 293 .
 294 .TQ
 295 .B TB
 296 .FT TB
 297 CM Bold Extended Roman (cmbx10)
 298 .FT
 299 .
 300 .TQ
 301 .B TBI
 302 .FT TBI
 303 CM Bold Extended Text Italic (cmbxti10)
 304 .FT
 305 .
 306 .TQ
 307 .B HR
 308 .FT HR
 309 CM Sans Serif (cmss10)
 310 .FT
 311 .
 312 .TQ
 313 .B HI
 314 .FT HI
 315 CM Slanted Sans Serif (cmssi10)
 316 .FT
 317 .
 318 .TQ
 319 .B HB
 320 .FT HB
 321 CM Sans Serif Bold Extended (cmssbx10)
 322 .FT
 323 .
 324 .TQ
 325 .B HBI
 326 .FT HBI
 327 CM Slanted Sans Serif Bold Extended (cmssbxo10)
 328 .FT
 329 .RE
 330 .
 331 .LP
 332 There are also the following fonts which are not members of a family:
 333 .
 334 .RS
 335 .TP
 336 .B CW
 337 CM Typewriter Text (cmtt10)
 338 .FT CW
 339 .FT
 340 .
 341 .TQ
 342 .B CWI
 343 CM Italic Typewriter Text (cmitt10)
 344 .FT CWI
 345 .FT
 346 .RE
 347 .
 348 .LP
 349 Special fonts are
 350 .B MI
 351 (cmmi10),
 352 .B S
 353 (cmsy10),
 354 .B EX
 355 (cmex10),
 356 .B SC
 357 (cmtex10, only for
 358 .BR CW ),
 359 and, perhaps surprisingly,
 360 .BR TR ,
 361 .BR TI ,
 362 and
 363 .BR CW ,
 364 due to the different font encodings of text fonts.
 365 .
 366 For italic fonts,
 367 .B CWI
 368 is used instead of
 369 .BR CW .
 370 .
 371 .LP
 372 Finally, the symbol fonts of the American Mathematical Society are available
 373 as special fonts
 374 .B SA
 375 (msam10) and
 376 .B SB
 377 (msbm10).
 378 .
 379 These two fonts are not mounted by default.
 380 .
 381 .LP
 382 Using the option
 383 .B \-mec
 384 (which loads the file
 385 .BR ec.tmac )
 386 provides the EC and TC fonts.
 387 .
 388 The design of the EC family is very similar to that of the CM fonts;
 389 additionally, they give a much better coverage of groff symbols.
 390 .
 391 Note that
 392 .B ec.tmac
 393 must be called before any language-specific files; it doesn\[aq]t take
 394 care of hcode values.
 395 .
 396 .
 397 .SH ENVIRONMENT
 398 .TP
 399 .SM
 400 .B GROFF_FONT_PATH
 401 A list of directories in which to search for the
 402 .BI dev name
 403 directory in addition to the default ones.
 404 .
 405 See
 406 .BR @g@troff (@MAN1EXT@)
 407 and
 408 .BR \%groff_font (@MAN5EXT@)
 409 for more details.
 410 .
 411 .
 412 .\" --------------------------------------------------------------------
 413 .SH FILES
 414 .\" --------------------------------------------------------------------
 415 .
 416 .TP
 417 .B @FONTDIR@/devdvi/DESC
 418 Device description file.
 419 .
 420 .TP
 421 .BI @FONTDIR@/devdvi/ F
 422 Font description file for font
 423 .IR F .
 424 .
 425 .TP
 426 .B @MACRODIR@/dvi.tmac
 427 Macros for use with
 428 .BR grodvi .
 429 .
 430 .TP
 431 .B @MACRODIR@/ec.tmac
 432 Macros to switch to EC fonts.
 433 .
 434 .
 435 .\" --------------------------------------------------------------------
 436 .SH BUGS
 437 .\" --------------------------------------------------------------------
 438 .
 439 Dvi files produced by
 440 .B grodvi
 441 use a different resolution (57816 units per inch) to those produced by
 442 \*(tx.
 443 .
 444 Incorrectly written drivers which assume the resolution used by \*(tx,
 445 rather than using the resolution specified in the dvi file will not
 446 work with
 447 .BR grodvi .
 448 .
 449 .LP
 450 When using the
 451 .B \-d
 452 option with boxed tables,
 453 vertical and horizontal lines can sometimes protrude by one pixel.
 454 .
 455 This is a consequence of the way \*(tx requires that the heights
 456 and widths of rules be rounded.
 457 .
 458 .
 459 .\" --------------------------------------------------------------------
 460 .SH "SEE ALSO"
 461 .\" --------------------------------------------------------------------
 462 .
 463 .BR tfmtodit (@MAN1EXT@),
 464 .BR groff (@MAN1EXT@),
 465 .BR @g@troff (@MAN1EXT@),
 466 .BR groff_out (@MAN5EXT@),
 467 .BR groff_font (@MAN5EXT@),
 468 .BR groff_char (@MAN7EXT@),
 469 .BR groff_tmac (@MAN5EXT@)
 470 .
 471 .
 472 .\" --------------------------------------------------------------------
 473 .SH "COPYING"
 474 .\" --------------------------------------------------------------------
 475 .co
 476 .
 477 .
 478 .cp \n[grodvi_C]