Debian Codegraph @

upstream/debian-trixie/man1/grotty.1

raw
1 .TH grotty 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 grotty \-
4 .I groff
5 output driver for typewriter-like (terminal) devices
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 1989-2021 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_grotty_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 .\" ====================================================================
51 .SH Synopsis
52 .\" ====================================================================
53 .
54 .SY grotty
55 .RB [ \-dfho ]
56 .RB [ \-i | \-r ]
57 .RB [ \-F\~\c
58 .IR dir ]
59 .RI [ file\~ .\|.\|.]
60 .YS
61 .
62 .
63 .SY "grotty \-c"
64 .RB [ \-bBdfhouU ]
65 .RB [ \-F\~\c
66 .IR dir ]
67 .RI [ file\~ .\|.\|.]
68 .YS
69 .
70 .
71 .SY grotty
72 .B \-\-help
73 .YS
74 .
75 .
76 .SY grotty
77 .B \-v
78 .
79 .SY grotty
80 .B \-\-version
81 .YS
82 .
83 .
84 .\" ====================================================================
85 .SH Description
86 .\" ====================================================================
87 .
88 The GNU
89 .I roff
90 TTY
91 (\[lq]Teletype\[rq])
92 output driver translates the output of
93 .MR \%troff 1
94 into a form suitable for typewriter-like devices,
95 including terminal emulators.
96 .
97 Normally,
98 .I grotty
99 is invoked by
100 .MR groff 1
101 when the latter is given one of the
102 .RB \[lq] \-T\~ascii \[rq],
103 .RB \[lq] \-T\~latin1 \[rq],
104 .BR \-Tlatin1 ,
105 or
106 .RB \[lq] \-T\~utf8 \[rq]
107 options on systems using ISO character encoding standards,
108 or with
109 .RB \[lq] \-T\~cp1047 \[rq]
110 or
111 .RB \[lq] \-T\~utf8 \[rq]
112 on EBCDIC-based hosts.
113 .
114 (In this installation,
115 .B \%ps
116 is the default output device.)
117 .
118 Use
119 .IR groff 's
120 .B \-P
121 option to pass any options shown above to
122 .IR grotty .
123 .
124 If no
125 .I file
126 arguments are given,
127 or if
128 .I file
129 is \[lq]\-\[rq],
130 .I grotty
131 reads the standard input stream.
132 .
133 Output is written to the standard output stream.
134 .
135 .
136 .P
137 By default,
138 .I grotty
139 emits SGR escape sequences
140 (from ISO\~6429,
141 popularly called \[lq]ANSI escapes\[rq])
142 to change text attributes
143 (bold,
144 italic,
145 underline,
146 reverse video
147 .\" ECMA-48, 2nd edition (1979) calls it "negative image".
148 [\[lq]negative image\[rq]]
149 and colors).
150 .
151 Devices supporting the appropriate sequences can view
152 .I roff
153 documents using eight different background and foreground colors.
154 .
155 Following ISO\~6429,
156 the following colors are defined in
157 .IR tty.tmac :
158 black,
159 white,
160 red,
161 green,
162 blue,
163 yellow,
164 magenta,
165 and cyan.
166 .
167 Unrecognized colors are mapped to the default color,
168 which is dependent on the settings of the terminal.
169 .
170 OSC\~8 hyperlinks are produced for these devices.
171 .
172 .
173 .P
174 In keeping with long-standing practice and the rarity of terminals
175 (and emulators)
176 that support oblique or italic fonts,
177 italicized text is represented with underlining by default\[em]but see
178 the
179 .B \-i
180 option below.
181 .
182 .
183 .\" ====================================================================
184 .SS "SGR and OSC support in pagers"
185 .\" ====================================================================
186 .
187 When paging
188 .IR grotty 's
189 output with
190 .MR less 1 ,
191 the latter program must be instructed to pass SGR and OSC sequences
192 through to the device;
193 its
194 .B \-R
195 option is one way to achieve this
196 .RI ( less
197 version 566 or later is required for OSC\~8 support).
198 .
199 Consequently,
200 programs like
201 .MR man 1
202 that page
203 .I roff
204 documents with
205 .I less
206 must call it with an appropriate option.
207 .
208 .
209 .\" ====================================================================
210 .SS "Legacy output format"
211 .\" ====================================================================
212 .
213 The
214 .B \-c
215 option tells
216 .I grotty
217 to use an output format compatible with paper terminals,
218 like the Teletype machines for which
219 .I roff
220 and
221 .I nroff
222 were first developed but which are no longer in wide use.
223 .
224 SGR escape sequences are not emitted;
225 bold,
226 italic,
227 and underlining character attributes are thus not manipulated.
228 .
229 Instead,
230 .I grotty
231 overstrikes,
232 representing a bold character
233 .I c
234 with the sequence
235 .RI \[lq] c\~\c
236 BACKSPACE\~\c
237 .IR c \[rq],
238 an italic character
239 .I c
240 with the sequence
241 .RB \[lq] _\~\c
242 BACKSPACE\~\c
243 .IR c \[rq],
244 and bold italics with
245 .RB \[lq] _\~\c
246 BACKSPACE\~\c
247 .I c
248 BACKSPACE\~\c
249 .IR c \[rq].
250 .
251 This rendering is inherently ambiguous when the character
252 .I c
253 is itself the underscore.
254 .
255 .
256 .P
257 The legacy output format can be rendered on a video terminal
258 (or emulator)
259 by piping
260 .IR grotty 's
261 output through
262 .MR ul 1 ,
263 .\" from bsdmainutils 11.1.2+b1 (on Debian Buster)
264 which may render bold italics as reverse video.
265 .
266 .\" 'more' from util-linux 2.33.1 (on Debian Buster) neither renders
267 .\" double-struck characters as bold nor supports -b, but does render
268 .\" SGR sequences (including color) with no flags required.
269 Some implementations of
270 .MR more 1
271 are also able to display these sequences;
272 you may wish to experiment with that command's
273 .B \-b
274 option.
275 .
276 .\" Version 487 of...
277 .I less
278 renders legacy bold and italics without requiring options.
279 .
280 In contrast to the terminal output drivers of some other
281 .I roff
282 implementations,
283 .I grotty
284 never outputs reverse line feeds.
285 .
286 There is therefore no need to filter its output through
287 .MR col 1 .
288 .
289 .
290 .\" ====================================================================
291 .SS "Device control commands"
292 .\" ====================================================================
293 .
294 .I grotty
295 understands one device control function produced by the
296 .I roff
297 .B \[rs]X
298 escape sequence in a document.
299 .
300 .
301 .TP
302 .BR "\[rs]X\[aq]tty: link " [\c
303 .IR uri \~[ key\c
304 .BI = value\c
305 ] \|.\|.\|.\|]\c
306 .B \[aq]
307 .
308 Embed a hyperlink using the OSC 8 terminal escape sequence.
309 .
310 Specifying
311 .I uri
312 starts hyperlinked text,
313 and omitting it ends the hyperlink.
314 .
315 When
316 .I uri
317 is present,
318 any number of additional key/value pairs can be specified;
319 their interpretation is the responsibility of the pager or terminal.
320 .
321 Spaces or tabs cannot appear literally in
322 .IR uri ,
323 .IR key ,
324 or
325 .IR value ;
326 they must be represented in an alternate form.
327 .
328 .
329 .\" ====================================================================
330 .SS "Device description files"
331 .\" ====================================================================
332 .
333 If the
334 .I DESC
335 file for the character encoding contains the
336 .RB \[lq] unicode \[rq]
337 directive,
338 .I grotty
339 emits Unicode characters in UTF-8 encoding.
340 .
341 Otherwise,
342 it emits characters in a single-byte encoding depending on the data in
343 the font description files.
344 .
345 See
346 .MR groff_font 5 .
347 .
348 .
349 .P
350 A font description file may contain a directive
351 .RB \[lq] internalname\~\c
352 .IR n \[rq]
353 where
354 .I n
355 is a decimal integer.
356 .
357 If the 01 bit in
358 .I n
359 is set,
360 then the font is treated as an italic font;
361 if the 02 bit is set,
362 then it is treated as a bold font.
363 .
364 .\" The following seems to say nothing that is not true of font
365 .\" description files in general; if so, it belongs in groff_font(5).
366 .\"The code field in the font description field gives the code which is
367 .\"used to output the character.
368 .\".
369 .\"This code can also be used in the
370 .\".I groff
371 .\".B \[rs]N
372 .\"escape sequence in a document.
373 .
374 .
375 .\" ====================================================================
376 .SS Typefaces
377 .\" ====================================================================
378 .
379 .I grotty
380 supports the standard four styles:
381 .B R
382 (roman),
383 .B I
384 .RI ( italic ),
385 .B B
386 .RB ( bold ),
387 and
388 .B BI
389 (\f[BI]bold-italic\f[]).
390 .
391 Because the output driver operates in
392 .I nroff
393 mode,
394 attempts to set or change the font family or type size are ignored.
395 .
396 .
397 .
398 .\" ====================================================================
399 .SH Options
400 .\" ====================================================================
401 .
402 .B \-\-help
403 displays a usage message,
404 while
405 .B \-v
406 and
407 .B \-\-version
408 show version information;
409 all exit afterward.
410 .
411 .
412 .TP
413 .B \-b
414 Suppress the use of overstriking for bold characters in legacy output
415 format.
416 .
417 .
418 .TP
419 .B \-B
420 Use only overstriking for bold-italic characters in legacy output
421 format.
422 .
423 .
424 .TP
425 .B \-c
426 Use
427 .IR grotty 's
428 legacy output format
429 (see subsection \[lq]Legacy output format\[rq] above).
430 .
431 SGR and OSC escape sequences are not emitted.
432 .
433 .
434 .TP
435 .B \-d
436 Ignore all
437 .B \[rs]D
438 drawing escape sequences in the input.
439 .
440 By default,
441 .I grotty
442 renders
443 .BR \[rs]D\[aq]l \|.\|.\|.\& \[aq]
444 escape sequences that have at least one zero argument
445 (and so are either horizontal or vertical)
446 using Unicode box drawing characters
447 (for the
448 .B utf8
449 device)
450 or the
451 .BR \- ,
452 .BR | ,
453 and
454 .B +
455 characters
456 (for all other devices).
457 .
458 .I grotty
459 handles
460 .BR \[rs]D\[aq]p \|.\|.\|.\& \[aq]
461 escape sequences that consist entirely of horizontal and vertical
462 lines similarly.
463 .
464 .
465 .TP
466 .B \-f
467 Emit a form feed at the end of each page having no output on its last
468 line.
469 .
470 .
471 .TP
472 .BI \-F\~ dir
473 Prepend directory
474 .RI dir /dev name
475 to the search path for font and device description files;
476 .I name
477 describes the output device's character encoding,
478 one of
479 .BR ascii ,
480 .BR latin1 ,
481 .BR utf8 ,
482 or
483 .BR cp1047 .
484 .
485 .
486 .TP
487 .B \-h
488 Use literal horizontal tab characters in the output.
489 .
490 Tabs are assumed to be set every 8 columns.
491 .
492 .
493 .TP
494 .B \-i
495 Render oblique-styled fonts
496 .RB ( I
497 and
498 .BR BI )
499 with the SGR attribute for italic text
500 rather than underlined text.
501 .
502 Many terminals don't support this attribute;
503 however,
504 .MR xterm 1 ,
505 since patch\~#314 (2014-12-28),
506 does.
507 .
508 Ignored if
509 .B \-c
510 is also specified.
511 .
512 .
513 .TP
514 .B \-o
515 Suppress overstriking
516 (other than for bold and/or underlined characters when the legacy output
517 format is in use).
518 .
519 .
520 .TP
521 .B \-r
522 Render oblique-styled fonts
523 .RB ( I
524 and
525 .BR BI )
526 with the SGR attribute for reverse video text
527 rather than underlined text.
528 .
529 Ignored if
530 .B \-c
531 or
532 .B \-i
533 is also specified.
534 .
535 .
536 .TP
537 .B \-u
538 Suppress the use of underlining for italic characters in legacy output
539 format.
540 .
541 .
542 .TP
543 .B \-U
544 Use only underlining for bold-italic characters in legacy output format.
545 .
546 .
547 .\" ====================================================================
548 .SH Environment
549 .\" ====================================================================
550 .
551 .TP
552 .I GROFF_FONT_PATH
553 A list of directories in which to seek the selected output device's
554 directory of device and font description files.
555 .
556 See
557 .MR \%troff 1
558 and
559 .MR groff_font 5 .
560 .
561 .
562 .TP
563 .I GROFF_NO_SGR
564 If set,
565 .IR grotty 's
566 legacy output format is used just as if the
567 .B \-c
568 option were specified;
569 see subsection \[lq]Legacy output format\[rq] above.
570 .
571 .
572 .br
573 .ne 3v \" Keep section heading and paragraph tag together.
574 .\" ====================================================================
575 .SH Files
576 .\" ====================================================================
577 .
578 .TP
579 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devascii/\:DESC
580 describes the
581 .B ascii
582 output device.
583 .
584 .
585 .TP
586 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devascii/ F
587 describes the font known
588 .RI as\~ F
589 on device
590 .BR ascii .
591 .
592 .
593 .TP
594 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devcp1047/\:DESC
595 describes the
596 .B cp1047
597 output device.
598 .
599 .
600 .TP
601 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devcp1047/ F
602 describes the font known
603 .RI as\~ F
604 on device
605 .BR cp1047 .
606 .
607 .
608 .TP
609 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlatin1/\:DESC
610 describes the
611 .B latin1
612 output device.
613 .
614 .
615 .TP
616 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devlatin1/ F
617 describes the font known
618 .RI as\~ F
619 on device
620 .BR latin1 .
621 .
622 .
623 .TP
624 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devutf8/\:DESC
625 describes the
626 .B utf8
627 output device.
628 .
629 .
630 .TP
631 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devutf8/ F
632 describes the font known
633 .RI as\~ F
634 on device
635 .BR utf8 .
636 .
637 .
638 .TP
639 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:tty\:.tmac
640 defines macros for use with the
641 .BR ascii ,
642 .BR cp1047 ,
643 .BR latin1 ,
644 and
645 .B utf8
646 output devices.
647 .
648 It is automatically loaded by
649 .I troffrc
650 when any of those output devices is selected.
651 .
652 .
653 .TP
654 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:tty\-char\:.tmac
655 defines fallback characters for use with
656 .I grotty.
657 .
658 See
659 .MR nroff 1 .
660 .
661 .
662 .\" XXX: The following no longer seems to be true; an inspection of the
663 .\" font/*/dev*.am files suggests no evidence of it, at any rate.
664 .\".P
665 .\"Note that on EBCDIC hosts,
666 .\"only files for the
667 .\".B cp1047
668 .\"device are installed.
669 .
670 .
671 .\" ====================================================================
672 .SH Limitations
673 .\" ====================================================================
674 .
675 .I grotty
676 is intended only for simple documents.
677 .
678 .
679 .IP \[bu] 2n
680 There is no support for fractional horizontal or vertical motions.
681 .
682 .
683 .IP \[bu]
684 .I roff
685 .B \[rs]D
686 escape sequences producing anything other than horizontal and vertical
687 lines are not supported.
688 .
689 .
690 .IP \[bu]
691 Characters above the first line
692 (that is,
693 with a vertical drawing position of\~0)
694 cannot be rendered.
695 .
696 .
697 .IP \[bu]
698 Color handling differs from other output drivers.
699 .
700 The
701 .I groff
702 requests and escape sequences that set the stroke and fill colors
703 instead set the foreground and background character cell colors,
704 respectively.
705 .
706 .
707 .\" ====================================================================
708 .SH Examples
709 .\" ====================================================================
710 .
711 The following
712 .I groff
713 document exercises several features for which output device support
714 varies:
715 (1)\~bold style;
716 (2)\~italic (underline) style;
717 (3)\~bold-italic style;
718 (4)\~character composition by overstriking (\[lq]co\[:o]perate\[rq]);
719 (5)\~foreground color;
720 (6)\~background color;
721 and
722 (7)\~horizontal and vertical line-drawing.
723 .
724 .
725 .P
726 .RS
727 .EX
728 You might see \ef[B]bold\ef[] and \ef[I]italic\ef[].
729 Some people see \ef[BI]both\ef[].
730 If the output device does (not) co\ez\e[ad]operate,
731 you might see \em[red]red\em[].
732 Black on cyan can have a \eM[cyan]\em[black]prominent\em[]\eM[]
733 \eD\[aq]l 1i 0\[aq]\eD\[aq]l 0 2i\[aq]\eD\[aq]l 1i 0\[aq] look.
734 \&.\e" If in nroff mode, end page now.
735 \&.if n .pl \en[nl]u
736 .EE
737 .RE
738 .
739 .
740 .P
741 Given the foregoing input,
742 compare and contrast the output of the following.
743 .
744 .
745 .P
746 .RS
747 .EX
748 $ \c
749 .B groff \-T ascii \c
750 .I file
751 $ \c
752 .B groff \-T utf8 \-P \-i \c
753 .I file
754 $ \c
755 .B groff \-T utf8 \-P \-c \c
756 .I file \c
757 .B | ul
758 .EE
759 .RE
760 .
761 .
762 .\" ====================================================================
763 .SH "See also"
764 .\" ====================================================================
765 .
766 \[lq]Control Functions for Coded Character Sets\[rq]
767 (ECMA-48)
768 5th\~edition,
769 Ecma International,
770 June\~1991.
771 .
772 A gratis version of ISO\~6429,
773 this document includes a normative description of SGR escape sequences.
774 .
775 Available at
776 .UR http://\:www\:.ecma\-international\:.org/\:publications/\:files/\:\
777 ECMA\-ST/\:Ecma\-048\:.pdf
778 .UE .
779 .
780 .
781 .P
782 .UR https://\:gist\:.github\:.com/\:egmontkob/\:\
783 eb114294efbcd5ad\:b1944c9f3cb5feda
784 \[lq]Hyperlinks in Terminal Emulators\[rq]
785 .UE ,
786 Egmont Koblinger.
787 .
788 .
789 .P
790 .MR groff 1 ,
791 .MR \%troff 1 ,
792 .MR groff_out 5 ,
793 .MR groff_font 5 ,
794 .MR groff_char 7 ,
795 .MR ul 1 ,
796 .MR more 1 ,
797 .MR less 1 ,
798 .MR man 1
799 .
800 .
801 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
802 .cp \n[*groff_grotty_1_man_C]
803 .do rr *groff_grotty_1_man_C
804 .
805 .
806 .\" Local Variables:
807 .\" fill-column: 72
808 .\" mode: nroff
809 .\" End:
810 .\" vim: set filetype=groff textwidth=72: