src/devices/grotty/grotty.1.man

   1 .TH GROTTY @MAN1EXT@ "@MDATE@" "groff @VERSION@"
   2 .SH NAME
   3 grotty \- groff driver for typewriter-like devices
   4 .
   5 .
   6 .\" ====================================================================
   7 .\" Legal Terms
   8 .\" ====================================================================
   9 .\"
  10 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
  11 .\"
  12 .\" Permission is granted to make and distribute verbatim copies of this
  13 .\" manual provided the copyright notice and this permission notice are
  14 .\" preserved on all copies.
  15 .\"
  16 .\" Permission is granted to copy and distribute modified versions of
  17 .\" this manual under the conditions for verbatim copying, provided that
  18 .\" the entire resulting derived work is distributed under the terms of
  19 .\" a permission notice identical to this one.
  20 .\"
  21 .\" Permission is granted to copy and distribute translations of this
  22 .\" manual into another language, under the above conditions for
  23 .\" modified versions, except that this permission notice may be
  24 .\" included in translations approved by the Free Software Foundation
  25 .\" instead of in the original English.
  26 .
  27 .
  28 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
  29 .do nr grotty_C \n[.C]
  30 .cp 0
  31 .
  32 .
  33 .\" ====================================================================
  34 .SH SYNOPSIS
  35 .\" ====================================================================
  36 .
  37 .SY grotty
  38 .OP \-bBcdfhioruUv
  39 .OP \-F dir
  40 .RI [ file
  41 \&.\|.\|.\&]
  42 .YS
  43 .
  44 .
  45 .\" ====================================================================
  46 .SH DESCRIPTION
  47 .\" ====================================================================
  48 .
  49 .B grotty
  50 translates the output of GNU
  51 .B troff
  52 into a form suitable for typewriter-like devices.
  53 .
  54 Normally
  55 .B grotty
  56 should be invoked by using the
  57 .B groff
  58 command with a
  59 .BR \-Tascii ,
  60 .B \-Tlatin1
  61 or
  62 .B \-Tutf8
  63 option on ASCII based systems, and with
  64 .B \-Tcp1047
  65 and
  66 .B \-Tutf8
  67 on EBCDIC based hosts.
  68 .
  69 If no files are given,
  70 .B grotty
  71 reads the standard input.
  72 .
  73 A filename of
  74 .B \-
  75 also causes
  76 .B grotty
  77 to read the standard input.
  78 .
  79 Output is written to the standard output.
  80 .
  81 .
  82 .LP
  83 By default,
  84 .B grotty
  85 emits SGR escape sequences (from ISO 6429, also called ANSI color
  86 escapes) to change text attributes (bold, italic, colors).
  87 .
  88 This makes it possible to have eight different background and
  89 foreground colors; additionally, bold and italic attributes can be
  90 used \f[BI]at the same time\f[] (by using the BI font).
  91 .
  92 .
  93 .LP
  94 The following colors are defined in
  95 .BR tty.tmac :
  96 black, white, red, green, blue, yellow, magenta, cyan.
  97 .
  98 Unknown colors are mapped to the default color (which is dependent on
  99 the settings of the terminal; in most cases, this is black for the
 100 foreground and white for the background).
 101 .
 102 .
 103 .LP
 104 Use the
 105 .B \-c
 106 switch to revert to the old behaviour, printing a bold character
 107 .I c
 108 with the sequence
 109 .RI \[lq] c
 110 BACKSPACE
 111 .IR c \[rq]
 112 and an italic character
 113 .I c
 114 by the sequence
 115 .RB \[lq] _
 116 BACKSPACE
 117 .IR c \[rq].
 118 .
 119 At the same time, color output is disabled.
 120 .
 121 The same effect can be achieved by setting either the
 122 .I GROFF_NO_SGR
 123 environment variable or using the \[oq]sgr\[cq] X command (see below).
 124 .
 125 .
 126 .LP
 127 For SGR support, it is necessary to use the
 128 .B \-R
 129 option of
 130 .BR less (1)
 131 to disable the interpretation of
 132 .BR grotty 's
 133 old output format.
 134 .
 135 Consequently, all programs which use
 136 .B less
 137 as the pager program have to pass this option to it.
 138 .
 139 For
 140 .BR man (1)
 141 in particular, either add
 142 .B \-R
 143 to the
 144 .I PAGER
 145 environment variable, e.g.\&
 146 .
 147 .RS
 148 .LP
 149 .B PAGER="/usr/bin/less \-R"
 150 .br
 151 .B export PAGER
 152 .RE
 153 .LP
 154 .
 155 or use the
 156 .B \-P
 157 option of
 158 .B man
 159 to set the pager executable and its options, or modify the
 160 configuration file of
 161 .B man
 162 in a similar fashion.
 163 .
 164 Note that with some
 165 .BR man (1)
 166 versions, you have to use the
 167 .I \%MANPAGER
 168 environment variable instead.
 169 .
 170 .
 171 .LP
 172 .BR grotty 's
 173 old output format can be displayed on a terminal
 174 by piping through
 175 .BR ul (1).
 176 Pagers such as
 177 .BR more (1)
 178 or
 179 .BR less (1)
 180 are also able to display these sequences.
 181 Use either
 182 .B \-B
 183 or
 184 .B \-U
 185 when piping into
 186 .BR less (1);
 187 use
 188 .B \-b
 189 when piping into
 190 .BR more (1).
 191 There is no need to filter the output through
 192 .BR col (1)
 193 since
 194 .B grotty
 195 never outputs reverse line feeds.
 196 .
 197 .
 198 .LP
 199 The font description file may contain a command
 200 .
 201 .IP
 202 .BI internalname\  n
 203 .LP
 204 .
 205 where
 206 .I n
 207 is a decimal integer.
 208 .
 209 If the 01 bit in
 210 .I n
 211 is set,
 212 then the font is treated as an italic font;
 213 if the 02 bit is set,
 214 then it is treated as a bold font.
 215 .
 216 The code field in the font description field gives the code which is
 217 used to output the character.
 218 .
 219 This code can also be used in the
 220 .B \[rs]N
 221 escape sequence in
 222 .BR troff .
 223 .
 224 .
 225 .LP
 226 If the
 227 .I DESC
 228 file contains the keyword
 229 .BR unicode ,
 230 .B grotty
 231 emits Unicode characters in UTF-8 encoding.
 232 .
 233 Otherwise, it emits characters in a single-byte encoding depending on
 234 the data in the font description files.
 235 .
 236 See the
 237 .BR groff_font (@MAN5EXT@)
 238 man page for more details.
 239 .
 240 .
 241 .\" ====================================================================
 242 .SH OPTIONS
 243 .\" ====================================================================
 244 .
 245 Whitespace is permitted between a command-line option and its argument.
 246 .
 247 .
 248 .TP
 249 .B \-b
 250 Suppress the use of overstriking for bold characters.
 251 .
 252 Ignored if
 253 .B \-c
 254 isn't used.
 255 .
 256 .TP
 257 .B \-B
 258 Use only overstriking for bold-italic characters.
 259 Ignored if
 260 .B \-c
 261 isn't used.
 262 .
 263 .TP
 264 .B \-c
 265 Use
 266 .BR grotty 's
 267 old output format (see above).
 268 This also disables color output.
 269 .
 270 .TP
 271 .B \-d
 272 Ignore all
 273 .B \[rs]D
 274 commands.
 275 .
 276 Without this
 277 .B grotty
 278 renders
 279 .B \[rs]D'l\|.\|.\|.\&'
 280 commands that have at least one zero argument
 281 (and so are either horizontal or vertical)
 282 using
 283 .BR \- ,
 284 .BR | ,
 285 and
 286 .B +
 287 characters.
 288 .
 289 In a similar way,
 290 .B grotty
 291 handles
 292 .B \[rs]D'p\|.\|.\|.\&'
 293 commands which consist entirely of horizontal and vertical lines.
 294 .
 295 .
 296 .TP
 297 .B \-f
 298 Use form feeds in the output.
 299 .
 300 A form feed is output at the end of each page that has no output on
 301 its last line.
 302 .
 303 .TP
 304 .BI \-F dir
 305 Prepend directory
 306 .RI dir /dev name
 307 to the search path for font and device description files;
 308 .I name
 309 is the name of the device, usually
 310 .BR ascii ,
 311 .BR latin1 ,
 312 .BR utf8 ,
 313 or
 314 .BR cp1047 .
 315 .
 316 .TP
 317 .B \-h
 318 Use horizontal tabs in the output.
 319 .
 320 Tabs are assumed to be set every 8 columns.
 321 .
 322 .TP
 323 .B \-i
 324 Use escape sequences to set the italic text attribute instead of the
 325 underline attribute for italic fonts (\[oq]I\[cq] and \[oq]BI\[cq]).
 326 .
 327 Note that most terminals (including xterm) don't support this.
 328 .
 329 Ignored if
 330 .B \-c
 331 is active.
 332 .
 333 .TP
 334 .B \-o
 335 Suppress overstriking (other than for bold or underlined characters in
 336 case the old output format has been activated with
 337 .BR \-c ).
 338 .
 339 .TP
 340 .B \-r
 341 Use escape sequences to set the reverse text attribute instead of the
 342 underline attribute for italic fonts (\[oq]I\[cq] and \[oq]BI\[cq]).
 343 .
 344 Ignored if
 345 .B \-c
 346 is active.
 347 .
 348 .TP
 349 .B \-u
 350 Suppress the use of underlining for italic characters.
 351 .
 352 Ignored if
 353 .B \-c
 354 isn't used.
 355 .
 356 .TP
 357 .B \-U
 358 Use only underlining for bold-italic characters.
 359 .
 360 Ignored if
 361 .B \-c
 362 isn't used.
 363 .
 364 .TP
 365 .B \-v
 366 Print the version number.
 367 .
 368 .
 369 .\" ====================================================================
 370 .SH USAGE
 371 .\" ====================================================================
 372 .
 373 .B grotty
 374 understands a single X command produced using the
 375 .B \[rs]X
 376 escape sequence.
 377 .
 378 .TP
 379 .BI \[rs]X'tty:\ sgr\  n '
 380 .
 381 If
 382 .I n
 383 is non-zero or missing, enable SGR output (this is the default),
 384 otherwise use the old drawing scheme for bold and underline.
 385 .
 386 .
 387 .\" ====================================================================
 388 .SH ENVIRONMENT
 389 .\" ====================================================================
 390 .
 391 .TP
 392 .I GROFF_NO_SGR
 393 If set, the old drawing scheme for bold and underline (using the
 394 backspace character) is active.
 395 .
 396 Colors are disabled.
 397 .
 398 .
 399 .TP
 400 .I GROFF_FONT_PATH
 401 A list of directories in which to search for the
 402 .IR dev name
 403 directory in addition to the default ones.
 404 .
 405 See
 406 .BR @g@troff (@MAN1EXT@)
 407 and
 408 .BR \%groff_font (@MAN5EXT@)
 409 for more details.
 410 .
 411 .
 412 .\" ====================================================================
 413 .SH FILES
 414 .\" ====================================================================
 415 .
 416 .TP
 417 .I @FONTDIR@/devascii/DESC
 418 Device description file for the
 419 .B ascii
 420 device.
 421 .
 422 .TP
 423 .IR @FONTDIR@/devascii/ F
 424 Font description file for font
 425 .I F
 426 of the
 427 .B ascii
 428 device.
 429 .
 430 .TP
 431 .I @FONTDIR@/devlatin1/DESC
 432 Device description file for the
 433 .B latin1
 434 device.
 435 .
 436 .TP
 437 .IR @FONTDIR@/devlatin1/ F
 438 Font description file for font
 439 .I F
 440 of the
 441 .B latin1
 442 device.
 443 .
 444 .TP
 445 .I @FONTDIR@/devutf8/DESC
 446 Device description file for the
 447 .B utf8
 448 device.
 449 .
 450 .TP
 451 .IR @FONTDIR@/devutf8/ F
 452 Font description file for font
 453 .I F
 454 of the
 455 .B utf8
 456 device.
 457 .
 458 .TP
 459 .I @FONTDIR@/devcp1047/DESC
 460 Device description file for the
 461 .B cp1047
 462 device.
 463 .
 464 .TP
 465 .IR @FONTDIR@/devcp1047/ F
 466 Font description file for font
 467 .I F
 468 of the
 469 .B cp1047
 470 device.
 471 .
 472 .TP
 473 .I @MACRODIR@/tty.tmac
 474 Macros for use with
 475 .BR grotty .
 476 .
 477 .TP
 478 .I @MACRODIR@/tty\-char.tmac
 479 Additional character definitions for use with
 480 .BR grotty .
 481 .
 482 .LP
 483 Note that on EBCDIC hosts, only files for the
 484 .B cp1047
 485 device is installed.
 486 .
 487 .
 488 .\" ====================================================================
 489 .SH BUGS
 490 .\" ====================================================================
 491 .
 492 .B grotty
 493 is intended only for simple documents.
 494 .
 495 .
 496 .LP
 497 There is no support for fractional horizontal or vertical motions.
 498 .
 499 .
 500 .LP
 501 There is no support for
 502 .B \[rs]D
 503 commands other than horizontal and vertical lines.
 504 .
 505 .
 506 .LP
 507 Characters above the first line (i.e.\& with a vertical position
 508 of\~0) cannot be printed.
 509 .
 510 .
 511 .LP
 512 Color handling differs from
 513 .BR grops (@MAN1EXT@).
 514 .B \[rs]M
 515 doesn't set the fill color for closed graphic objects (which
 516 .B grotty
 517 doesn't support anyway) but changes the background color of the
 518 character cell, affecting all subsequent operations.
 519 .
 520 .
 521 .\" ====================================================================
 522 .SH "SEE ALSO"
 523 .\" ====================================================================
 524 .BR groff (@MAN1EXT@),
 525 .BR @g@troff (@MAN1EXT@),
 526 .BR groff_out (@MAN5EXT@),
 527 .BR groff_font (@MAN5EXT@),
 528 .BR groff_char (@MAN7EXT@),
 529 .BR ul (1),
 530 .BR more (1),
 531 .BR man (1),
 532 .BR less (1)
 533 .
 534 .
 535 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
 536 .cp \n[grotty_C]
 537 .
 538 .
 539 .\" Local Variables:
 540 .\" mode: nroff
 541 .\" End:
 542 .\" vim: set filetype=groff: