Debian Codegraph @

upstream/debian-trixie/man1/grodvi.1

raw
1 .TH grodvi 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 grodvi \-
4 .I groff
5 output driver for TeX DVI format
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 1989-2020, 2022 Free Software Foundation, Inc.
13 .\"
14 .\" Permission is granted to make and distribute verbatim copies of this
15 .\" manual provided the copyright notice and this permission notice are
16 .\" preserved on all copies.
17 .\"
18 .\" Permission is granted to copy and distribute modified versions of
19 .\" this manual under the conditions for verbatim copying, provided that
20 .\" the entire resulting derived work is distributed under the terms of
21 .\" a permission notice identical to this one.
22 .\"
23 .\" Permission is granted to copy and distribute translations of this
24 .\" manual into another language, under the above conditions for
25 .\" modified versions, except that this permission notice may be
26 .\" included in translations approved by the Free Software Foundation
27 .\" instead of in the original English.
28 .
29 .
30 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
31 .do nr *groff_grodvi_1_man_C \n[.cp]
32 .cp 0
33 .
34 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
35 .nr do-fallback 0
36 .if !\n(.f .nr do-fallback 1 \" mandoc
37 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
38 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
39 .if \n[do-fallback] \{\
40 . de MR
41 . ie \\n(.$=1 \
42 . I \%\\$1
43 . el \
44 . IR \%\\$1 (\\$2)\\$3
45 . .
46 .\}
47 .rr do-fallback
48 .
49 .
50 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
51 .el .ds tx TeX
52 .
53 .\" This macro definition is poor style from a portability standpoint,
54 .\" but it's a good test and demonstration of the standard font
55 .\" repertoire for the devices where it has any effect at all, and so
56 .\" should be retained.
57 .de FT
58 . if '\\*(.T'dvi' .ft \\$1
59 ..
60 .
61 .
62 .\" ====================================================================
63 .SH Synopsis
64 .\" ====================================================================
65 .
66 .SY grodvi
67 .RB [ \-dl ]
68 .RB [ \-F\~\c
69 .IR dir ]
70 .RB [ \-p\~\c
71 .IR paper-format ]
72 .RB [ \-w\~\c
73 .IR n ]
74 .RI [ file\~ .\|.\|.]
75 .YS
76 .
77 .
78 .SY grodvi
79 .B \-\-help
80 .YS
81 .
82 .
83 .SY grodvi
84 .B \-v
85 .
86 .SY grodvi
87 .B \-\-version
88 .YS
89 .
90 .
91 .\" ====================================================================
92 .SH Description
93 .\" ====================================================================
94 .
95 The GNU
96 .I roff
97 DVI output driver translates the output of
98 .MR \%troff 1
99 into \*[tx] DVI format.
100 .
101 Normally,
102 .I grodvi
103 is invoked by
104 .MR groff 1
105 when the latter is given the
106 .RB \[lq] \-T\~dvi \[rq]
107 option.
108 .
109 (In this installation,
110 .B \%ps
111 is the default output device.)
112 .
113 Use
114 .IR groff 's
115 .B \-P
116 option to pass any options shown above to
117 .IR grodvi .
118 .
119 If no
120 .I file
121 arguments are given,
122 or if
123 .I file
124 is \[lq]\-\[rq],
125 .I grodvi
126 reads the standard input stream.
127 .
128 Output is written to the standard output stream.
129 .
130 .
131 .P
132 The DVI file generated by
133 .I grodvi
134 can interpreted by any correctly written DVI driver.
135 .
136 .I troff \" generic
137 drawing primitives are implemented using
138 .I tpic
139 version\~2 specials.
140 .
141 If the driver does not support these,
142 .B \[rs]D
143 escape sequences will not produce any output.
144 .
145 .
146 .P
147 Encapsulated PostScript (EPS) files can be easily included;
148 use the
149 .B PSPIC
150 macro.
151 .
152 .I pspic.tmac
153 is loaded automatically by
154 .IR dvi.tmac .
155 .
156 See
157 .MR groff_tmac 5 .
158 .
159 .
160 .P
161 The default color used by the
162 .B \[rs]m
163 and
164 .B \[rs]M
165 escape sequences is black.
166 .
167 Currently,
168 the stroke color for
169 .B \[rs]D
170 drawing escape sequences is black;
171 fill color values are translated to gray.
172 .
173 .
174 .P
175 In
176 .IR groff ,
177 as in AT&T
178 .IR troff , \" AT&T
179 the
180 .B \[rs]N
181 escape sequence can be used to access any glyph in the current font by
182 its position in the corresponding TFM file.
183 .
184 .
185 .P
186 By design,
187 the DVI format doesn't care about the physical dimensions of the output
188 medium.
189 .
190 Instead,
191 .I grodvi
192 emits the equivalent to \*[tx]'s
193 .BI \%\[rs]special{\:\%papersize= width , length }
194 on the first page;
195 .I dvips
196 (or another DVI driver)
197 then sets the page size accordingly.
198 .
199 If either the page width or length is not positive,
200 no
201 .B \%papersize
202 special is output.
203 .
204 .
205 .P
206 A device control escape sequence
207 .BI \[rs]X\[aq] anything \[aq]
208 is translated to the same DVI file instructions as would be produced by
209 .BI \%\[rs]special{ anything }
210 in \*[tx];
211 .I anything
212 cannot contain a newline.
213 .
214 .
215 .\" ====================================================================
216 .SS Typefaces
217 .\" ====================================================================
218 .
219 .I grodvi
220 supports the standard four styles:
221 .B R
222 (roman),
223 .B I
224 .RI ( italic ),
225 .B B
226 .RB ( bold ),
227 and
228 .B BI
229 (\f[BI]bold-italic\f[]).
230 .
231 Fonts are grouped into families
232 .B T
233 and
234 .B H
235 having members in each style.
236 .
237 \[lq]CM\[rq] abbreviates \[lq]Computer Modern\[rq].
238 .
239 .
240 .RS
241 .TP
242 .B TR
243 .FT TR
244 CM Roman (cmr10)
245 .FT
246 .
247 .TQ
248 .B TI
249 .FT TI
250 CM Text Italic (cmti10)
251 .FT
252 .
253 .TQ
254 .B TB
255 .FT TB
256 CM Bold Extended Roman (cmbx10)
257 .FT
258 .
259 .TQ
260 .B TBI
261 .FT TBI
262 CM Bold Extended Text Italic (cmbxti10)
263 .FT
264 .
265 .TQ
266 .B HR
267 .FT HR
268 CM Sans Serif (cmss10)
269 .FT
270 .
271 .TQ
272 .B HI
273 .FT HI
274 CM Slanted Sans Serif (cmssi10)
275 .FT
276 .
277 .TQ
278 .B HB
279 .FT HB
280 CM Sans Serif Bold Extended (cmssbx10)
281 .FT
282 .
283 .TQ
284 .B HBI
285 .FT HBI
286 CM Slanted Sans Serif Bold Extended (cmssbxo10)
287 .FT
288 .RE
289 .
290 .
291 .LP
292 The following fonts are not members of a family.
293 .
294 .
295 .RS
296 .TP
297 .B CW
298 .FT CW
299 CM Typewriter Text (cmtt10)
300 .FT
301 .
302 .TQ
303 .B CWI
304 .FT CWI
305 CM Italic Typewriter Text (cmitt10)
306 .FT
307 .RE
308 .
309 .
310 .P
311 Special fonts include
312 .B MI
313 (cmmi10),
314 .B S
315 (cmsy10),
316 .B EX
317 (cmex10),
318 .B SC
319 (cmtex10,
320 only for
321 .BR CW ),
322 and,
323 perhaps surprisingly,
324 .BR TR ,
325 .BR TI ,
326 and
327 .BR CW ,
328 .\" See font/devdvi/generate/Makefile for details.
329 because \*[tx] places some glyphs in text fonts that
330 .I troff \" generic
331 generally does not.
332 .
333 For italic fonts,
334 .B CWI
335 is used instead of
336 .BR CW .
337 .
338 .
339 .P
340 Finally,
341 the symbol fonts of the American Mathematical Society are available as
342 special fonts
343 .B SA
344 (msam10) and
345 .B SB
346 (msbm10).
347 .
348 They are are not mounted by default.
349 .
350 .
351 .br
352 .ne 2v
353 .P
354 The
355 .I \%troff
356 option
357 .B \-mec
358 loads the
359 .I ec.tmac
360 macro file,
361 employing the EC and TC fonts instead of CM.
362 .
363 These are designed similarly to the Computer Modern fonts;
364 further,
365 they provide Euro
366 .B \[rs][Eu]
367 and per mille
368 .B \[rs][%0]
369 glyphs.
370 .
371 .I ec.tmac
372 must be loaded before any language-specific macro files because it does
373 not set up the codes necessary for automatic hyphenation.
374 .
375 .
376 .\" ====================================================================
377 .SS "Font description files"
378 .\" ====================================================================
379 .
380 Use
381 .MR tfmtodit 1
382 to create
383 .I groff
384 font description files from TFM
385 (\*[tx] font metrics)
386 files.
387 .
388 The font description file should contain the following additional
389 directives,
390 which
391 .I tfmtodit
392 generates automatically.
393 .
394 .
395 .TP
396 .BI internalname\~ name
397 The name of the TFM file
398 (without the
399 .I .tfm
400 extension) is
401 .IR name .
402 .
403 .
404 .TP
405 .BI checksum\~ n
406 The checksum in the TFM file is
407 .IR n .
408 .
409 .
410 .TP
411 .BI designsize\~ n
412 The design size in the TFM file is
413 .IR n .
414 .
415 .
416 .\" ====================================================================
417 .SS "Drawing commands"
418 .\" ====================================================================
419 .
420 .I grodvi
421 supports an additional drawing command.
422 .
423 .
424 .TP
425 .BI \[rs]D\[aq]R\~ "dh dv" \[aq]
426 Draw a rule
427 (solid black rectangle)
428 with one corner at the drawing position,
429 and the diagonally opposite corner at the drawing position
430 .RI +( dh , dv ),
431 which becomes the new drawing position afterward.
432 .
433 This command produces a rule in the DVI file and so can be printed even
434 with a driver that does not support
435 .I tpic
436 specials,
437 unlike the other
438 .B \[rs]D
439 commands.
440 .
441 .
442 .\" ====================================================================
443 .SH Options
444 .\" ====================================================================
445 .
446 .B \-\-help
447 displays a usage message,
448 while
449 .B \-v
450 and
451 .B \-\-version
452 show version information;
453 all exit afterward.
454 .
455 .
456 .TP
457 .B \-d
458 Do not use
459 .I tpic
460 specials to implement drawing commands.
461 .
462 Horizontal and vertical lines are implemented by rules.
463 .
464 Other drawing commands are ignored.
465 .
466 .
467 .TP
468 .BI \-F\~ dir
469 Prepend directory
470 .RI dir /dev name
471 to the search path for font and device description files;
472 .I name
473 is the name of the device,
474 usually
475 .BR dvi .
476 .
477 .
478 .TP
479 .B \-l
480 Use landscape orientation rather than portrait.
481 .
482 .
483 .TP
484 .BI \-p\~ paper-format
485 Set physical dimensions of output medium,
486 overriding the
487 .BR \%papersize ,
488 .BR \%paperlength ,
489 and
490 .B \%paperwidth
491 directives in the
492 .I DESC
493 file.
494 .
495 .I paper-format
496 can be any argument accepted by the
497 .B \%papersize
498 directive;
499 see
500 .MR groff_font 5 .
501 .
502 .
503 .TP
504 .BI \-w\~ n
505 Draw rules (lines) with a thickness of
506 .IR n \~thousandths
507 of an em.
508 .
509 The default thickness is
510 .B 40
511 (0.04\~em).
512 .
513 .
514 .\" ====================================================================
515 .SH Environment
516 .\" ====================================================================
517 .
518 .TP
519 .I GROFF_FONT_PATH
520 lists directories in which to search for
521 .IR devdvi ,
522 .IR grodvi 's
523 directory of device and font description files.
524 .
525 See
526 .MR \%troff 1
527 and
528 .MR groff_font 5 .
529 .
530 .
531 .\" ====================================================================
532 .SH Files
533 .\" ====================================================================
534 .
535 .TP
536 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devdvi/\:DESC
537 describes the
538 .B dvi
539 output device.
540 .
541 .
542 .TP
543 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devdvi/ F
544 describes the font known
545 .RI as\~ F
546 on device
547 .BR dvi .
548 .
549 .
550 .TP
551 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:dvi\:.tmac
552 defines font mappings,
553 special characters,
554 and colors for use with the
555 .B dvi
556 output device.
557 .
558 It is automatically loaded by
559 .I \%troffrc
560 when the
561 .B dvi
562 output device is selected.
563 .
564 .
565 .TP
566 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:ec\:.tmac
567 configures the
568 .B dvi
569 output device to use
570 the EC and TC font families instead of CM
571 (Computer Modern).
572 .
573 .
574 .\" ====================================================================
575 .SH Bugs
576 .\" ====================================================================
577 .
578 DVI files produced by
579 .I grodvi
580 use a different resolution
581 (57,816 units per inch)
582 from those produced by \*[tx].
583 .
584 Incorrectly written drivers which assume the resolution used by \*[tx],
585 rather than using the resolution specified in the DVI file,
586 will not work with
587 .IR grodvi .
588 .
589 .
590 .LP
591 When using the
592 .B \-d
593 option with boxed tables,
594 vertical and horizontal lines can sometimes protrude by one pixel.
595 .
596 This is a consequence of the way \*[tx] requires that the heights
597 and widths of rules be rounded.
598 .
599 .
600 .\" ====================================================================
601 .SH "See also"
602 .\" ====================================================================
603 .
604 .UR https://\:texfaq\:.org/\:FAQ\-\:ECfonts
605 \[lq]What are the EC fonts?\[rq]
606 .UE ;
607 \*[tx] FAQ: Frequently Asked Question List for \*[tx]
608 .
609 .
610 .P
611 .MR tfmtodit 1 ,
612 .MR groff 1 ,
613 .MR \%troff 1 ,
614 .MR groff_out 5 ,
615 .MR groff_font 5 ,
616 .MR groff_char 7 ,
617 .MR groff_tmac 5
618 .
619 .
620 .\" Clean up.
621 .rm FT
622 .rm tx
623 .
624 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
625 .cp \n[*groff_grodvi_1_man_C]
626 .do rr *groff_grodvi_1_man_C
627 .
628 .
629 .\" Local Variables:
630 .\" fill-column: 72
631 .\" mode: nroff
632 .\" End:
633 .\" vim: set filetype=groff textwidth=72: