src/devices/grotty/grotty.man

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