grotty(1)

1grotty(1)                   General Commands Manual                  grotty(1)
2
3
4

Name

6       grotty - groff output driver for typewriter-like (terminal) devices
7

Synopsis

9       grotty [-dfho] [-i|-r] [-F dir] [file ...]
10
11       grotty -c [-bBdfhouU] [-F dir] [file ...]
12
13       grotty --help
14
15       grotty -v
16       grotty --version
17

Description

19       The  GNU  roff  TTY (“Teletype”) output driver translates the output of
20       troff(1) into a form suitable for  typewriter-like  devices,  including
21       terminal  emulators.   Normally, grotty is invoked by groff(1) when the
22       latter is given one of  the  “-T  ascii”,  “-T  latin1”,  -Tlatin1,  or
23       “-T utf8” options on systems using ISO character encoding standards, or
24       with “-T cp1047” or “-T utf8” on EBCDIC-based hosts.  (In this  instal‐
25       lation,  ps  is  the  default output device.)  Use groff's -P option to
26       pass any options shown above to  grotty.   If  no  file  arguments  are
27       given, or if file is “-”, grotty reads the standard input stream.  Out‐
28       put is written to the standard output stream.
29
30       By default, grotty emits SGR escape sequences (from ISO 6429, popularly
31       called  “ANSI escapes”) to change text attributes (bold, italic, under‐
32       line, reverse video [“negative image”] and colors).  Devices supporting
33       the appropriate sequences can view roff documents using eight different
34       background and foreground colors.  Following ISO  6429,  the  following
35       colors are defined in tty.tmac: black, white, red, green, blue, yellow,
36       magenta, and cyan.  Unrecognized  colors  are  mapped  to  the  default
37       color,  which  is dependent on the settings of the terminal.  OSC 8 hy‐
38       perlinks are produced for these devices.
39
40       In keeping with long-standing practice and the rarity of terminals (and
41       emulators)  that  support  oblique  or italic fonts, italicized text is
42       represented with underlining by default—but see the -i option below.
43
44   SGR and OSC support in pagers
45       When paging grotty's output with less(1), the latter  program  must  be
46       instructed  to pass SGR and OSC sequences through to the device; its -R
47       option is one way to achieve this (less version 566  or  later  is  re‐
48       quired  for  OSC  8  support).  Consequently, programs like man(1) that
49       page roff documents with less must call it with an appropriate option.
50
51   Legacy output format
52       The -c option tells grotty to use an output format compatible with  pa‐
53       per terminals, like the Teletype machines for which roff and nroff were
54       first developed but which are no longer in wide use.   SGR  escape  se‐
55       quences  are  not  emitted; bold, italic, and underlining character at‐
56       tributes are thus not manipulated.  Instead, grotty overstrikes, repre‐
57       senting a bold character c with the sequence “c BACKSPACE c”, an italic
58       character c with the sequence “_ BACKSPACE c”, and  bold  italics  with
59       “_  BACKSPACE  c  BACKSPACE c”.  This rendering is inherently ambiguous
60       when the character c is itself the underscore.
61
62       The legacy output format can be rendered on a video terminal (or emula‐
63       tor)  by  piping  grotty's  output through ul(1), which may render bold
64       italics as reverse video.  Some implementations  of  more(1)  are  also
65       able  to  display these sequences; you may wish to experiment with that
66       command's -b option.  less renders legacy bold and italics without  re‐
67       quiring  options.   In  contrast to the terminal output drivers of some
68       other roff implementations, grotty never outputs  reverse  line  feeds.
69       There is therefore no need to filter its output through col(1).
70
71   Device control commands
72       grotty  understands one device control function produced by the roff \X
73       escape sequence in a document.
74
75       \X'tty: link [uri [key=value] ...]'
76              Embed a hyperlink using the  OSC  8  terminal  escape  sequence.
77              Specifying uri starts hyperlinked text, and omitting it ends the
78              hyperlink.  When  uri  is  present,  any  number  of  additional
79              key/value  pairs  can  be specified; their interpretation is the
80              responsibility of the pager or terminal.  Spaces or tabs  cannot
81              appear literally in uri, key, or value; they must be represented
82              in an alternate form.
83
84   Device description files
85       If the DESC file for the character encoding contains the “unicode”  di‐
86       rective, grotty emits Unicode characters in UTF-8 encoding.  Otherwise,
87       it emits characters in a single-byte encoding depending on the data  in
88       the font description files.  See groff_font(5).
89
90       A  font description file may contain a directive “internalname n” where
91       n is a decimal integer.  If the 01 bit in n is set, then  the  font  is
92       treated  as an italic font; if the 02 bit is set, then it is treated as
93       a bold font.
94
95   Typefaces
96       grotty supports the standard four styles:  R  (roman),  I  (italic),  B
97       (bold),  and  BI  (bold-italic).  Because the output driver operates in
98       nroff mode, attempts to set or change the font family or type size  are
99       ignored.
100

Options

