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

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