Debian Codegraph @

upstream/debian-unstable/man1/grodvi.1

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