102       --help  displays  a  usage message, while -v and --version show version
103       information; all exit afterward.
104
105       -b     Suppress the use of overstriking for bold characters  in  legacy
106              output format.
107
108       -B     Use  only overstriking for bold-italic characters in legacy out‐
109              put format.
110
111       -c     Use grotty's legacy output format (see subsection “Legacy output
112              format” above).  SGR and OSC escape sequences are not emitted.
113
114       -d     Ignore  all  \D  drawing  escape sequences in the input.  By de‐
115              fault, grotty renders \D'l...' escape  sequences  that  have  at
116              least  one zero argument (and so are either horizontal or verti‐
117              cal) using Unicode box drawing characters (for the utf8  device)
118              or  the  -, |, and + characters (for all other devices).  grotty
119              handles \D'p...' escape sequences that consist entirely of hori‐
120              zontal and vertical lines similarly.
121
122       -f     Emit a form feed at the end of each page having no output on its
123              last line.
124
125       -F dir Prepend directory dir/devname to the search path  for  font  and
126              device  description  files;  name  describes the output device's
127              character encoding, one of ascii, latin1, utf8, or cp1047.
128
129       -h     Use literal horizontal tab characters in the output.   Tabs  are
130              assumed to be set every 8 columns.
131
132       -i     Render  oblique-styled  fonts  (I and BI) with the SGR attribute
133              for italic text rather than  underlined  text.   Many  terminals
134              don't   support   this   attribute;   however,  xterm(1),  since
135              patch #314 (2014-12-28), does.  Ignored if -c is also specified.
136
137       -o     Suppress overstriking (other than  for  bold  and/or  underlined
138              characters when the legacy output format is in use).
139
140       -r     Render  oblique-styled  fonts  (I and BI) with the SGR attribute
141              for reverse video text rather than underlined text.  Ignored  if
142              -c or -i is also specified.
143
144       -u     Suppress  the use of underlining for italic characters in legacy
145              output format.
146
147       -U     Use only underlining for bold-italic characters in legacy output
148              format.
149

Environment

151       GROFF_FONT_PATH
152              A  list  of directories in which to seek the selected output de‐
153              vice's directory of device  and  font  description  files.   See
154              troff(1) and groff_font(5).
155
156       GROFF_NO_SGR
157              If  set, grotty's legacy output format is used just as if the -c
158              option were specified; see  subsection  “Legacy  output  format”
159              above.
160

Files

162       /usr/share/groff/1.23.0/font/devascii/DESC
163              describes the ascii output device.
164
165       /usr/share/groff/1.23.0/font/devascii/F
166              describes the font known as F on device ascii.
167
168       /usr/share/groff/1.23.0/font/devcp1047/DESC
169              describes the cp1047 output device.
170
171       /usr/share/groff/1.23.0/font/devcp1047/F
172              describes the font known as F on device cp1047.
173
174       /usr/share/groff/1.23.0/font/devlatin1/DESC
175              describes the latin1 output device.
176
177       /usr/share/groff/1.23.0/font/devlatin1/F
178              describes the font known as F on device latin1.
179
180       /usr/share/groff/1.23.0/font/devutf8/DESC
181              describes the utf8 output device.
182
183       /usr/share/groff/1.23.0/font/devutf8/F
184              describes the font known as F on device utf8.
185
186       /usr/share/groff/1.23.0/tmac/tty.tmac
187              defines  macros for use with the ascii, cp1047, latin1, and utf8
188              output devices.  It is automatically loaded by troffrc when  any
189              of those output devices is selected.
190
191       /usr/share/groff/1.23.0/tmac/tty-char.tmac
192              defines fallback characters for use with grotty.  See nroff(1).
193

Limitations

195       grotty is intended only for simple documents.
196
197       • There is no support for fractional horizontal or vertical motions.
198
199       • roff \D escape sequences producing anything other than horizontal and
200         vertical lines are not supported.
201
202       • Characters above the first line (that is, with a vertical drawing po‐
203         sition of 0) cannot be rendered.
204
205       • Color handling differs from other output drivers.  The groff requests
206         and escape sequences that set the stroke and fill colors instead  set
207         the foreground and background character cell colors, respectively.
208

Examples

210       The  following groff document exercises several features for which out‐
211       put device support varies:  (1)  bold  style;  (2)  italic  (underline)
212       style; (3) bold-italic style; (4) character composition by overstriking
213       (“coöperate”); (5) foreground color; (6) background color; and (7) hor‐
214       izontal and vertical line-drawing.
215
216              You might see \f[B]bold\f[] and \f[I]italic\f[].
217              Some people see \f[BI]both\f[].
218              If the output device does (not) co\z\[ad]operate,
219              you might see \m[red]red\m[].
220              Black on cyan can have a \M[cyan]\m[black]prominent\m[]\M[]
221              \D'l 1i 0'\D'l 0 2i'\D'l 1i 0' look.
222              .\" If in nroff mode, end page now.
223              .if n .pl \n[nl]u
224
225       Given  the foregoing input, compare and contrast the output of the fol‐
226       lowing.
227
228              $ groff -T ascii file
229              $ groff -T utf8 -P -i file
230              $ groff -T utf8 -P -c file | ul
231