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