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

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