contrib/groff/src/devices/grotty/grotty.man

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