/contrib/groff/man/groff_out.man

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 2106 lines · 2101 code · 5 blank · 0 comment · 0 complexity · c58990d4ca4e05ecd2b45f1eb962cb1a MD5 · raw file

  1. '\" e
  2. .\" The above line should force the use of eqn as a preprocessor
  3. .ig
  4. groff_out.5
  5. Last update: 2 Jul 2005
  6. This file is part of groff, the GNU roff type-setting system.
  7. Copyright (C) 1989, 2001, 2002, 2003, 2004, 2005
  8. Free Software Foundation, Inc.
  9. rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
  10. Permission is granted to copy, distribute and/or modify this document
  11. under the terms of the GNU Free Documentation License, Version 1.1 or
  12. any later version published by the Free Software Foundation; with the
  13. Invariant Sections being this .ig-section and AUTHORS, with no
  14. Front-Cover Texts, and with no Back-Cover Texts.
  15. A copy of the Free Documentation License is included as a file called
  16. FDL in the main directory of the groff source package.
  17. ..
  18. .
  19. .\" --------------------------------------------------------------------
  20. .\" Setup
  21. .\" --------------------------------------------------------------------
  22. .
  23. .do nr groff_out_C \n[.C]
  24. .cp 0
  25. .
  26. .mso www.tmac
  27. .
  28. .if n \{\
  29. . mso tty-char.tmac
  30. . ftr CR R
  31. . ftr CI I
  32. . ftr CB B
  33. .\}
  34. .
  35. .if '\*[.T]'dvi' \
  36. . ftr CB CW
  37. .
  38. .if t \{\
  39. .EQ
  40. delim $$
  41. .EN
  42. .\}
  43. .
  44. .\" ----------------- Document configuration
  45. .
  46. .\" Number register to decide whether the commands `{' and `}' are used
  47. .\" 0: disable (actual default); 1: enable
  48. .nr @USE_ENV_STACK 0
  49. .
  50. .ig
  51. Unfortunately, old versions of groff used an illogical position change
  52. after some D\~commands (Dp, DP, Dt). If the number register
  53. @STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
  54. after these commands, otherwise the position is not changed.
  55. ..
  56. .nr @STUPID_DRAWING_POSITIONING 1
  57. .
  58. .\" ----------------- Syntactical definitions
  59. .
  60. .\" comments when escapes are switched off
  61. .de c
  62. ..
  63. .\" Begin of macro definitions
  64. .eo
  65. .
  66. .de Text
  67. . nop \)\$*
  68. ..
  69. .c follow-up line for a .TP header
  70. .de TP+
  71. . br
  72. . ns
  73. . TP \$1
  74. ..
  75. .c a bulleted paragraph
  76. .de Topic
  77. . TP 2m
  78. . nop \[bu]
  79. ..
  80. .de ShellCommand
  81. . br
  82. . IR "shell>" "\h'1m'\f[CB]\$*\f[]\/"
  83. ..
  84. .ec
  85. .\" End of macro definitions
  86. .
  87. .c ----------------- Semantical definitions
  88. .
  89. .nr @maxcolor 65536
  90. .ds @backslash \[rs]\"
  91. .ds @linebreak \f[R]\[la]line_break\[ra]\f[]\"
  92. .
  93. .\" Begin of macro definitions
  94. .eo
  95. .
  96. .c format: .unit <letter> <punctuation>
  97. .de unit
  98. . BR \$@
  99. ..
  100. .c argument in italic with punctuation
  101. .de argument
  102. . if (\n[.$] == 0) \
  103. . return
  104. . IR \$@
  105. ..
  106. .c comma separated list of indexed variables
  107. .de list1..n
  108. . ds @arg1 \$1\"
  109. . nop \c
  110. . ie t \
  111. . nop $\*[@arg1] sub 1$, $\*[@arg1] sub 2$, .\|.\|., $\*[@arg1] sub n$ \c
  112. . el \{\
  113. . IR \*[@arg1]1 ,
  114. . IR \*[@arg1]2 ,
  115. . nop \&...,
  116. . I \*[@arg1]n
  117. . \}
  118. . rm @arg1
  119. ..
  120. .de offset
  121. . if (\n[.$] < 2) \
  122. . ab `.offset' needs at least 2 arguments
  123. . ds @arg1 \$1\"
  124. . ds @arg2 \$2\"
  125. . shift 2
  126. . nop (\f[I]\,\*[@arg1]\/\f[],\ \f[I]\,\*[@arg2]\/\f[])\$*
  127. . rm @arg1
  128. . rm @arg2
  129. ..
  130. .de indexed_offset
  131. . if (\n[.$] < 4) \
  132. . ab `.indexed_offset' needs at least 4 arguments
  133. . ds @arg1 \$1\"
  134. . ds @index1 \$2\"
  135. . ds @arg2 \$3\"
  136. . ds @index2 \$4\"
  137. . shift 4
  138. . ie t \{\
  139. . ie \B'\*[@index1]' \{\
  140. . nop ($\*[@arg1] sub roman \*[@index1]$,\ \c
  141. . \}
  142. . el \{\
  143. . nop ($\*[@arg1] sub \*[@index1]$,\ \c
  144. . \}
  145. . ie \B'\*[@index2]' \{\
  146. . nop $\*[@arg2] sub roman \*[@index2]$)\$* \c
  147. . \}
  148. . el \{\
  149. . nop $\*[@arg2] sub \*[@index2]$)\$* \c
  150. . \}
  151. . \}
  152. . el \{\
  153. . nop (\f[I]\*[@arg1]\*[@index1]\f[],\ \c
  154. . nop \f[I]\*[@arg2]\*[@index2]\f[])\$* \c
  155. . \}
  156. . rm @arg1
  157. . rm @arg2
  158. . rm @index1
  159. . rm @index2
  160. ..
  161. .c format: .command <name> "<arguments>" <punctuation>
  162. .de command
  163. . ds @arg1 \$1\"
  164. . ds @arg2 \$2\"
  165. . shift 2
  166. . IP "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
  167. . rm @arg1
  168. . rm @arg2
  169. ..
  170. .c format: .command+ <name> "<arguments>" <punctuation>
  171. .c continue previous .command heading
  172. .de command+
  173. . ds @arg1 \$1\"
  174. . ds @arg2 \$2\"
  175. . shift 2
  176. . TP+
  177. . Text "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
  178. . rm @arg1
  179. . rm @arg2
  180. ..
  181. .c format: .D-command <subcommand> "<arguments>"
  182. .de D-command
  183. . ds @sub \$1\"
  184. . shift 1
  185. . IP "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\|\*[@linebreak]"
  186. . rm @sub
  187. ..
  188. .c format: .D-command+ <subcommand> "<arguments>"
  189. .c continue previous .D-command heading
  190. .de D-command+
  191. . ds @sub \$1\"
  192. . shift 1
  193. . TP+
  194. . Text "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\*[@linebreak]"
  195. . rm @sub
  196. ..
  197. .de Da-command
  198. . shift 1
  199. . ie t \
  200. . ds @args $h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$\"
  201. . el \
  202. . ds @args \f[I]h1\~v1 h2\~v2\f[]\"
  203. . IP "\f[B]Da\f[]\ \*[@args]\|\*[@linebreak]"
  204. . rm @args
  205. ..
  206. .c graphics command .D with a variable number of arguments
  207. .c format: .D-multiarg <subcommand>
  208. .de D-multiarg
  209. . ds @sub \$1\"
  210. . shift 1
  211. . ie t \{\
  212. . ds @args "$h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$ .\|.\|. \"
  213. . as @args "$h sub n$\~$v sub n$\"
  214. . \}
  215. . el \
  216. . ds @args \f[I]h1\~v1 h2\~v2\f[] ... \f[I]\,hn\~vn\f[]\"
  217. . IP "\f[B]D\*[@sub]\f[]\ \*[@args]\|\*[@linebreak]"
  218. . rm @args
  219. . rm @sub
  220. ..
  221. .c format: .x-command <subname> "<arguments>"
  222. .de x-command
  223. . ds @sub \$1\"
  224. . shift 1
  225. . ds @args
  226. . if (\n[.$] > 0) \
  227. . ds @args \ \f[I]\,\$*\/\f[]\"
  228. . IP "\f[B]x\*[@sub]\f[]\*[@args]\f[]\|\*[@linebreak]"
  229. . rm @sub
  230. . rm @args
  231. ..
  232. .de xsub
  233. . RI "(" "\$1" " control command)"
  234. . br
  235. ..
  236. .ec
  237. .\" End of macro definitions
  238. .
  239. .
  240. .\" --------------------------------------------------------------------
  241. .\" Title
  242. .\" --------------------------------------------------------------------
  243. .
  244. .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
  245. .
  246. .SH NAME
  247. groff_out \- groff intermediate output format
  248. .
  249. .
  250. .\" --------------------------------------------------------------------
  251. .SH DESCRIPTION
  252. .\" --------------------------------------------------------------------
  253. .
  254. This manual page describes the
  255. .I intermediate output
  256. format of the GNU
  257. .BR roff (@MAN7EXT@)
  258. text processing system
  259. .BR groff (@MAN1EXT@).
  260. .
  261. This output is produced by a run of the GNU
  262. .BR @g@troff (@MAN1EXT@)
  263. program.
  264. .
  265. It contains already all device-specific information, but it is not yet
  266. fed into a device postprocessor program.
  267. .
  268. .
  269. .P
  270. As the GNU
  271. .I roff
  272. processor
  273. .BR groff (@MAN1EXT@)
  274. is a wrapper program around
  275. .B @g@troff
  276. that automatically calls a
  277. postprocessor, this output does not show up normally.
  278. .
  279. This is why it is called
  280. .I intermediate
  281. within the
  282. .I groff
  283. .IR system .
  284. .
  285. The
  286. .B groff
  287. program provides the option
  288. .B -Z
  289. to inhibit postprocessing, such that the produced
  290. .I intermediate output
  291. is sent to standard output just like calling
  292. .B @g@troff
  293. manually.
  294. .
  295. .
  296. .P
  297. In this document, the term
  298. .I @g@troff output
  299. describes what is output by the GNU
  300. .B @g@troff
  301. program, while
  302. .I intermediate output
  303. refers to the language that is accepted by the parser that prepares
  304. this output for the postprocessors.
  305. .
  306. This parser is smarter on whitespace and implements obsolete elements
  307. for compatibility, otherwise both formats are the same.
  308. .
  309. Both formats can be viewed directly with
  310. .BR \%gxditview (@MAN1EXT@).
  311. .
  312. .
  313. .P
  314. The main purpose of the
  315. .I intermediate output
  316. concept is to facilitate the development of postprocessors by
  317. providing a common programming interface for all devices.
  318. .
  319. It has a language of its own that is completely different from the
  320. .BR groff (@MAN7EXT@)
  321. language.
  322. .
  323. While the
  324. .I groff
  325. language is a high-level programming language for text processing, the
  326. .I intermediate output
  327. language is a kind of low-level assembler language by specifying all
  328. positions on the page for writing and drawing.
  329. .
  330. .
  331. .P
  332. The
  333. .RI pre- groff
  334. .I roff
  335. versions are denoted as
  336. .I classical
  337. .IR troff .
  338. The
  339. .I intermediate output
  340. produced by
  341. .B groff
  342. is fairly readable, while
  343. .I classical troff
  344. output was hard to understand because of strange habits that are
  345. still supported, but not used any longer by
  346. .I GNU
  347. .IR @g@troff .
  348. .
  349. .
  350. .\" --------------------------------------------------------------------
  351. .SH "LANGUAGE CONCEPTS"
  352. .\" --------------------------------------------------------------------
  353. .
  354. During the run of
  355. .BR @g@troff ,
  356. the
  357. .I roff
  358. input is cracked down to the information on what has to be printed at
  359. what position on the intended device.
  360. .
  361. So the language of the
  362. .I intermediate output
  363. format can be quite small.
  364. .
  365. Its only elements are commands with or without arguments.
  366. .
  367. In this document, the term "command" always refers to the
  368. .I intermediate output
  369. language, never to the
  370. .I roff
  371. language used for document formatting.
  372. .
  373. There are commands for positioning and text writing, for drawing, and
  374. for device controlling.
  375. .
  376. .
  377. .\" --------------------------------------------------------------------
  378. .SS "Separation"
  379. .\" --------------------------------------------------------------------
  380. .
  381. .I Classical troff output
  382. had strange requirements on whitespace.
  383. .
  384. The
  385. .B groff
  386. output parser, however, is smart about whitespace by making it
  387. maximally optional.
  388. .
  389. The whitespace characters, i.e., the
  390. .IR tab ,
  391. .IR space ,
  392. and
  393. .I newline
  394. characters, always have a syntactical meaning.
  395. .
  396. They are never printable because spacing within the output is always
  397. done by positioning commands.
  398. .
  399. .
  400. .P
  401. Any sequence of
  402. .I space
  403. or
  404. .I tab
  405. characters is treated as a single
  406. .I syntactical
  407. .IR space .
  408. .
  409. It separates commands and arguments, but is only required when there
  410. would occur a clashing between the command code and the arguments
  411. without the space.
  412. .
  413. Most often, this happens when variable length command names,
  414. arguments, argument lists, or command clusters meet.
  415. .
  416. Commands and arguments with a known, fixed length need not be
  417. separated by
  418. .I syntactical
  419. .IR space .
  420. .
  421. .
  422. .P
  423. A line break is a syntactical element, too.
  424. .
  425. Every command argument can be followed by whitespace, a comment, or a
  426. newline character.
  427. .
  428. Thus a
  429. .I syntactical line break
  430. is defined to consist of optional
  431. .I syntactical space
  432. that is optionally followed by a comment, and a newline character.
  433. .
  434. .
  435. .P
  436. The normal commands, those for positioning and text, consist of a
  437. single letter taking a fixed number of arguments.
  438. .
  439. For historical reasons, the parser allows to stack such commands on
  440. the same line, but fortunately, in
  441. .I groff intermediate
  442. .IR output ,
  443. every command with at least one argument is followed by a line break,
  444. thus providing excellent readability.
  445. .
  446. .P
  447. The other commands \[em] those for drawing and device controlling \[em]
  448. have a more complicated structure; some recognize long command names,
  449. and some take a variable number of arguments.
  450. .
  451. So all
  452. .B D
  453. and
  454. .B x
  455. commands were designed to request a
  456. .I syntactical line break
  457. after their last argument.
  458. .
  459. Only one command,
  460. .RB ` x\ X '
  461. has an argument that can stretch over several lines, all other
  462. commands must have all of their arguments on the same line as the
  463. command, i.e., the arguments may not be splitted by a line break.
  464. .
  465. .P
  466. Empty lines, i.e., lines containing only space and/or a comment, can
  467. occur everywhere.
  468. .
  469. They are just ignored.
  470. .
  471. .
  472. .\" --------------------------------------------------------------------
  473. .SS "Argument Units"
  474. .\" --------------------------------------------------------------------
  475. .
  476. Some commands take integer arguments that are assumed to represent
  477. values in a measurement unit, but the letter for the corresponding
  478. .I scale indicator
  479. is not written with the output command arguments; see
  480. .BR groff (@MAN7EXT@)
  481. and the
  482. .I groff info file
  483. for more on this topic.
  484. .
  485. Most commands assume the scale indicator\~\c
  486. .unit u ,
  487. the basic unit of the device, some use\~\c
  488. .unit z ,
  489. the
  490. .I scaled point unit
  491. of the device, while others, such as the color commands expect plain
  492. integers.
  493. .
  494. Note that these scale indicators are relative to the chosen device.
  495. .
  496. They are defined by the parameters specified in the device's
  497. .I DESC
  498. file; see
  499. .BR groff_font (@MAN5EXT@).
  500. .
  501. .
  502. .P
  503. Note that single characters can have the eighth bit set, as can the
  504. names of fonts and special characters.
  505. .
  506. The names of characters and fonts can be of arbitrary length.
  507. .
  508. A character that is to be printed will always be in the current font.
  509. .
  510. .
  511. .P
  512. A string argument is always terminated by the next whitespace
  513. character (space, tab, or newline); an embedded
  514. .B #
  515. character is regarded as part of the argument, not as the beginning of
  516. a comment command.
  517. .
  518. An integer argument is already terminated by the next non-digit
  519. character, which then is regarded as the first character of the next
  520. argument or command.
  521. .
  522. .
  523. .\" --------------------------------------------------------------------
  524. .SS "Document Parts"
  525. .\" --------------------------------------------------------------------
  526. A correct
  527. .I intermediate output
  528. document consists of two parts, the
  529. .I prologue
  530. and the
  531. .IR body .
  532. .
  533. .P
  534. The task of the
  535. .I prologue
  536. is to set the general device parameters using three exactly specified
  537. commands.
  538. .
  539. The
  540. .I groff prologue
  541. is guaranteed to consist of the following three lines (in that order):
  542. .RS
  543. .P
  544. .B x\ T
  545. .I device
  546. .br
  547. .B x\ res
  548. .I n\ h\ v
  549. .br
  550. .B x init
  551. .RE
  552. .P
  553. with the arguments set as outlined in the section
  554. .BR "Device Control Commands" .
  555. .
  556. But the parser for the
  557. .I intermediate output
  558. format is able to swallow additional whitespace and comments as well.
  559. .
  560. .
  561. .P
  562. The
  563. .I body
  564. is the main section for processing the document data.
  565. .
  566. Syntactically, it is a sequence of any commands different from the
  567. ones used in the
  568. .IR prologue .
  569. .
  570. Processing is terminated as soon as the first
  571. .B x\ stop
  572. command is encountered; the last line of any
  573. .I groff intermediate output
  574. always contains such a command.
  575. .
  576. .
  577. .P
  578. Semantically, the
  579. .I body
  580. is page oriented.
  581. .
  582. A new page is started by a
  583. .BR p \~command.
  584. .
  585. Positioning, writing, and drawing commands are always done within the
  586. current page, so they cannot occur before the first
  587. .BR p \~command.
  588. .
  589. Absolute positioning (by the
  590. .B H
  591. and
  592. .BR V \~commands)
  593. is done relative to the current page, all other positioning
  594. is done relative to the current location within this page.
  595. .
  596. .
  597. .\" --------------------------------------------------------------------
  598. .SH "COMMAND REFERENCE"
  599. .\" --------------------------------------------------------------------
  600. .
  601. This section describes all
  602. .I intermediate output
  603. commands, the classical commands as well as the
  604. .I groff
  605. extensions.
  606. .
  607. .
  608. .\" --------------------------------------------------------------------
  609. .SS "Comment Command"
  610. .\" --------------------------------------------------------------------
  611. .
  612. .TP
  613. .BI # anything \[la]end_of_line\[ra]
  614. A comment.
  615. .
  616. Ignore any characters from the
  617. .BR # \~\c
  618. character up to the next newline character.
  619. .
  620. .P
  621. This command is the only possibility for commenting in the
  622. .I intermediate
  623. .IR output .
  624. .
  625. Each comment can be preceded by arbitrary
  626. .I syntactical
  627. .IR space ;
  628. every command can be terminated by a comment.
  629. .
  630. .
  631. .\" --------------------------------------------------------------------
  632. .SS "Simple Commands"
  633. .\" --------------------------------------------------------------------
  634. .
  635. The commands in this subsection have a command code consisting of a
  636. single character, taking a fixed number of arguments.
  637. .
  638. Most of them are commands for positioning and text writing.
  639. .
  640. These commands are smart about whitespace.
  641. .
  642. Optionally,
  643. .I syntactical space
  644. can be inserted before, after, and between the command letter and its
  645. arguments.
  646. .
  647. All of these commands are stackable, i.e., they can be preceded by
  648. other simple commands or followed by arbitrary other commands on the
  649. same line.
  650. .
  651. A separating
  652. .I syntactical space
  653. is only necessary when two integer arguments would clash or if the
  654. preceding argument ends with a string argument.
  655. .
  656. .
  657. .if (\n[@USE_ENV_STACK] == 1) \{\
  658. .command {
  659. Open a new environment by copying the actual device configuration data
  660. to the environment stack.
  661. .
  662. The current environment is setup by the device specification and
  663. manipulated by the setting commands.
  664. .
  665. .
  666. .command }
  667. Close the actual environment (opened by a preceding
  668. .BR { \~command)
  669. and restore the previous environment from the environment
  670. stack as the actual device configuration data.
  671. .
  672. \} \" endif @USE_ENV_STACK
  673. .
  674. .
  675. .command C xxx \[la]white_space\[ra]
  676. Print a special groff character named
  677. .argument xxx .
  678. .
  679. The trailing
  680. .I syntactical space
  681. or
  682. .I line break
  683. is necessary to allow character names of arbitrary length.
  684. .
  685. The character is printed at the current print position; the
  686. character's size is read from the font file.
  687. .
  688. The print position is not changed.
  689. .
  690. .
  691. .command c c
  692. Print character\~\c
  693. .argument c
  694. at the current print position;
  695. the character's size is read from the font file.
  696. .
  697. The print position is not changed.
  698. .
  699. .
  700. .command f n
  701. Set font to font number\~\c
  702. .argument n
  703. (a non-negative integer).
  704. .
  705. .
  706. .command H n
  707. Move right to the absolute vertical position\~\c
  708. .argument n
  709. (a non-negative integer in basic units\~\c
  710. .unit u )
  711. relative to left edge of current page.
  712. .
  713. .
  714. .command h n
  715. Move
  716. .argument n
  717. (a non-negative integer) basic units\~\c
  718. .unit u
  719. horizontally to the right.
  720. .
  721. .I [CSTR\~#54]
  722. allows negative values for
  723. .I n
  724. also, but
  725. .I groff
  726. doesn't use this.
  727. .
  728. .
  729. .command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
  730. Set the color for text (glyphs), line drawing, and the outline of
  731. graphic objects using different color schemes; the analoguous command
  732. for the filling color of graphic objects is
  733. .BR DF .
  734. .
  735. The color components are specified as integer arguments between 0 and
  736. \n[@maxcolor].
  737. .
  738. The number of color components and their meaning vary for the
  739. different color schemes.
  740. .
  741. These commands are generated by the
  742. .I groff
  743. escape sequence
  744. .BR \*[@backslash]m .
  745. .
  746. No position changing.
  747. .
  748. These commands are a
  749. .I groff
  750. extension.
  751. .
  752. .
  753. .RS
  754. .
  755. .command mc "cyan magenta yellow"
  756. Set color using the CMY color scheme, having the 3\~color components
  757. cyan, magenta, and yellow.
  758. .
  759. .
  760. .command md
  761. Set color to the default color value
  762. (black in most cases).
  763. .
  764. No component arguments.
  765. .
  766. .
  767. .command mg "gray"
  768. Set color to the shade of gray given by the argument, an integer
  769. between 0 (black) and \n[@maxcolor] (white).
  770. .
  771. .
  772. .command mk "cyan magenta yellow black"
  773. Set color using the CMYK color scheme, having the 4\~color components
  774. cyan, magenta, yellow, and black.
  775. .
  776. .command mr "red green blue"
  777. Set color using the RGB color scheme, having the 3\~color components
  778. red, green, and blue.
  779. .
  780. .RE
  781. .
  782. .
  783. .command N n
  784. Print character with index\~\c
  785. .argument n
  786. (an integer, normally non-negative) of the current font.
  787. .
  788. The print position is not changed.
  789. .
  790. If
  791. .B \-T\~html
  792. is used, negative values are emitted also to indicate an unbreakable space
  793. with given width.
  794. .
  795. For example,
  796. .B N\~-193
  797. represents an unbreakable space which has a width of 193u.
  798. .
  799. This command is a
  800. .I groff
  801. extension.
  802. .
  803. .
  804. .command n b\ a
  805. Inform the device about a line break, but no positioning is done by
  806. this command.
  807. .
  808. In
  809. .I classical
  810. .IR troff ,
  811. the integer arguments
  812. .argument b
  813. and\~\c
  814. .argument a
  815. informed about the space before and after the current line to
  816. make the
  817. .I intermediate output
  818. more human readable without performing any action.
  819. .
  820. In
  821. .IR groff ,
  822. they are just ignored, but they must be provided for compatibility
  823. reasons.
  824. .
  825. .
  826. .command p n
  827. Begin a new page in the outprint.
  828. .
  829. The page number is set to\~\c
  830. .argument n .
  831. .
  832. This page is completely independent of pages formerly processed even
  833. if those have the same page number.
  834. .
  835. The vertical position on the outprint is automatically set to\~0.
  836. .
  837. All positioning, writing, and drawing is always done relative to a
  838. page, so a
  839. .BR p \~command
  840. must be issued before any of these commands.
  841. .
  842. .
  843. .command s n
  844. Set point size to
  845. .argument n
  846. scaled points
  847. (this is unit\~\c
  848. .unit z
  849. in GNU
  850. .BR @g@troff ).
  851. .
  852. .I Classical troff
  853. used the unit
  854. .I points
  855. (\c
  856. .unit p )
  857. instead; see section
  858. .BR COMPATIBILITY .
  859. .
  860. .
  861. .command t xxx \[la]white_space\[ra]
  862. .command+ t "xxx dummy_arg" \[la]white_space\[ra]
  863. Print a word, i.e., a sequence of characters
  864. .argument xxx
  865. terminated by a space character or a line break; an optional second
  866. integer argument is ignored (this allows the formatter to generate
  867. an even number of arguments).
  868. .
  869. The first character should be printed at the current position, the
  870. current horizontal position should then be increased by the width of
  871. the first character, and so on for each character.
  872. .
  873. The widths of the characters are read from the font file, scaled for the
  874. current point size, and rounded to a multiple of the horizontal
  875. resolution.
  876. .
  877. Special characters cannot be printed using this command (use the
  878. .B C
  879. command for named characters).
  880. .
  881. This command is a
  882. .I groff
  883. extension; it is only used for devices whose
  884. .I DESC
  885. file contains the
  886. .B tcommand
  887. keyword; see
  888. .BR groff_font (@MAN5EXT@).
  889. .
  890. .
  891. .command u "n xxx" \[la]white_space\[ra]
  892. Print word with track kerning.
  893. .
  894. This is the same as the
  895. .B t
  896. command except that after printing each character, the current
  897. horizontal position is increased by the sum of the width of that
  898. character and\~\c
  899. .argument n
  900. (an integer in
  901. basic units\~\c
  902. .unit u ).
  903. This command is a
  904. .I groff
  905. extension; it is only used for devices whose
  906. .I DESC
  907. file contains the
  908. .B tcommand
  909. keyword; see
  910. .BR groff_font (@MAN5EXT@).
  911. .
  912. .
  913. .command V n
  914. Move down to the absolute vertical position\~\c
  915. .argument n
  916. (a non-negative integer in basic units\~\c
  917. .unit u )
  918. relative to upper edge of current page.
  919. .
  920. .
  921. .command v n
  922. Move
  923. .argument n
  924. basic units\~\c
  925. .unit u
  926. down
  927. .RI ( n
  928. is a non-negative integer).
  929. .
  930. .I [CSTR\~#54]
  931. allows negative values for
  932. .I n
  933. also, but
  934. .I groff
  935. doesn't use this.
  936. .
  937. .
  938. .command w
  939. Informs about a paddable whitespace to increase readability.
  940. .
  941. The spacing itself must be performed explicitly by a move command.
  942. .
  943. .
  944. .\" --------------------------------------------------------------------
  945. .SS "Graphics Commands"
  946. .\" --------------------------------------------------------------------
  947. .
  948. Each graphics or drawing command in the
  949. .I intermediate output
  950. starts with the letter\~\c
  951. .B D
  952. followed by one or two characters that specify a subcommand; this
  953. is followed by a fixed or variable number of integer arguments that
  954. are separated by a single space character.
  955. .
  956. A
  957. .B D\c
  958. \~command
  959. may not be followed by another command on the same line (apart from a
  960. comment), so each
  961. .B D\c
  962. \~command
  963. is terminated by a
  964. .I syntactical line
  965. .IR break .
  966. .
  967. .
  968. .P
  969. .B @g@troff
  970. output follows the classical spacing rules (no space between command
  971. and subcommand, all arguments are preceded by a single space
  972. character), but the parser allows optional space between the command
  973. letters and makes the space before the first argument optional.
  974. .
  975. As usual, each space can be any sequence of tab and space characters.
  976. .
  977. .
  978. .P
  979. Some graphics commands can take a variable number of arguments.
  980. .
  981. In this case, they are integers representing a size measured in basic
  982. units\~\c
  983. .unit u .
  984. .
  985. The arguments called
  986. .list1..n h
  987. stand for horizontal distances where positive means right, negative
  988. left.
  989. .
  990. The arguments called
  991. .list1..n v
  992. stand for vertical distances where positive means down, negative up.
  993. .
  994. All these distances are offsets relative to the current location.
  995. .
  996. .
  997. .P
  998. Unless indicated otherwise, each graphics command directly corresponds
  999. to a similar
  1000. .I groff
  1001. .B \*[@backslash]D
  1002. escape sequence; see
  1003. .BR groff (@MAN7EXT@).
  1004. .
  1005. .
  1006. .P
  1007. Unknown
  1008. .B D\c
  1009. \~commands are assumed to be device-specific.
  1010. .
  1011. Its arguments are parsed as strings; the whole information is then
  1012. sent to the postprocessor.
  1013. .
  1014. .
  1015. .P
  1016. In the following command reference, the syntax element
  1017. .I \[la]line_break\[ra]
  1018. means a
  1019. .I syntactical line break
  1020. as defined in section
  1021. .BR Separation .
  1022. .
  1023. .
  1024. .D-multiarg ~
  1025. Draw B-spline from current position to offset
  1026. .indexed_offset h 1 v 1 ,
  1027. then to offset
  1028. .indexed_offset h 2 v 2
  1029. if given, etc.\& up to
  1030. .indexed_offset h n v n .
  1031. This command takes a variable number of argument pairs; the current
  1032. position is moved to the terminal point of the drawn curve.
  1033. .
  1034. .
  1035. .Da-command
  1036. Draw arc from current position to
  1037. .indexed_offset h 1 v 1 \|+\|\c
  1038. .indexed_offset h 2 v 2
  1039. with center at
  1040. .indexed_offset h 1 v 1 ;
  1041. then move the current position to the final point of the arc.
  1042. .
  1043. .
  1044. .D-command C d
  1045. .D-command+ C d dummy_arg
  1046. Draw a solid circle using the current fill color with diameter\~\c
  1047. .argument d
  1048. (integer in basic units\~\c
  1049. .unit u )
  1050. with leftmost point at the current position; then move the current
  1051. position to the rightmost point of the circle.
  1052. .
  1053. An optional second integer argument is ignored (this allows to the
  1054. formatter to generate an even number of arguments).
  1055. .
  1056. This command is a
  1057. .I groff
  1058. extension.
  1059. .
  1060. .
  1061. .D-command c d
  1062. Draw circle line with diameter\~\c
  1063. .argument d
  1064. (integer in basic units\~\c
  1065. .unit u )
  1066. with leftmost point at the current position; then move the current
  1067. position to the rightmost point of the circle.
  1068. .
  1069. .
  1070. .D-command E "h v"
  1071. Draw a solid ellipse in the current fill color with a horizontal
  1072. diameter of\~\c
  1073. .argument h
  1074. and a vertical diameter of\~\c
  1075. .argument v
  1076. (both integers in basic units\~\c
  1077. .unit u )
  1078. with the leftmost point at the current position; then move to the
  1079. rightmost point of the ellipse.
  1080. .
  1081. This command is a
  1082. .I groff
  1083. extension.
  1084. .
  1085. .
  1086. .D-command e "h v"
  1087. Draw an outlined ellipse with a horizontal diameter of\~\c
  1088. .argument h
  1089. and a vertical diameter of\~\c
  1090. .argument v
  1091. (both integers in basic units\~\c
  1092. .unit u )
  1093. with the leftmost point at current position; then move to the
  1094. rightmost point of the ellipse.
  1095. .
  1096. .
  1097. .D-command F "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]"
  1098. Set fill color for solid drawing objects using different color
  1099. schemes; the analoguous command for setting the color of text, line
  1100. graphics, and the outline of graphic objects is
  1101. .BR m .
  1102. .
  1103. The color components are specified as integer arguments between 0 and
  1104. \n[@maxcolor].
  1105. .
  1106. The number of color components and their meaning vary for the
  1107. different color schemes.
  1108. .
  1109. These commands are generated by the
  1110. .I groff
  1111. escape sequences
  1112. .B \*[@backslash]D'F\ .\|.\|.'
  1113. and
  1114. .B \*[@backslash]M
  1115. (with no other corresponding graphics commands).
  1116. .
  1117. No position changing.
  1118. .
  1119. This command is a
  1120. .I groff
  1121. extension.
  1122. .
  1123. .
  1124. .RS
  1125. .
  1126. .D-command Fc "cyan magenta yellow"
  1127. Set fill color for solid drawing objects using the CMY color scheme,
  1128. having the 3\~color components cyan, magenta, and yellow.
  1129. .
  1130. .
  1131. .D-command Fd
  1132. Set fill color for solid drawing objects to the default fill color value
  1133. (black in most cases).
  1134. .
  1135. No component arguments.
  1136. .
  1137. .
  1138. .D-command Fg "gray"
  1139. Set fill color for solid drawing objects to the shade of gray given by
  1140. the argument, an integer between 0 (black) and \n[@maxcolor] (white).
  1141. .
  1142. .
  1143. .D-command Fk "cyan magenta yellow black"
  1144. Set fill color for solid drawing objects using the CMYK color scheme,
  1145. having the 4\~color components cyan, magenta, yellow, and black.
  1146. .
  1147. .D-command Fr "red green blue"
  1148. Set fill color for solid drawing objects using the RGB color scheme,
  1149. having the 3\~color components red, green, and blue.
  1150. .
  1151. .RE
  1152. .
  1153. .
  1154. .D-command f n
  1155. The argument
  1156. .argument n
  1157. must be an integer in the range -32767 to 32767.
  1158. .
  1159. .RS
  1160. .TP
  1161. .RI "0 \[<=] " n " \[<=] 1000"
  1162. Set the color for filling solid drawing objects to a shade of gray,
  1163. where 0 corresponds to solid white, 1000 (the default) to solid black,
  1164. and values in between to intermediate shades of gray; this is
  1165. obsoleted by command
  1166. .BR DFg .
  1167. .
  1168. .TP
  1169. .IR n " < 0 or " n " > 1000"
  1170. Set the filling color to the color that is currently being used for
  1171. the text and the outline, see command
  1172. .BR m .
  1173. For example, the command sequence
  1174. .
  1175. .nf
  1176. .ft CB
  1177. .RS
  1178. .RS
  1179. mg 0 0 \n[@maxcolor]
  1180. Df -1
  1181. .RE
  1182. .ft
  1183. .fi
  1184. .
  1185. sets all colors to blue.
  1186. .RE
  1187. .
  1188. .
  1189. .P
  1190. No position changing.
  1191. .
  1192. This command is a
  1193. .I groff
  1194. extension.
  1195. .
  1196. .RE
  1197. .
  1198. .
  1199. .D-command l "h v"
  1200. Draw line from current position to offset
  1201. .offset h v
  1202. (integers in basic units\~\c
  1203. .unit u );
  1204. then set current position to the end of the drawn line.
  1205. .
  1206. .
  1207. .D-multiarg p
  1208. Draw a polygon line from current position to offset
  1209. .offset h1 v1 ,
  1210. from there to offset
  1211. .offset h2 v2 ,
  1212. etc.\& up to offset
  1213. .offset hn vn ,
  1214. and from there back to the starting position.
  1215. .
  1216. .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
  1217. For historical reasons, the position is changed by adding the sum of
  1218. all arguments with odd index to the actual horizontal position and the
  1219. even ones to the vertical position.
  1220. .
  1221. Although this doesn't make sense it is kept for compatibility.
  1222. .
  1223. \}
  1224. .el \{\
  1225. As the polygon is closed, the end of drawing is the starting point, so
  1226. the position doesn't change.
  1227. \}
  1228. .
  1229. This command is a
  1230. .I groff
  1231. extension.
  1232. .
  1233. .
  1234. .D-multiarg P
  1235. The same macro as the corresponding
  1236. .B Dp
  1237. command with the same arguments, but draws a solid polygon in the
  1238. current fill color rather than an outlined polygon.
  1239. .
  1240. .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
  1241. The position is changed in the same way as with
  1242. .BR Dp .
  1243. \}
  1244. .el \
  1245. No position changing.
  1246. .
  1247. This command is a
  1248. .I groff
  1249. extension.
  1250. .
  1251. .
  1252. .D-command t n
  1253. Set the current line thickness to\~\c
  1254. .argument n
  1255. (an integer in basic units\~\c
  1256. .unit u )
  1257. if
  1258. .argument n >0;
  1259. if
  1260. .argument n =0
  1261. select the smallest available line thickness; if
  1262. .argument n <0
  1263. set the line thickness proportional to the point size (this is the
  1264. default before the first
  1265. .B Dt
  1266. command was specified).
  1267. .
  1268. .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
  1269. For historical reasons, the horizontal position is changed by adding
  1270. the argument to the actual horizontal position, while the vertical
  1271. position is not changed.
  1272. .
  1273. Although this doesn't make sense it is kept for compatibility.
  1274. .
  1275. \}
  1276. .el \
  1277. No position changing.
  1278. .
  1279. This command is a
  1280. .I groff
  1281. extension.
  1282. .
  1283. .
  1284. .\" --------------------------------------------------------------------
  1285. .SS "Device Control Commands"
  1286. .\" --------------------------------------------------------------------
  1287. .
  1288. Each device control command starts with the letter
  1289. .B x
  1290. followed by a space character (optional or arbitrary space/\:tab in
  1291. .IR groff )
  1292. and a subcommand letter or word; each argument (if any) must be
  1293. preceded by a
  1294. .I syntactical
  1295. .IR space .
  1296. .
  1297. All
  1298. .B x
  1299. commands are terminated by a
  1300. .IR "syntactical line break" ;
  1301. no device control command can be followed by another command on the same
  1302. line (except a comment).
  1303. .
  1304. .P
  1305. The subcommand is basically a single letter, but to increase
  1306. readability, it can be written as a word, i.e., an arbitrary sequence
  1307. of characters terminated by the next tab, space, or newline character.
  1308. .
  1309. All characters of the subcommand word but the first are simply ignored.
  1310. .
  1311. For example,
  1312. .B @g@troff
  1313. outputs the initialization command
  1314. .B x\ i
  1315. as
  1316. .B x\ init
  1317. and the resolution command
  1318. .B x\ r
  1319. as
  1320. .BR "x\ res" .
  1321. .
  1322. But writings like
  1323. .B x\ i_like_groff
  1324. and
  1325. .B x\ roff_is_groff
  1326. resp.\& are accepted as well to mean the same commands.
  1327. .
  1328. .P
  1329. In the following, the syntax element
  1330. .I \[la]line_break\[ra]
  1331. means a
  1332. .I syntactical line break
  1333. as defined in section
  1334. .BR Separation .
  1335. .
  1336. .x-command F name
  1337. .xsub Filename
  1338. Use
  1339. .argument name
  1340. as the intended name for the current file in error reports.
  1341. .
  1342. This is useful for remembering the original file name when
  1343. .B groff
  1344. uses an internal piping mechanism.
  1345. .
  1346. The input file is not changed by this command.
  1347. .
  1348. This command is a
  1349. .I groff
  1350. extension.
  1351. .
  1352. .
  1353. .x-command f "n\ s"
  1354. .xsub font
  1355. Mount font position\~\c
  1356. .argument n
  1357. (a non-negative integer) with font named\~\c
  1358. .argument s
  1359. (a text word),
  1360. cf.
  1361. .BR groff_font (@MAN5EXT@).
  1362. .
  1363. .
  1364. .x-command H n
  1365. .xsub Height
  1366. Set character height to\~\c
  1367. .argument n
  1368. (a positive integer in scaled points\~\c
  1369. .unit z ).
  1370. .
  1371. .I Classical troff
  1372. used the unit points (\c
  1373. .unit p )
  1374. instead; see section
  1375. .BR COMPATIBILITY .
  1376. .
  1377. .
  1378. .x-command i
  1379. .xsub init
  1380. Initialize device.
  1381. .
  1382. This is the third command of the
  1383. .IR prologue .
  1384. .
  1385. .
  1386. .x-command p
  1387. .xsub pause
  1388. Parsed but ignored.
  1389. .
  1390. The classical documentation reads
  1391. .I pause device, can be
  1392. .IR restarted .
  1393. .
  1394. .
  1395. .x-command r "n\ h\ v"
  1396. .xsub resolution
  1397. Resolution is\~\c
  1398. .argument n ,
  1399. while
  1400. .argument h
  1401. is the minimal horizontal motion, and
  1402. .argument v
  1403. the minimal vertical motion possible with this device; all arguments
  1404. are positive integers in basic units\~\c
  1405. .unit u
  1406. per inch.
  1407. .
  1408. This is the second command of the
  1409. .IR prologue .
  1410. .
  1411. .
  1412. .x-command S n
  1413. .xsub Slant
  1414. Set slant to\~\c
  1415. .argument n
  1416. degrees (an integer in basic units\~\c
  1417. .unit u ).
  1418. .
  1419. .
  1420. .x-command s
  1421. .xsub stop
  1422. Terminates the processing of the current file; issued as the last
  1423. command of any
  1424. .I intermediate @g@troff
  1425. .IR output .
  1426. .
  1427. .
  1428. .x-command t
  1429. .xsub trailer
  1430. Generate trailer information, if any.
  1431. .
  1432. In
  1433. .BR groff ,
  1434. this is actually just ignored.
  1435. .
  1436. .
  1437. .x-command T xxx
  1438. .xsub Typesetter
  1439. Set name of device to word
  1440. .argument xxx ,
  1441. a sequence of characters ended by the next whitespace character.
  1442. .
  1443. The possible device names coincide with those from the groff
  1444. .B -T
  1445. option.
  1446. .
  1447. This is the first command of the
  1448. .IR prologue .
  1449. .
  1450. .
  1451. .x-command u n
  1452. .xsub underline
  1453. Configure underlining of spaces.
  1454. .
  1455. If
  1456. .argument n
  1457. is\~1, start underlining of spaces;
  1458. if
  1459. .argument n
  1460. is\~0, stop underlining of spaces.
  1461. .
  1462. This is needed for the
  1463. .B cu
  1464. request in
  1465. .B @g@nroff
  1466. mode and is ignored otherwise.
  1467. .
  1468. This command is a
  1469. .I groff
  1470. extension.
  1471. .
  1472. .
  1473. .x-command X anything
  1474. .xsub X-escape
  1475. Send string
  1476. .argument anything
  1477. uninterpreted to the device.
  1478. .
  1479. If the line following this command starts with a
  1480. .B +
  1481. character this line is interpreted as a continuation line in the
  1482. following sense.
  1483. .
  1484. The
  1485. .B +
  1486. is ignored, but a newline character is sent instead to the device, the
  1487. rest of the line is sent uninterpreted.
  1488. .
  1489. The same applies to all following lines until the first character of a
  1490. line is not a
  1491. .B +
  1492. character.
  1493. .
  1494. This command is generated by the
  1495. .I groff
  1496. escape sequence
  1497. .BR \*[@backslash]X .
  1498. .
  1499. The line-continuing feature is a
  1500. .I groff
  1501. extension.
  1502. .
  1503. .
  1504. .\" --------------------------------------------------------------------
  1505. .SS "Obsolete Command"
  1506. .\" --------------------------------------------------------------------
  1507. .
  1508. In
  1509. .I classical troff
  1510. output, the writing of a single character was mostly done by a very
  1511. strange command that combined a horizontal move and the printing of a
  1512. character.
  1513. .
  1514. It didn't have a command code, but is represented by a 3-character
  1515. argument consisting of exactly 2\~digits and a character.
  1516. .
  1517. .TP
  1518. .argument ddc
  1519. Move right
  1520. .argument dd
  1521. (exactly two decimal digits) basic units\~\c
  1522. .unit u ,
  1523. then print character\~\c
  1524. .argument c .
  1525. .
  1526. .
  1527. .RS
  1528. .P
  1529. In
  1530. .IR groff ,
  1531. arbitrary
  1532. .I syntactical space
  1533. around and within this command is allowed to be added.
  1534. .
  1535. Only when a preceding command on the same line ends with an argument
  1536. of variable length a separating space is obligatory.
  1537. .
  1538. In
  1539. .I classical
  1540. .IR troff ,
  1541. large clusters of these and other commands were used, mostly without
  1542. spaces; this made such output almost unreadable.
  1543. .
  1544. .RE
  1545. .
  1546. .
  1547. .P
  1548. For modern high-resolution devices, this command does not make sense
  1549. because the width of the characters can become much larger than two
  1550. decimal digits.
  1551. .
  1552. In
  1553. .BR groff ,
  1554. this is only used for the devices
  1555. .BR X75 ,
  1556. .BR X75-12 ,
  1557. .BR X100 ,
  1558. and
  1559. .BR X100-12 .
  1560. .
  1561. For other devices,
  1562. the commands
  1563. .B t
  1564. and\~\c
  1565. .B u
  1566. provide a better functionality.
  1567. .
  1568. .
  1569. .\" --------------------------------------------------------------------
  1570. .SH "POSTPROCESSING"
  1571. .\" --------------------------------------------------------------------
  1572. .
  1573. The
  1574. .I roff
  1575. postprocessors are programs that have the task to translate the
  1576. .I intermediate output
  1577. into actions that are sent to a device.
  1578. .
  1579. A device can be some piece of hardware such as a printer, or a software
  1580. file format suitable for graphical or text processing.
  1581. .
  1582. The
  1583. .I groff
  1584. system provides powerful means that make the programming of such
  1585. postprocessors an easy task.
  1586. .P
  1587. There is a library function that parses the
  1588. .I intermediate output
  1589. and sends the information obtained to the device via methods of a
  1590. class with a common interface for each device.
  1591. .
  1592. So a
  1593. .I groff
  1594. postprocessor must only redefine the methods of this class.
  1595. .
  1596. For details, see the reference in section
  1597. .BR FILES .
  1598. .
  1599. .
  1600. .\" --------------------------------------------------------------------
  1601. .SH "EXAMPLES"
  1602. .\" --------------------------------------------------------------------
  1603. .
  1604. This section presents the
  1605. .I intermediate output
  1606. generated from the same input for three different devices.
  1607. .
  1608. The input is the sentence
  1609. .I hell world
  1610. fed into
  1611. .B groff
  1612. on the command line.
  1613. .
  1614. .
  1615. .Topic
  1616. High-resolution device
  1617. .I ps
  1618. .
  1619. .
  1620. .RS
  1621. .P
  1622. .ShellCommand echo "hell world" | groff -Z -T ps
  1623. .
  1624. .
  1625. .P
  1626. .nf
  1627. .ft CB
  1628. x T ps
  1629. x res 72000 1 1
  1630. x init
  1631. p1
  1632. x font 5 TR
  1633. f5
  1634. s10000
  1635. V12000
  1636. H72000
  1637. thell
  1638. wh2500
  1639. tw
  1640. H96620
  1641. torld
  1642. n12000 0
  1643. x trailer
  1644. V792000
  1645. x stop
  1646. .ft P
  1647. .fi
  1648. .RE
  1649. .
  1650. .
  1651. .P
  1652. This output can be fed into the postprocessor
  1653. .BR grops (@MAN1EXT@)
  1654. to get its representation as a PostScript file.
  1655. .
  1656. .
  1657. .Topic
  1658. Low-resolution device
  1659. .I latin1
  1660. .
  1661. .
  1662. .RS
  1663. .P
  1664. This is similar to the high-resolution device except that the
  1665. positioning is done at a minor scale.
  1666. .
  1667. Some comments (lines starting with
  1668. .IR # )
  1669. were added for clarification; they were not generated by the
  1670. formatter.
  1671. .
  1672. .
  1673. .P
  1674. .ShellCommand echo "hell world" | groff -Z -T latin1
  1675. .
  1676. .
  1677. .P
  1678. .nf
  1679. .I "# prologue"
  1680. .ft CB
  1681. x T latin1
  1682. x res 240 24 40
  1683. x init
  1684. .I "# begin a new page"
  1685. .ft CB
  1686. p1
  1687. .I "# font setup"
  1688. .ft CB
  1689. x font 1 R
  1690. f1
  1691. s10
  1692. .I "# initial positioning on the page"
  1693. .ft CB
  1694. V40
  1695. H0
  1696. .I "# write text `hell'"
  1697. .ft CB
  1698. thell
  1699. .I "# inform about a space, and do it by a horizontal jump"
  1700. .ft CB
  1701. wh24
  1702. .I "# write text `world'"
  1703. .ft CB
  1704. tworld
  1705. .I "# announce line break, but do nothing because ..."
  1706. .ft CB
  1707. n40 0
  1708. .I "# ... the end of the document has been reached"
  1709. .ft CB
  1710. x trailer
  1711. V2640
  1712. x stop
  1713. .ft P
  1714. .fi
  1715. .RE
  1716. .
  1717. .
  1718. .P
  1719. This output can be fed into the postprocessor
  1720. .BR grotty (@MAN1EXT@)
  1721. to get a formatted text document.
  1722. .
  1723. .
  1724. .Topic
  1725. Classical style output
  1726. .
  1727. .
  1728. .RS
  1729. .P
  1730. As a computer monitor has a very low resolution compared to modern
  1731. printers the
  1732. .I intermediate output
  1733. for the X\~devices can use the jump-and-write command with its 2-digit
  1734. displacements.
  1735. .
  1736. .
  1737. .P
  1738. .ShellCommand echo "hell world" | groff -Z -T X100
  1739. .
  1740. .
  1741. .P
  1742. .nf
  1743. .ft CB
  1744. x T X100
  1745. x res 100 1 1
  1746. x init
  1747. p1
  1748. x font 5 TR
  1749. f5
  1750. s10
  1751. V16
  1752. H100
  1753. .I "# write text with old-style jump-and-write command"
  1754. .ft CB
  1755. ch07e07l03lw06w11o07r05l03dh7
  1756. n16 0
  1757. x trailer
  1758. V1100
  1759. x stop
  1760. .ft P
  1761. .fi
  1762. .RE
  1763. .
  1764. .
  1765. .P
  1766. This output can be fed into the postprocessor
  1767. .BR \%xditview (1x)
  1768. or
  1769. .BR \%gxditview (@MAN1EXT@)
  1770. for displaying in\~X.
  1771. .
  1772. .
  1773. .P
  1774. Due to the obsolete jump-and-write command, the text clusters in the
  1775. classical output are almost unreadable.
  1776. .
  1777. .
  1778. .\" --------------------------------------------------------------------
  1779. .SH "COMPATIBILITY"
  1780. .\" --------------------------------------------------------------------
  1781. .
  1782. The
  1783. .I intermediate output
  1784. language of the
  1785. .I classical troff
  1786. was first documented in
  1787. .IR [CSTR\~#97] .
  1788. .
  1789. The
  1790. .I groff intermediate output
  1791. format is compatible with this specification except for the following
  1792. features.
  1793. .
  1794. .
  1795. .Topic
  1796. The classical quasi device independence is not yet implemented.
  1797. .
  1798. .
  1799. .Topic
  1800. The old hardware was very different from what we use today.
  1801. .
  1802. So the
  1803. .I groff
  1804. devices are also fundamentally different from the ones in
  1805. .I classical
  1806. .IR troff .
  1807. .
  1808. For example, the classical PostScript device was called
  1809. .I post
  1810. and had a resolution of 720 units per inch,
  1811. while
  1812. .IR groff 's
  1813. .I ps
  1814. device has a resolution of 72000 units per inch.
  1815. .
  1816. Maybe, by implementing some rescaling mechanism similar to the
  1817. classical quasi device independence, these could be integrated into
  1818. modern
  1819. .IR groff .
  1820. .
  1821. .
  1822. .Topic
  1823. The B-spline command
  1824. .B D~
  1825. is correctly handled by the
  1826. .I intermediate output
  1827. parser, but the drawing routines aren't implemented in some of the
  1828. postprocessor programs.
  1829. .
  1830. .
  1831. .Topic
  1832. The argument of the commands
  1833. .B s
  1834. and
  1835. .B x H
  1836. has the implicit unit scaled point\~\c
  1837. .unit z
  1838. in
  1839. .IR groff ,
  1840. while
  1841. .I classical troff
  1842. had point (\c
  1843. .unit p ).
  1844. .
  1845. This isn't an incompatibility, but a compatible extension, for both
  1846. units coincide for all devices without a
  1847. .I sizescale
  1848. parameter, including all classical and the
  1849. .I groff
  1850. text devices.
  1851. .
  1852. The few
  1853. .I groff
  1854. devices with a sizescale parameter either did not exist, had a
  1855. different name, or seem to have had a different resolution.
  1856. .
  1857. So conflicts with classical devices are very unlikely.
  1858. .
  1859. .
  1860. .ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\
  1861. .Topic
  1862. The position changing after the commands
  1863. .BR Dp ,
  1864. .BR DP ,
  1865. and
  1866. .B Dt
  1867. is illogical, but as old versions of groff used this feature it is
  1868. kept for compatibility reasons.
  1869. .\} \" @STUPID_DRAWING_POSITIONING
  1870. .el \{\
  1871. .Topic
  1872. Temporarily, there existed some confusion on the positioning after the
  1873. .B D
  1874. commands that are
  1875. .I groff
  1876. extensions.
  1877. .
  1878. This has been clarified by establishing the classical rule for all
  1879. groff drawing commands:
  1880. .
  1881. .
  1882. .RS
  1883. .P
  1884. .ft I
  1885. The position after a graphic object has been drawn is at its end;
  1886. for circles and ellipses, the "end" is at the right side.
  1887. .ft
  1888. .RE
  1889. .
  1890. .
  1891. .P
  1892. From this, the positionings specified for the drawing commands above
  1893. follow quite naturally.
  1894. .\} \" @STUPID_DRAWING_POSITIONING
  1895. .
  1896. .P
  1897. The differences between
  1898. .I groff
  1899. and
  1900. .I classical troff
  1901. are documented in
  1902. .BR groff_diff (@MAN7EXT@).
  1903. .
  1904. .
  1905. .\" --------------------------------------------------------------------
  1906. .SH "FILES"
  1907. .\" --------------------------------------------------------------------
  1908. .
  1909. .TP
  1910. .BI @FONTDIR@/dev name /DESC
  1911. Device description file for device
  1912. .IR name .
  1913. .
  1914. .TP
  1915. .IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
  1916. Defines the parser and postprocessor for the
  1917. .I intermediate
  1918. .IR output .
  1919. .
  1920. It is located relative to the top directory of the
  1921. .I groff
  1922. source tree, e.g.
  1923. .IR @GROFFSRCDIR@ .
  1924. .
  1925. This parser is the definitive specification of the
  1926. .I groff intermediate output
  1927. format.
  1928. .
  1929. .
  1930. .\" --------------------------------------------------------------------
  1931. .SH "SEE ALSO"
  1932. .\" --------------------------------------------------------------------
  1933. .
  1934. A reference like
  1935. .BR groff (@MAN7EXT@)
  1936. refers to a manual page; here
  1937. .B groff
  1938. in section\~\c
  1939. .I @MAN7EXT@
  1940. of the man-page documentation system.
  1941. .
  1942. To read the example, look up section\~@MAN7EXT@ in your desktop help
  1943. system or call from the shell prompt
  1944. .
  1945. .
  1946. .RS
  1947. .P
  1948. .ShellCommand man @MAN7EXT@ groff
  1949. .RE
  1950. .
  1951. .
  1952. .P
  1953. For more details, see
  1954. .BR man (1).
  1955. .
  1956. .
  1957. .TP
  1958. .BR groff (@MAN1EXT@)
  1959. option
  1960. .B -Z
  1961. and further readings on groff.
  1962. .
  1963. .
  1964. .TP
  1965. .BR groff (@MAN7EXT@)
  1966. for details of the
  1967. .I groff
  1968. language such as numerical units and escape sequences.
  1969. .
  1970. .
  1971. .TP
  1972. .BR groff_font (@MAN5EXT@)
  1973. for details on the device scaling parameters of the
  1974. .B DESC
  1975. file.
  1976. .
  1977. .
  1978. .TP
  1979. .BR @g@troff (@MAN1EXT@)
  1980. generates the device-independent intermediate output.
  1981. .
  1982. .
  1983. .TP
  1984. .BR roff (@MAN7EXT@)
  1985. for historical aspects and the general structure of roff systems.
  1986. .
  1987. .
  1988. .TP
  1989. .BR groff_diff (@MAN7EXT@)
  1990. The differences between the intermediate output in groff and classical
  1991. troff.
  1992. .
  1993. .
  1994. .TP
  1995. .BR gxditview (@MAN1EXT@)
  1996. Viewer for the
  1997. .I intermediate
  1998. .IR output .
  1999. .
  2000. .
  2001. .P
  2002. .BR \%grodvi (@MAN1EXT@),
  2003. .BR \%grohtml (@MAN1EXT@),
  2004. .BR \%grolbp (@MAN1EXT@),
  2005. .BR \%grolj4 (@MAN1EXT@),
  2006. .BR \%grops (@MAN1EXT@),
  2007. .BR \%grotty (@MAN1EXT@)
  2008. .br
  2009. .RS
  2010. the groff postprocessor programs.
  2011. .RE
  2012. .
  2013. .
  2014. .P
  2015. For a treatment of all aspects of the groff system within a single
  2016. document, see the
  2017. .I groff info
  2018. .IR file .
  2019. .
  2020. It can be read within the integrated help systems, within
  2021. .BR emacs (1)
  2022. or from the shell prompt by
  2023. .
  2024. .RS
  2025. .ShellCommand info groff
  2026. .RE
  2027. .
  2028. .
  2029. .P
  2030. The
  2031. .I classical troff output language
  2032. is described in two AT&T Bell Labs CSTR documents available on-line at
  2033. .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \
  2034. "Bell Labs CSTR site" .
  2035. .
  2036. .
  2037. .TP
  2038. .I [CSTR #97]
  2039. .I A Typesetter-independent TROFF
  2040. by
  2041. .I Brian Kernighan
  2042. is the original and most concise documentation on the output language;
  2043. see
  2044. .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 .
  2045. .
  2046. .
  2047. .TP
  2048. .I [CSTR\~#54]
  2049. The 1992 revision of the
  2050. .I Nroff/\:Troff User's Manual
  2051. by
  2052. .I J.\& F.\& Osanna
  2053. and
  2054. .I Brian Kernighan
  2055. isn't as concise as
  2056. .I [CSTR\~#97]
  2057. regarding the output language; see
  2058. .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 .
  2059. .
  2060. .
  2061. .\" --------------------------------------------------------------------
  2062. .SH "AUTHORS"
  2063. .\" --------------------------------------------------------------------
  2064. .
  2065. Copyright (C) 1989, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
  2066. .
  2067. .
  2068. .P
  2069. This document is distributed under the terms of the FDL (GNU Free
  2070. Documentation License) version 1.1 or later.
  2071. .
  2072. You should have received a copy of the FDL with this package; it is also
  2073. available on-line at the
  2074. .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
  2075. .
  2076. .
  2077. .P
  2078. This document is part of
  2079. .IR groff ,
  2080. the GNU
  2081. .I roff
  2082. distribution.
  2083. .
  2084. It is based on a former version \- published under the GPL \- that
  2085. described only parts of the
  2086. .I groff
  2087. extensions of the output language.
  2088. .
  2089. It has been rewritten 2002 by \m[blue]Bernd Warken\m[] and is
  2090. maintained by
  2091. .MTO wl@gnu.org "Werner Lemberg" .
  2092. .
  2093. .cp \n[groff_out_C]
  2094. .
  2095. .\" --------------------------------------------------------------------
  2096. .\" Emacs settings
  2097. .\" --------------------------------------------------------------------
  2098. .\"
  2099. .\" Local Variables:
  2100. .\" mode: nroff
  2101. .\" End: