Debian Codegraph @

upstream/debian-unstable/man1/grotty.1

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