home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / printer / pcroff.arc / PCROFF.DOC next >
Text File  |  1988-08-28  |  11KB  |  514 lines
  1. .po 8
  2. .in 5
  3. .na
  4. .ta 
  5. .he 'PCROFF'- % -'PCROFF'
  6. .fo 'Dave Tutelman''August 28, 1988'
  7.  
  8. .bo
  9. .ti 0
  10. NAME
  11.  
  12. PCroff - format text
  13.  
  14. .bo
  15. .ti 0
  16. SYNOPSIS
  17.  
  18. PCroff
  19. [+
  20. .it
  21. n
  22. ] [-
  23. .it
  24. n
  25. ] [-s] [-h] [-d] [-t] [-pPRINTER] file ...
  26.  
  27. .bo
  28. .ti 0
  29. DESCRIPTION
  30.  
  31. .ul
  32. PCroff
  33. formats text according to control lines embedded
  34. in the text in the given files.
  35. Encountering a nonexistent file terminates printing.
  36. The optional flag arguments mean:
  37. .br
  38. .in +8
  39. .ti -6
  40. +n    
  41. Start printing at the first page with number
  42. .it
  43. n.
  44. .br
  45. .ti -6
  46. -n    
  47. Stop printing at the first page numbered higher
  48. than
  49. .it
  50. n.
  51. .br
  52. .ti -6
  53. -s    
  54. Stop before each page (including the first)
  55. to allow paper manipulation;
  56. resume on receipt of a keyboard input.
  57. .br
  58. .ti -6
  59. -h    
  60. Insert tabs in the output stream to replace
  61. spaces whenever appropriate.
  62. .br
  63. .ti -6
  64. -d    
  65. The output is sent directly to the screen,
  66. not the standard output.
  67. The screen attributes approximate the fonts chosen
  68. (bold & underlining are done,
  69. italic is blinking).
  70. .br
  71. .ti -6
  72. -t    
  73. Format the output for a "typewriter" type of printer,
  74. which can achieve font control only by overstriking.
  75. (In the absence of a -t or a PRINTCAP file,
  76. the default is to insert font control appropriate to
  77. the IBM, Epson, AT&T 473, and Gemini printers.)
  78. .br
  79. .ti -6
  80. -pXXX 
  81. Format the output for printer XXX (as described in the PRINTCAP file)
  82. rather than the default printer (named and described in the PRINTCAP file).
  83. The preparation of a PRINTCAP file is an appendix to this manual.
  84.  
  85. .in -8
  86. Input consists of intermixed
  87. .ul
  88. text lines,
  89. which contain information to be formatted, and
  90. .ul
  91. request lines,
  92. which contain instructions about how to format
  93. it.
  94. Request lines begin with a distinguished
  95. .ul
  96. control character,
  97. normally a period.
  98.  
  99. Output lines may be
  100. .ul
  101. filled
  102. as nearly as possible with words without regard to
  103. input lineation.
  104. Line
  105. .ul
  106. breaks
  107. may be caused at specified places by
  108. certain commands, or by the appearance of an
  109. empty input line or an input line beginning with a space.
  110.  
  111. The capabilities of
  112. .ul
  113. PCroff
  114. are specified in the attached Request Summary.
  115. Numerical values are denoted there by n or +n,
  116. titles by t, and single characters by c.
  117. Numbers denoted +n may be signed + or -,
  118. in which case they signify relative changes to
  119. a quantity, otherwise they signify
  120. an absolute resetting.
  121. Missing n fields are ordinarily taken to be 1,
  122. missing t fields to be empty,
  123. and missing c fields to shut off
  124. the appropriate special interpretation.
  125.  
  126. Running titles usually appear at top and bottom of every
  127. page.
  128. They are set by requests like
  129.  
  130. .in +10
  131. .li
  132. .he 'part1'part2'part3'
  133. .in -10
  134.  
  135. Part1 is left justified, part2 is centered,
  136. and part3 is right justified on the page.
  137. Any % sign in a title is replaced by the current
  138. page number.
  139. Any $ sign in a title is replaced by the current
  140. date (an enhancement not in
  141. .ul
  142. Roff.)
  143. Any nonblank may serve as a quote.
  144.  
  145. ASCII tab characters are replaced in the input by a
  146. .ul
  147. replacement character,
  148. normally a space,
  149. according to the
  150. column settings given by a .ta command.
  151. (See .tr for how to convert this character on output.)
  152.  
  153. Automatic hyphenation of filled output is done
  154. under control of .hy.
  155. When a word contains a designated
  156. .ul
  157. hyphenation character,
  158. that character disappears from the output and
  159. hyphens can be introduced into
  160. the word at the marked places only.
  161.  
  162. .bo
  163. .ti 0
  164. FILES
  165. .br
  166. .ul
  167. PRINTCAP
  168. allows the definition of other printers' font control.
  169. A set of instructions for preparing PRINTCAP files is
  170. in an appendix to this manual.
  171.  
  172. .ul
  173. MACWRITE.TMP
  174. is created when macros are defined,
  175. and deleted at the end of the program run.
  176.  
  177. .bo
  178. .ti 0
  179. BUGS
  180. .br
  181. .ul
  182. Roff
  183. is the simplest of the text formatting
  184. programs, and is utterly frozen.
  185. The philosophy in
  186. .ul
  187. PCroff
  188. was to preserve the spirit of this freeze
  189. and not be tempted to add enhancements.
  190. The temptation was resisted for everything but font control
  191. and dates in titles.
  192.  
  193. This is a home-brewed C version of a V7 assembly-language program.
  194. It comes with no guarantees.
  195. .bp
  196. .tr | 
  197. .in 0
  198. .ce
  199. .bo
  200. .ul
  201. REQUEST SUMMARY
  202. .sp 3
  203. .br
  204. .ta 12 20 30 
  205. .in 29
  206. .ul
  207. .ti 0
  208. Request    Break    Initial    Meaning
  209. .na
  210. .ti 0
  211. .li
  212. .ad    yes    yes    Begin adjusting right margins.
  213. .ti 0
  214. .li
  215. .ar    no    arabic    Arabic page numbers.
  216. .ti0
  217. .li
  218. .bo|n    no    -    Use bold font
  219. .bo
  220. (example)
  221. for the next n input lines.
  222. .ti 0
  223. .li
  224. .br    yes    -    Causes a line break \*- the filling of
  225. the current line is stopped.
  226. .ti 0
  227. .li
  228. .bl|n    yes    -    Insert of n blank lines, on new page if necessary.
  229. .ti 0
  230. .li
  231. .bp|+n    yes    n=1    Begin new page and number it n; no n means `+1'.
  232. .ti 0
  233. .li
  234. .cc|c    no    c=.    Control character becomes `c'.
  235. .ti 0
  236. .li
  237. .ce|n    yes    -    Center the next n input lines,
  238. without filling.
  239. .ti 0
  240. .li
  241. .de|xx    no    -    Define parameterless macro
  242. to be invoked by request `.xx'
  243. (definition ends on line beginning `..').
  244. Note that, while macro definitions can contain calls to other macros,
  245. they may not contain definitions of other macros.
  246. .ti 0
  247. .li
  248. .ds    yes    no    Double space; same as `.ls 2'.
  249. .ti 0
  250. .li
  251. .ef|t    no    t=    Even foot title becomes t.
  252. .ti 0
  253. .li
  254. .eh|t    no    t=    Even head title becomes t.
  255. .ti 0
  256. .li
  257. .fi    yes    yes    Begin filling output lines.
  258. .ti 0
  259. .li
  260. .fo    no    t=    All foot titles are t.
  261. .ti 0
  262. .li
  263. .hc|c    no    none    Hyphenation character becomes `c'.
  264. .ti 0
  265. .li
  266. .he|t    no    t=    All head titles are t.
  267. .ti 0
  268. .li
  269. .hx    no    -    Title lines are suppressed.
  270. .ti 0
  271. .li
  272. .hy|n    no    n=1    Hyphenation is done, if n=1;
  273. and is not done, if n=0.
  274. .ti 0
  275. .li
  276. .ig    no    -    Ignore input lines through
  277. a line beginning with `..'.
  278. .ti 0
  279. .li
  280. .in|+n    yes    -    Indent n spaces from left margin.
  281. .ti0
  282. .li
  283. .it|n    no    -    Use italic font
  284. .it
  285. (example)
  286. for the next n input lines.
  287. .ti 0
  288. .li
  289. .ix +n    no    -    Same as `.in' but without break.
  290. .ti 0
  291. .li
  292. .li|n    no    -    Literal, treat next n lines as text rather
  293. than as formatting requests.
  294. (Note that this does not turn off fill or adjust.
  295. That must be done explicitly with .nf and .na respectively.)
  296. .ti 0
  297. .li
  298. .ll|+n    no    n=65    Line length including indent is n characters.
  299. .ti 0
  300. .li
  301. .ls|+n    yes    n=1    Line spacing set to n lines per output line.
  302. .ti 0
  303. .li
  304. .m1|n    no    n=2    Put n blank lines between the top
  305. of page and head title.
  306. .ti 0
  307. .li
  308. .m2|n    no    n=2    n blank lines put between head title
  309. and beginning of text on page.
  310. .ti 0
  311. .li
  312. .m3|n    no    n=1    n blank lines put between end of
  313. text and foot title.
  314. .ti 0
  315. .li
  316. .m4|n    no    n=3    n blank lines put between the foot title
  317. and the bottom of page.
  318. .ti 0
  319. .li
  320. .na    yes    no    Stop adjusting the right margin.
  321. .ti 0
  322. .li
  323. .ne|n    no    -    Begin new page, if n output lines
  324. cannot fit on present page.
  325. .ti 0
  326. .li
  327. .nn|+n    no    -    The next n output lines are not numbered.
  328. .ti 0
  329. .li
  330. .n1    no    no    Add 5 to page offset;
  331. number lines in margin from 1 on each page.
  332. .ti 0
  333. .li
  334. .n2|n    no    no    Add 5 to page offset;
  335. number lines from n;
  336. stop if n=0.
  337. .ti 0
  338. .li
  339. .ni|+n    no    n=0    Line numbers are indented n.
  340. .ti 0
  341. .li
  342. .nf    yes    no    Stop filling output lines.
  343. (This also stops right-adjustment when in effect,
  344. and prevents the folding of oversize lines.)
  345. .ti 0
  346. .li
  347. .nx|file    ?    -    Switch input to `file'.
  348. .ti 0
  349. .li
  350. .of|t    no    t=    Odd foot title becomes t.
  351. .ti 0
  352. .li
  353. .oh|t    no    t=    Odd head title becomes t.
  354. .ti 0
  355. .li
  356. .pa|+n    yes    n=1    Same as `.bp'.
  357. .ti 0
  358. .li
  359. .pl|+n    no    n=66    Total paper length taken to be n lines.
  360. .ti 0
  361. .li
  362. .po|+n    no    n=0    Page offset.
  363. All lines are preceded by n spaces.
  364. .ti 0
  365. .li
  366. .ro    no    arabic    Roman page numbers.
  367. .ti 0
  368. .li
  369. .sk|n    no    -    Produce n blank pages starting next page.
  370. .ti 0
  371. .li
  372. .sp|n    yes    -    Insert block of n blank lines,
  373. except at top of page.
  374. .ti 0
  375. .li
  376. .ss    yes    yes    Single space output lines,
  377. equivalent to `.ls 1'.
  378. .ti 0
  379. .li
  380. .ta|n|n..    ?    -    Pseudotab settings.
  381. Initial tab settings are columns 9 17 25 ...
  382. .ti 0
  383. .li
  384. .tc|c    no    space    Tab replacement character becomes `c'.
  385. .ti 0
  386. .li
  387. .ti|+n    yes    -    Temporarily indent next output
  388. line n spaces.
  389. .ti0
  390. .li
  391. .tr|cdef..    no    -    Translate c into d, e into f, etc.
  392. .ti0
  393. .li
  394. .ul|n    no    -    Underline the letters and numbers
  395. .ul
  396. (example)
  397. in the next n input lines.
  398. .br
  399. .tr ||
  400. .bp
  401. .in 0
  402. .ce
  403. .bo
  404. .ul
  405. PRINTCAP FILES
  406. .sp 3
  407. .fi
  408. A file named 
  409. .ul
  410. PRINTCAP
  411. (no qualifier)
  412. is consulted by PCroff for definition of font control strings
  413. for the printer.
  414. It also contains a statement of the default printer.
  415.  
  416. The
  417. .ul
  418. PRINTCAP
  419. file consists of a default printer statement,
  420. followed by an arbitrary number of printer specifications.
  421. The grammar will be described after we see a sample
  422. .ul
  423. PRINTCAP
  424. file.
  425.  
  426. .in +3
  427. .nf
  428.        default = epson.  
  429. epson | 473 | gemini | ibm: us="\033-\001", ue="\033-\000";
  430.     bs="\033E", be="\033F", is="\0334",ie="\0335".
  431. citoh | itoh | 475 : us="\033X", ue="\033Y,
  432.     bs="\033!", be="\033\042", is="\033X", ie="\033Y".
  433. test: us="*us*", ue="*ue*", bs="*bs*",be="*be*",
  434.     is="*is*", ie="*ie*".
  435. .fi
  436. .in -3
  437.  
  438. This file names the default printer as the Epson
  439. supplied by IBM with its PC
  440. (and its look-alikes).
  441. The next two lines are a specification of the escape sequences
  442. used by the Epson for font control.
  443. (Note that the Epson could also be referred to as the
  444. 473 (for the AT&T 473 printer), IBM, or Gemini, and PCroff would find it.)
  445. The following lines are specifications for the C.Itoh
  446. Prowriter 8510 (supplied by AT&T as the 475 printer),
  447. and a fictitious "test" printer that will plant readable
  448. sequences in the output so you can see what's happening
  449. to your font control commands.
  450. (Try formatting a document with the
  451. .it
  452. -pTEST
  453. option.)
  454. .bp
  455. The specification that follows is an informal BNF
  456. description.
  457.  
  458. .in +4
  459. .nf
  460. <p-cap> ::=    <default> <p-spec>*
  461.  
  462. <default> ::=    default = <name> .
  463.  
  464. <p-spec> ::=    <name part> : <spec part> .
  465.  
  466. <name part> ::=    <name>  [ | <name> ]*
  467.  
  468. <spec part> ::=    <spec>  [ , <spec> ]*
  469.  
  470. <spec> ::=    <f-name> = " <byte>* "
  471.  
  472. <name> ::=    [A-Z,a-z,0-9]*
  473.  
  474. <byte> ::=    <character> |  \[0-7][0-7][0-7]
  475.  
  476. <f-name> ::=    us | ue | is | ie | bs | be
  477.  
  478. .fi
  479. .ul
  480. .ti -3
  481. Notes:
  482.  
  483. .ti -3
  484. Names of printers must be unique in the first three characters,
  485. which are all that the program uses to identify them.
  486.  
  487. .ti -3
  488. The characters "," ";" and ":" are treated identically as separators,
  489. so minor errors in their use will be ignored.
  490.  
  491. .ti -3
  492. Bytes in font-control strings are sometimes not easily created
  493. by a single keystroke of the ASCII character.
  494. In such cases, the octal representation preceded by a backslash
  495. will suffice.
  496. A few particularly useful octal numbers are:
  497. .in +6
  498. \033 = ESC
  499. .br
  500. \042 = "   (can't use within a string of bytes)
  501. .br
  502. \134 = \   (can't use within a string of bytes)
  503. .in -6
  504. Sorry for octal rather than hex,
  505. but since roff comes from a C culture,
  506. I thought it best to retain the original conventions of C.
  507.  
  508. .ti -3
  509. The font-control sequence names (f-names)
  510. are chosen in the spirit of
  511. .ul
  512. TERMCAP.
  513. For instance, "us" means underscore start and "ie" means italics end.
  514.