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

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 438 lines · 435 code · 3 blank · 0 comment · 0 complexity · b8b9f56f3fb1b0b5ee4ef463ddb08086 MD5 · raw file

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