/contrib/groff/src/preproc/grn/grn.man

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 652 lines · 649 code · 3 blank · 0 comment · 0 complexity · 1a5bf6accc50b30b9b600a878e9a8440 MD5 · raw file

  1. '\" t
  2. .ig
  3. Copyright (C) 2000, 2001, 2002, 2003, 2004 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 grn_C \n[.C]
  19. .cp 0
  20. .
  21. .de TQ
  22. . br
  23. . ns
  24. . TP \\$1
  25. ..
  26. .
  27. .\" Like TP, but if specified indent is more than half
  28. .\" the current line-length - indent, use the default indent.
  29. .de Tp
  30. . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  31. . el .TP "\\$1"
  32. ..
  33. .
  34. .
  35. .TH @G@GRN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
  36. .SH NAME
  37. @g@grn \- groff preprocessor for gremlin files
  38. .SH SYNOPSIS
  39. .BR @g@grn
  40. [
  41. .B \-Cv
  42. ]
  43. [
  44. .BI \-T dev
  45. ]
  46. [
  47. .BI \-M dir
  48. ]
  49. [
  50. .BI \-F dir
  51. ]
  52. [
  53. .IR file\.\.\.\&
  54. ]
  55. .PP
  56. It is possible to have whitespace between a command line option and its
  57. parameter.
  58. .SH DESCRIPTION
  59. .I @g@grn
  60. is a preprocessor for including
  61. .I gremlin
  62. pictures in
  63. .I groff
  64. input.
  65. .I @g@grn
  66. writes to standard output, processing only input lines between two that
  67. start with
  68. .B .GS
  69. and
  70. .BR .GE.
  71. Those lines must contain
  72. .I @g@grn
  73. commands (see below).
  74. These commands request a
  75. .I gremlin
  76. file, and the picture in that file is
  77. converted and placed in the
  78. .I @g@troff
  79. input stream.
  80. The
  81. .B .GS
  82. request may be followed by a C, L, or R to center, left, or right
  83. justify the whole
  84. .I gremlin
  85. picture (default justification is center).
  86. If no
  87. .I file
  88. is mentioned, the standard input is read.
  89. At the end of the picture, the position on the page is the bottom of the
  90. .I gremlin
  91. picture.
  92. If the
  93. .I @g@grn
  94. entry is ended with
  95. .B .GF
  96. instead of
  97. .BR .GE ,
  98. the position is left at the top of the picture.
  99. .PP
  100. Please note that currently only the \-me macro package has support for
  101. .BR .GS ,
  102. .BR .GE ,
  103. and
  104. .BR .GF .
  105. .PP
  106. The following command-line options are understood:
  107. .TP
  108. .BI \-T dev
  109. Prepare output for printer
  110. .IR dev .
  111. The default device is
  112. .BR @DEVICE@ .
  113. See
  114. .BR groff (@MAN1EXT@)
  115. for acceptable devices.
  116. .TP
  117. .BI \-M dir
  118. Prepend
  119. .I dir
  120. to the default search path for
  121. .I gremlin
  122. files.
  123. The default path is (in that order) the current directory, the home
  124. directory,
  125. .BR @SYSTEMMACRODIR@ ,
  126. .BR @LOCALMACRODIR@ ,
  127. and
  128. .BR @MACRODIR@ .
  129. .TP
  130. .BI \-F dir
  131. Search
  132. .I dir
  133. for subdirectories
  134. .BI dev name
  135. .RI ( name
  136. is the name of the device) for the
  137. .B DESC
  138. file before the default font directories
  139. .BR @LOCALFONTDIR@ ,
  140. .BR @FONTDIR@ ,
  141. and
  142. .BR @LEGACYFONTDIR@ .
  143. .TP
  144. .B \-C
  145. Recognize
  146. .B .GS
  147. and
  148. .B .GE
  149. (and
  150. .BR .GF )
  151. even when followed by a character other than space or newline.
  152. .\".TP
  153. .\".B \-s
  154. .\"This switch causes the picture to be traversed twice:
  155. .\"The first time, only the interiors of filled polygons (as borderless
  156. .\"polygons) are printed.
  157. .\"The second time, the outline is printed as a series of line segments.
  158. .\"This way, postprocessors that overwrite rather than merge picture elements
  159. .\"(such as Postscript) can still have text and graphics on a shaded
  160. .\"background.
  161. .TP
  162. .B \-v
  163. Print the version number.
  164. .SH GRN COMMANDS
  165. Each input line between
  166. .B .GS
  167. and
  168. .B .GE
  169. may have one
  170. .I @g@grn
  171. command.
  172. Commands consist of one or two strings separated by white space, the first
  173. string being the command and the second its operand.
  174. Commands may be upper or lower case and abbreviated down to one character.
  175. .PP
  176. Commands that affect a picture's environment (those listed before
  177. .BR default ,
  178. see below) are only in effect for the current picture:
  179. The environment is reinitialized to the defaults at the start of the next
  180. picture.
  181. The commands are as follows:
  182. .TP
  183. .BI 1\ N
  184. .TQ
  185. .BI 2\ N
  186. .TQ
  187. .BI 3\ N
  188. .TQ
  189. .BI 4\ N
  190. Set
  191. .IR gremlin 's
  192. text size number 1 (2, 3, or 4) to
  193. .I N
  194. points.
  195. The default is 12 (16, 24, and 36, respectively).
  196. .TP
  197. .BI roman\ f
  198. .TQ
  199. .BI italics\ f
  200. .TQ
  201. .BI bold\ f
  202. .TQ
  203. .BI special\ f
  204. Set the roman (italics, bold, or special) font to
  205. .IR @g@troff 's
  206. font
  207. .I f
  208. (either a name or number).
  209. The default is R (I, B, and S, respectively).
  210. .TP
  211. .BI l\ f
  212. .TQ
  213. .BI stipple\ f
  214. Set the stipple font to
  215. .IR @g@troff 's
  216. stipple font
  217. .I f
  218. (name or number).
  219. The command
  220. .B stipple
  221. may be abbreviated down as far as `st' (to avoid
  222. confusion with
  223. .BR special ).
  224. There is
  225. .I no
  226. default for stipples (unless one is set by the default command), and it is
  227. invalid to include a
  228. .I gremlin
  229. picture with polygons without specifying a
  230. stipple font.
  231. .TP
  232. .BI x\ N
  233. .TQ
  234. .BI scale\ N
  235. Magnify the picture (in addition to any default magnification) by
  236. .IR N ,
  237. a floating point number larger than zero.
  238. The command
  239. .B scale
  240. may be abbreviated down to `sc'.
  241. .TP
  242. .BI narrow\ N
  243. .TQ
  244. .BI medium\ N
  245. .TQ
  246. .BI thick\ N
  247. Set the thickness of
  248. .IR gremlin 's
  249. narrow (medium and thick, respectively) lines to
  250. .I N
  251. times 0.15pt (this value can be changed at compile time).
  252. The default is 1.0 (3.0 and 5.0, respectively), which corresponds to 0.15pt
  253. (0.45pt and 0.75pt, respectively).
  254. A thickness value of zero selects the smallest available line thickness.
  255. Negative values cause the line thickness to be proportional to the current
  256. point size.
  257. .TP
  258. .BI pointscale\ <off/on>
  259. Scale text to match the picture.
  260. Gremlin text is usually printed in the point size specified with the
  261. commands
  262. .BR 1 ,
  263. .BR 2 ,
  264. .BR 3 ,
  265. .RB or\~ 4 ,
  266. regardless of any scaling factors in the picture.
  267. Setting
  268. .B pointscale
  269. will cause the point sizes to scale with the picture (within
  270. .IR @g@troff 's
  271. limitations, of course).
  272. An operand of anything but
  273. .I off
  274. will turn text scaling on.
  275. .TP
  276. .B default
  277. Reset the picture environment defaults to the settings in the current
  278. picture.
  279. This is meant to be used as a global parameter setting mechanism at the
  280. beginning of the
  281. .I @g@troff
  282. input file, but can be used at any time to reset the
  283. default settings.
  284. .TP
  285. .BI width\ N
  286. Forces the picture to be
  287. .I N
  288. inches wide.
  289. This overrides any scaling factors present in the same picture.
  290. .RB ` width
  291. .IR 0 '
  292. is ignored.
  293. .TP
  294. .BI height\ N
  295. Forces picture to be
  296. .I N
  297. inches high, overriding other scaling factors.
  298. If both `width' and `height' are specified the tighter constraint will
  299. determine the scale of the picture.
  300. .B Height
  301. and
  302. .B width
  303. commands are not saved with a
  304. .B default
  305. command.
  306. They will, however, affect point size scaling if that option is set.
  307. .TP
  308. .BI file\ name
  309. Get picture from
  310. .I gremlin
  311. file
  312. .I name
  313. located the current directory (or in the library directory; see the
  314. .B \-M
  315. option above).
  316. If two
  317. .B file
  318. commands are given, the second one overrides the first.
  319. If
  320. .I name
  321. doesn't exist, an error message is reported and processing continues from
  322. the
  323. .B .GE
  324. line.
  325. .SH NOTES ABOUT GROFF
  326. Since
  327. .I @g@grn
  328. is a preprocessor, it doesn't know about current indents, point sizes,
  329. margins, number registers, etc.
  330. Consequently, no
  331. .I @g@troff
  332. input can be placed between the
  333. .B .GS
  334. and
  335. .B .GE
  336. requests.
  337. However,
  338. .I gremlin
  339. text is now processed by
  340. .IR @g@troff ,
  341. so anything legal in a single line of
  342. .I @g@troff
  343. input is legal in a line of
  344. .I gremlin
  345. text (barring `.' directives at the beginning of a line).
  346. Thus, it is possible to have equations within a
  347. .I gremlin
  348. figure by including in the
  349. .I gremlin
  350. file
  351. .I eqn
  352. expressions enclosed by previously defined delimiters (e.g.
  353. .IR $$ ).
  354. .PP
  355. When using
  356. .I @g@grn
  357. along with other preprocessors, it is best to run
  358. .I tbl
  359. before
  360. .IR @g@grn ,
  361. .IR pic ,
  362. and/or
  363. .I ideal
  364. to avoid overworking
  365. .IR tbl .
  366. .I Eqn
  367. should always be run last.
  368. .PP
  369. A picture is considered an entity, but that doesn't stop
  370. .I @g@troff
  371. from trying to break it up if it falls off the end of a page.
  372. Placing the picture between `keeps' in \-me macros will ensure proper
  373. placement.
  374. .PP
  375. .I @g@grn
  376. uses
  377. .IR @g@troff 's
  378. number registers
  379. .B g1
  380. through
  381. .B g9
  382. and sets registers
  383. .B g1
  384. and
  385. .B g2
  386. to the width and height of the
  387. .I gremlin
  388. figure (in device units) before entering the
  389. .B .GS
  390. request (this is for those who want to rewrite these macros).
  391. .SH GREMLIN FILE FORMAT
  392. There exist two distinct
  393. .I gremlin
  394. file formats, the original format from the
  395. .I AED
  396. graphic terminal version, and the
  397. .I SUN
  398. or
  399. .I X11
  400. version.
  401. An extension to the
  402. .IR SUN / X11
  403. version allowing reference points with negative coordinates is
  404. .B not
  405. compatible with the
  406. .I AED
  407. version.
  408. As long as a
  409. .I gremlin
  410. file does not contain negative coordinates, either format will be read
  411. correctly by either version of
  412. .I gremlin
  413. or
  414. .IR @g@grn .
  415. The other difference to the
  416. .IR SUN / X11
  417. format is the use of names for picture objects (e.g., POLYGON, CURVE)
  418. instead of numbers.
  419. Files representing the same picture are shown in Table 1 in each format.
  420. .sp
  421. .TS
  422. center, tab(@);
  423. l lw(0.1i) l.
  424. sungremlinfile@@gremlinfile
  425. 0 240.00 128.00@@0 240.00 128.00
  426. CENTCENT@@2
  427. 240.00 128.00@@240.00 128.00
  428. 185.00 120.00@@185.00 120.00
  429. 240.00 120.00@@240.00 120.00
  430. 296.00 120.00@@296.00 120.00
  431. *@@-1.00 -1.00
  432. 2 3@@2 3
  433. 10 A Triangle@@10 A Triangle
  434. POLYGON@@6
  435. 224.00 416.00@@224.00 416.00
  436. 96.00 160.00@@96.00 160.00
  437. 384.00 160.00@@384.00 160.00
  438. *@@-1.00 -1.00
  439. 5 1@@5 1
  440. 0@@0
  441. -1@@-1
  442. .T&
  443. css.
  444. .sp
  445. Table 1. File examples
  446. .TE
  447. .sp
  448. .IP \(bu
  449. The first line of each
  450. .I gremlin
  451. file contains either the string
  452. .B gremlinfile
  453. .RI ( AED
  454. version) or
  455. .B sungremlinfile
  456. .RI ( SUN / X11 )
  457. .IP \(bu
  458. The second line of the file contains an orientation, and
  459. .B x
  460. and
  461. .B y
  462. values for a positioning point, separated by spaces.
  463. The orientation, either
  464. .B 0
  465. or
  466. .BR 1 ,
  467. is ignored by the
  468. .IR SUN / X11
  469. version.
  470. .B 0
  471. means that
  472. .I gremlin
  473. will display things in horizontal format (drawing area wider than it is
  474. tall, with menu across top).
  475. .B 1
  476. means that
  477. .I gremlin
  478. will display things in vertical format (drawing area taller than it is wide,
  479. with menu on left side).
  480. .B x
  481. and
  482. .B y
  483. are floating point values giving a positioning point to be used when this
  484. file is read into another file.
  485. The stuff on this line really isn't all that important; a value of ``1 0.00
  486. 0.00'' is suggested.
  487. .IP \(bu
  488. The rest of the file consists of zero or more element specifications.
  489. After the last element specification is a line containing the string ``-1''.
  490. .IP \(bu
  491. Lines longer than 127 characters are chopped to this limit.
  492. .SH ELEMENT SPECIFICATIONS
  493. .IP \(bu
  494. The first line of each element contains a single decimal number giving the
  495. type of the element
  496. .RI ( AED
  497. version) or its ASCII name
  498. .RI ( SUN / X11
  499. version).
  500. See Table 2.
  501. .sp
  502. .TS
  503. center, tab(@);
  504. css
  505. ccc
  506. nll.
  507. \fIgremlin\fP File Format \(mi Object Type Specification
  508. .sp
  509. \fIAED\fP Number@\fISUN\fP/\fIX11\fP Name@Description
  510. 0@BOTLEFT@bottom-left-justified text
  511. 1@BOTRIGHT@bottom-right-justified text
  512. 2@CENTCENT@center-justified text
  513. 3@VECTOR@vector
  514. 4@ARC@arc
  515. 5@CURVE@curve
  516. 6@POLYGON@polygon
  517. 7@BSPLINE@b-spline
  518. 8@BEZIER@B\['e]zier
  519. 10@TOPLEFT@top-left-justified text
  520. 11@TOPCENT@top-center-justified text
  521. 12@TOPRIGHT@top-right-justified text
  522. 13@CENTLEFT@left-center-justified text
  523. 14@CENTRIGHT@right-center-justified text
  524. 15@BOTCENT@bottom-center-justified text
  525. .T&
  526. css.
  527. .sp
  528. Table 2.
  529. Type Specifications in \fIgremlin\fP Files
  530. .TE
  531. .sp
  532. .IP \(bu
  533. After the object type comes a variable number of lines, each specifying a
  534. point used to display the element.
  535. Each line contains an x-coordinate and a y-coordinate in floating point
  536. format, separated by spaces.
  537. The list of points is terminated by a line containing the string ``-1.0
  538. -1.0''
  539. .RI ( AED
  540. version) or a single asterisk, ``*''
  541. .RI ( SUN / X11
  542. version).
  543. .IP \(bu
  544. After the points comes a line containing two decimal values, giving the
  545. brush and size for the element.
  546. The brush determines the style in which things are drawn.
  547. For vectors, arcs, and curves there are six legal brush values:
  548. .sp
  549. .TS
  550. center, tab(@);
  551. ncw(0.1i)l.
  552. 1 \(mi@@thin dotted lines
  553. 2 \(mi@@thin dot-dashed lines
  554. 3 \(mi@@thick solid lines
  555. 4 \(mi@@thin dashed lines
  556. 5 \(mi@@thin solid lines
  557. 6 \(mi@@medium solid lines
  558. .TE
  559. .sp
  560. For polygons, one more value, 0, is legal.
  561. It specifies a polygon with an invisible border.
  562. For text, the brush selects a font as follows:
  563. .sp
  564. .TS
  565. center, tab(@);
  566. ncw(0.1i)l.
  567. 1 \(mi@@roman (R font in groff)
  568. 2 \(mi@@italics (I font in groff)
  569. 3 \(mi@@bold (B font in groff)
  570. 4 \(mi@@special (S font in groff)
  571. .TE
  572. .sp
  573. If you're using
  574. .I @g@grn
  575. to run your pictures through
  576. .IR groff ,
  577. the font is really just a starting font:
  578. The text string can contain formatting sequences like
  579. ``\efI''
  580. or
  581. ``\ed''
  582. which may change the font (as well as do many other things).
  583. For text, the size field is a decimal value between 1 and 4.
  584. It selects the size of the font in which the text will be drawn.
  585. For polygons, this size field is interpreted as a stipple number to fill the
  586. polygon with.
  587. The number is used to index into a stipple font at print time.
  588. .IP \(bu
  589. The last line of each element contains a decimal number and a string of
  590. characters, separated by a single space.
  591. The number is a count of the number of characters in the string.
  592. This information is only used for text elements, and contains the text
  593. string.
  594. There can be spaces inside the text.
  595. For arcs, curves, and vectors, this line of the element contains the string
  596. ``0''.
  597. .SH NOTES ON COORDINATES
  598. .I gremlin
  599. was designed for
  600. .IR AED s,
  601. and its coordinates reflect the
  602. .I AED
  603. coordinate space.
  604. For vertical pictures, x-values range 116 to 511, and y-values from 0 to
  605. 483.
  606. For horizontal pictures, x-values range from 0 to 511 and y-values range
  607. from 0 to 367.
  608. Although you needn't absolutely stick to this range, you'll get best results
  609. if you at least stay in this vicinity.
  610. Also, point lists are terminated by a point of (-1, -1), so you shouldn't
  611. ever use negative coordinates.
  612. .I gremlin
  613. writes out coordinates using format ``%f1.2''; it's probably a good idea to
  614. use the same format if you want to modify the
  615. .I @g@grn
  616. code.
  617. .SH NOTES ON SUN/X11 COORDINATES
  618. There is no longer a restriction on the range of coordinates used to create
  619. objects in the
  620. .IR SUN / X11
  621. version of
  622. .IR gremlin .
  623. However, files with negative coordinates
  624. .B will
  625. cause problems if displayed on the
  626. .IR AED .
  627. .SH FILES
  628. .Tp \w'@FONTDIR@/devname/DESC'u+3n
  629. .BI @FONTDIR@/dev name /DESC
  630. Device description file for device
  631. .IR name .
  632. .SH SEE ALSO
  633. .BR gremlin (1),
  634. .BR groff (@MAN1EXT@),
  635. .BR @g@pic (@MAN1EXT@),
  636. .BR ideal (1)
  637. .SH HISTORY
  638. .PP
  639. David Slattengren and Barry Roitblat wrote the original Berkeley
  640. .IR @g@grn .
  641. .PP
  642. Daniel Senderowicz and Werner Lemberg modified it for
  643. .IR groff .
  644. .
  645. .cp \n[grn_C]
  646. .
  647. .\" Local Variables:
  648. .\" mode: nroff
  649. .\" End: