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

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