logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

roff.7 (63448B)


  1. .\" $Id: roff.7,v 1.116 2021/09/18 12:23:06 schwarze Exp $
  2. .\"
  3. .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
  4. .\" Copyright (c) 2010-2019 Ingo Schwarze <schwarze@openbsd.org>
  5. .\"
  6. .\" Permission to use, copy, modify, and distribute this software for any
  7. .\" purpose with or without fee is hereby granted, provided that the above
  8. .\" copyright notice and this permission notice appear in all copies.
  9. .\"
  10. .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11. .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12. .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13. .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14. .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15. .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17. .\"
  18. .Dd $Mdocdate: September 18 2021 $
  19. .Dt ROFF 7
  20. .Os
  21. .Sh NAME
  22. .Nm roff
  23. .Nd roff language reference for mandoc
  24. .Sh DESCRIPTION
  25. The
  26. .Nm roff
  27. language is a general purpose text formatting language.
  28. Since traditional implementations of the
  29. .Xr mdoc 7
  30. and
  31. .Xr man 7
  32. manual formatting languages are based on it,
  33. many real-world manuals use small numbers of
  34. .Nm
  35. requests and escape sequences intermixed with their
  36. .Xr mdoc 7
  37. or
  38. .Xr man 7
  39. code.
  40. To properly format such manuals, the
  41. .Xr mandoc 1
  42. utility supports a subset of
  43. .Nm
  44. requests and escapes.
  45. Even though this manual page lists all
  46. .Nm
  47. requests and escape sequences, it only contains partial information
  48. about requests not supported by
  49. .Xr mandoc 1
  50. and about language features that do not matter for manual pages.
  51. For complete
  52. .Nm
  53. manuals, consult the
  54. .Sx SEE ALSO
  55. section.
  56. .Pp
  57. Input lines beginning with the control character
  58. .Sq \&.
  59. are parsed for requests and macros.
  60. Such lines are called
  61. .Dq request lines
  62. or
  63. .Dq macro lines ,
  64. respectively.
  65. Requests change the processing state and manipulate the formatting;
  66. some macros also define the document structure and produce formatted
  67. output.
  68. The single quote
  69. .Pq Qq \(aq
  70. is accepted as an alternative control character,
  71. treated by
  72. .Xr mandoc 1
  73. just like
  74. .Ql \&.
  75. .Pp
  76. Lines not beginning with control characters are called
  77. .Dq text lines .
  78. They provide free-form text to be printed; the formatting of the text
  79. depends on the respective processing context.
  80. .Sh LANGUAGE SYNTAX
  81. .Nm
  82. documents may contain only graphable 7-bit ASCII characters, the space
  83. character, and, in certain circumstances, the tab character.
  84. The backslash character
  85. .Sq \e
  86. indicates the start of an escape sequence, used for example for
  87. .Sx Comments
  88. and
  89. .Sx Special Characters .
  90. For a complete listing of escape sequences, consult the
  91. .Sx ESCAPE SEQUENCE REFERENCE
  92. below.
  93. .Ss Comments
  94. Text following an escaped double-quote
  95. .Sq \e\(dq ,
  96. whether in a request, macro, or text line, is ignored to the end of the line.
  97. A request line beginning with a control character and comment escape
  98. .Sq \&.\e\(dq
  99. is also ignored.
  100. Furthermore, request lines with only a control character and optional
  101. trailing whitespace are stripped from input.
  102. .Pp
  103. Examples:
  104. .Bd -literal -offset indent -compact
  105. \&.\e\(dq This is a comment line.
  106. \&.\e\(dq The next line is ignored:
  107. \&.
  108. \&.Sh EXAMPLES \e\(dq This is a comment, too.
  109. \&example text \e\(dq And so is this.
  110. .Ed
  111. .Ss Special Characters
  112. Special characters are used to encode special glyphs and are rendered
  113. differently across output media.
  114. They may occur in request, macro, and text lines.
  115. Sequences begin with the escape character
  116. .Sq \e
  117. followed by either an open-parenthesis
  118. .Sq \&(
  119. for two-character sequences; an open-bracket
  120. .Sq \&[
  121. for n-character sequences (terminated at a close-bracket
  122. .Sq \&] ) ;
  123. or a single one character sequence.
  124. .Pp
  125. Examples:
  126. .Bl -tag -width Ds -offset indent -compact
  127. .It Li \e(em
  128. Two-letter em dash escape.
  129. .It Li \ee
  130. One-letter backslash escape.
  131. .El
  132. .Pp
  133. See
  134. .Xr mandoc_char 7
  135. for a complete list.
  136. .Ss Font Selection
  137. In
  138. .Xr mdoc 7
  139. and
  140. .Xr man 7
  141. documents, fonts are usually selected with macros.
  142. The
  143. .Ic \ef
  144. escape sequence and the
  145. .Ic \&ft
  146. request can be used to manually change the font,
  147. but this is not recommended in
  148. .Xr mdoc 7
  149. documents.
  150. Such manual font changes are overridden by many subsequent macros.
  151. .Pp
  152. The following fonts are supported:
  153. .Pp
  154. .Bl -tag -width CW -offset indent -compact
  155. .It Cm B
  156. Bold font.
  157. .It Cm BI
  158. A font that is both bold and italic.
  159. .It Cm CB
  160. Bold constant width font.
  161. Same as
  162. .Cm B
  163. in terminal output.
  164. .It Cm CI
  165. Italic constant width font.
  166. Same as
  167. .Cm I
  168. in terminal output.
  169. .It Cm CR
  170. Regular constant width font.
  171. Same as
  172. .Cm R
  173. in terminal output.
  174. .It Cm CW
  175. An alias for
  176. .Cm CR .
  177. .It Cm I
  178. Italic font.
  179. .It Cm P
  180. Return to the previous font.
  181. If a macro caused a font change since the last
  182. .Ic \ef
  183. eascape sequence or
  184. .Ic \&ft
  185. request, this returns to the font before the last font change in
  186. the macro rather than to the font before the last manual font change.
  187. .It Cm R
  188. Roman font.
  189. This is the default font.
  190. .It Cm 1
  191. An alias for
  192. .Cm R .
  193. .It Cm 2
  194. An alias for
  195. .Cm I .
  196. .It Cm 3
  197. An alias for
  198. .Cm B .
  199. .It Cm 4
  200. An alias for
  201. .Cm BI .
  202. .El
  203. .Pp
  204. Examples:
  205. .Bl -tag -width Ds -offset indent -compact
  206. .It Li \efBbold\efR
  207. Write in \fBbold\fP, then switch to regular font mode.
  208. .It Li \efIitalic\efP
  209. Write in \fIitalic\fP, then return to previous font mode.
  210. .It Li \ef(BIbold italic\efP
  211. Write in \f(BIbold italic\fP, then return to previous font mode.
  212. .El
  213. .Ss Whitespace
  214. Whitespace consists of the space character.
  215. In text lines, whitespace is preserved within a line.
  216. In request and macro lines, whitespace delimits arguments and is discarded.
  217. .Pp
  218. Unescaped trailing spaces are stripped from text line input unless in a
  219. literal context.
  220. In general, trailing whitespace on any input line is discouraged for
  221. reasons of portability.
  222. In the rare case that a space character is needed at the end of an
  223. input line, it may be forced by
  224. .Sq \e\ \e& .
  225. .Pp
  226. Literal space characters can be produced in the output
  227. using escape sequences.
  228. In macro lines, they can also be included in arguments using quotation; see
  229. .Sx MACRO SYNTAX
  230. for details.
  231. .Pp
  232. Blank text lines, which may include whitespace, are only permitted
  233. within literal contexts.
  234. If the first character of a text line is a space, that line is printed
  235. with a leading newline.
  236. .Ss Scaling Widths
  237. Many requests and macros support scaled widths for their arguments.
  238. The syntax for a scaled width is
  239. .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
  240. where a decimal must be preceded or followed by at least one digit.
  241. .Pp
  242. The following scaling units are accepted:
  243. .Pp
  244. .Bl -tag -width Ds -offset indent -compact
  245. .It c
  246. centimetre
  247. .It i
  248. inch
  249. .It P
  250. pica (1/6 inch)
  251. .It p
  252. point (1/72 inch)
  253. .It f
  254. scale
  255. .Sq u
  256. by 65536
  257. .It v
  258. default vertical span
  259. .It m
  260. width of rendered
  261. .Sq m
  262. .Pq em
  263. character
  264. .It n
  265. width of rendered
  266. .Sq n
  267. .Pq en
  268. character
  269. .It u
  270. default horizontal span for the terminal
  271. .It M
  272. mini-em (1/100 em)
  273. .El
  274. .Pp
  275. Using anything other than
  276. .Sq m ,
  277. .Sq n ,
  278. or
  279. .Sq v
  280. is necessarily non-portable across output media.
  281. See
  282. .Sx COMPATIBILITY .
  283. .Pp
  284. If a scaling unit is not provided, the numerical value is interpreted
  285. under the default rules of
  286. .Sq v
  287. for vertical spaces and
  288. .Sq u
  289. for horizontal ones.
  290. .Pp
  291. Examples:
  292. .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
  293. .It Li \&.Bl -tag -width 2i
  294. two-inch tagged list indentation in
  295. .Xr mdoc 7
  296. .It Li \&.HP 2i
  297. two-inch tagged list indentation in
  298. .Xr man 7
  299. .It Li \&.sp 2v
  300. two vertical spaces
  301. .El
  302. .Ss Sentence Spacing
  303. Each sentence should terminate at the end of an input line.
  304. By doing this, a formatter will be able to apply the proper amount of
  305. spacing after the end of sentence (unescaped) period, exclamation mark,
  306. or question mark followed by zero or more non-sentence closing
  307. delimiters
  308. .Po
  309. .Sq \&) ,
  310. .Sq \&] ,
  311. .Sq \&' ,
  312. .Sq \&"
  313. .Pc .
  314. .Pp
  315. The proper spacing is also intelligently preserved if a sentence ends at
  316. the boundary of a macro line.
  317. .Pp
  318. If an input line happens to end with a period, exclamation or question
  319. mark that isn't the end of a sentence, append a zero-width space
  320. .Pq Sq \e& .
  321. .Pp
  322. Examples:
  323. .Bd -literal -offset indent -compact
  324. Do not end sentences mid-line like this. Instead,
  325. end a sentence like this.
  326. A macro would end like this:
  327. \&.Xr mandoc 1 \&.
  328. An abbreviation at the end of an input line needs escaping, e.g.\e&
  329. like this.
  330. .Ed
  331. .Sh REQUEST SYNTAX
  332. A request or macro line consists of:
  333. .Pp
  334. .Bl -enum -compact
  335. .It
  336. the control character
  337. .Sq \&.
  338. or
  339. .Sq \(aq
  340. at the beginning of the line,
  341. .It
  342. optionally an arbitrary amount of whitespace,
  343. .It
  344. the name of the request or the macro, which is one word of arbitrary
  345. length, terminated by whitespace,
  346. .It
  347. and zero or more arguments delimited by whitespace.
  348. .El
  349. .Pp
  350. Thus, the following request lines are all equivalent:
  351. .Bd -literal -offset indent
  352. \&.ig end
  353. \&.ig end
  354. \&. ig end
  355. .Ed
  356. .Sh MACRO SYNTAX
  357. Macros are provided by the
  358. .Xr mdoc 7
  359. and
  360. .Xr man 7
  361. languages and can be defined by the
  362. .Ic \&de
  363. request.
  364. When called, they follow the same syntax as requests, except that
  365. macro arguments may optionally be quoted by enclosing them
  366. in double quote characters
  367. .Pq Sq \(dq .
  368. Quoted text, even if it contains whitespace or would cause
  369. a macro invocation when unquoted, is always considered literal text.
  370. Inside quoted text, pairs of double quote characters
  371. .Pq Sq Qq
  372. resolve to single double quote characters.
  373. .Pp
  374. To be recognised as the beginning of a quoted argument, the opening
  375. quote character must be preceded by a space character.
  376. A quoted argument extends to the next double quote character that is not
  377. part of a pair, or to the end of the input line, whichever comes earlier.
  378. Leaving out the terminating double quote character at the end of the line
  379. is discouraged.
  380. For clarity, if more arguments follow on the same input line,
  381. it is recommended to follow the terminating double quote character
  382. by a space character; in case the next character after the terminating
  383. double quote character is anything else, it is regarded as the beginning
  384. of the next, unquoted argument.
  385. .Pp
  386. Both in quoted and unquoted arguments, pairs of backslashes
  387. .Pq Sq \e\e
  388. resolve to single backslashes.
  389. In unquoted arguments, space characters can alternatively be included
  390. by preceding them with a backslash
  391. .Pq Sq \e\~ ,
  392. but quoting is usually better for clarity.
  393. .Pp
  394. Examples:
  395. .Bl -tag -width Ds -offset indent -compact
  396. .It Li .Fn strlen \(dqconst char *s\(dq
  397. Group arguments
  398. .Qq const char *s
  399. into one function argument.
  400. If unspecified,
  401. .Qq const ,
  402. .Qq char ,
  403. and
  404. .Qq *s
  405. would be considered separate arguments.
  406. .It Li .Op \(dqFl a\(dq
  407. Consider
  408. .Qq \&Fl a
  409. as literal text instead of a flag macro.
  410. .El
  411. .Sh REQUEST REFERENCE
  412. The
  413. .Xr mandoc 1
  414. .Nm
  415. parser recognises the following requests.
  416. For requests marked as "ignored" or "unsupported", any arguments are
  417. ignored, and the number of arguments is not checked.
  418. .Bl -tag -width Ds
  419. .It Ic \&ab Op Ar message
  420. Abort processing.
  421. Currently unsupported.
  422. .It Ic \&ad Op Cm b | c | l | n | r
  423. Set line adjustment mode for subsequent text.
  424. Currently ignored.
  425. .It Ic \&af Ar registername format
  426. Assign an output format to a number register.
  427. Currently ignored.
  428. .It Ic \&aln Ar newname oldname
  429. Create an alias for a number register.
  430. Currently unsupported.
  431. .It Ic \&als Ar newname oldname
  432. Create an alias for a request, string, macro, or diversion.
  433. .It Ic \&am Ar macroname Op Ar endmacro
  434. Append to a macro definition.
  435. The syntax of this request is the same as that of
  436. .Ic \&de .
  437. .It Ic \&am1 Ar macroname Op Ar endmacro
  438. Append to a macro definition, switching roff compatibility mode off
  439. during macro execution (groff extension).
  440. The syntax of this request is the same as that of
  441. .Ic \&de1 .
  442. Since
  443. .Xr mandoc 1
  444. does not implement
  445. .Nm
  446. compatibility mode at all, it handles this request as an alias for
  447. .Ic \&am .
  448. .It Ic \&ami Ar macrostring Op Ar endstring
  449. Append to a macro definition, specifying the macro name indirectly
  450. (groff extension).
  451. The syntax of this request is the same as that of
  452. .Ic \&dei .
  453. .It Ic \&ami1 Ar macrostring Op Ar endstring
  454. Append to a macro definition, specifying the macro name indirectly
  455. and switching roff compatibility mode off during macro execution
  456. (groff extension).
  457. The syntax of this request is the same as that of
  458. .Ic \&dei1 .
  459. Since
  460. .Xr mandoc 1
  461. does not implement
  462. .Nm
  463. compatibility mode at all, it handles this request as an alias for
  464. .Ic \&ami .
  465. .It Ic \&as Ar stringname Op Ar string
  466. Append to a user-defined string.
  467. The syntax of this request is the same as that of
  468. .Ic \&ds .
  469. If a user-defined string with the specified name does not yet exist,
  470. it is set to the empty string before appending.
  471. .It Ic \&as1 Ar stringname Op Ar string
  472. Append to a user-defined string, switching roff compatibility mode off
  473. during macro execution (groff extension).
  474. The syntax of this request is the same as that of
  475. .Ic \&ds1 .
  476. Since
  477. .Xr mandoc 1
  478. does not implement
  479. .Nm
  480. compatibility mode at all, it handles this request as an alias for
  481. .Ic \&as .
  482. .It Ic \&asciify Ar divname
  483. Fully unformat a diversion.
  484. Currently unsupported.
  485. .It Ic \&backtrace
  486. Print a backtrace of the input stack.
  487. This is a groff extension and currently ignored.
  488. .It Ic \&bd Ar font Oo Ar curfont Oc Op Ar offset
  489. Artificially embolden by repeated printing with small shifts.
  490. Currently ignored.
  491. .It Ic \&bleedat Ar left top width height
  492. Set the BleedBox page parameter for PDF generation.
  493. This is a Heirloom extension and currently ignored.
  494. .It Ic \&blm Ar macroname
  495. Set a blank line trap.
  496. Currently unsupported.
  497. .It Ic \&box Ar divname
  498. Begin a diversion without including a partially filled line.
  499. Currently unsupported.
  500. .It Ic \&boxa Ar divname
  501. Add to a diversion without including a partially filled line.
  502. Currently unsupported.
  503. .It Ic \&bp Oo Cm + Ns | Ns Cm - Oc Ns Ar pagenumber
  504. Begin a new page.
  505. Currently ignored.
  506. .It Ic \&BP Ar source height width position offset flags label
  507. Define a frame and place a picture in it.
  508. This is a Heirloom extension and currently unsupported.
  509. .It Ic \&br
  510. Break the output line.
  511. .It Ic \&break
  512. Break out of the innermost
  513. .Ic \&while
  514. loop.
  515. .It Ic \&breakchar Ar char ...
  516. Optional line break characters.
  517. This is a Heirloom extension and currently ignored.
  518. .It Ic \&brnl Ar N
  519. Break output line after the next
  520. .Ar N
  521. input lines.
  522. This is a Heirloom extension and currently ignored.
  523. .It Ic \&brp
  524. Break and spread output line.
  525. Currently, this is implemented as an alias for
  526. .Ic \&br .
  527. .It Ic \&brpnl Ar N
  528. Break and spread output line after the next
  529. .Ar N
  530. input lines.
  531. This is a Heirloom extension and currently ignored.
  532. .It Ic \&c2 Op Ar char
  533. Change the no-break control character.
  534. Currently unsupported.
  535. .It Ic \&cc Op Ar char
  536. Change the control character.
  537. If
  538. .Ar char
  539. is not specified, the control character is reset to
  540. .Sq \&. .
  541. Trailing characters are ignored.
  542. .It Ic \&ce Op Ar N
  543. Center the next
  544. .Ar N
  545. input lines without filling.
  546. .Ar N
  547. defaults to 1.
  548. An argument of 0 or less ends centering.
  549. Currently, high level macros abort centering.
  550. .It Ic \&cf Ar filename
  551. Output the contents of a file.
  552. Ignored because insecure.
  553. .It Ic \&cflags Ar flags char ...
  554. Set character flags.
  555. This is a groff extension and currently ignored.
  556. .It Ic \&ch Ar macroname Op Ar dist
  557. Change a trap location.
  558. Currently ignored.
  559. .It Ic \&char Ar glyph Op Ar string
  560. Define or redefine the ASCII character or character escape sequence
  561. .Ar glyph
  562. to be rendered as
  563. .Ar string ,
  564. which can be empty.
  565. Only partially supported in
  566. .Xr mandoc 1 ;
  567. may interact incorrectly with
  568. .Ic \&tr .
  569. .It Ic \&chop Ar stringname
  570. Remove the last character from a macro, string, or diversion.
  571. Currently unsupported.
  572. .It Ic \&class Ar classname char ...
  573. Define a character class.
  574. This is a groff extension and currently ignored.
  575. .It Ic \&close Ar streamname
  576. Close an open file.
  577. Ignored because insecure.
  578. .It Ic \&CL Ar color text
  579. Print text in color.
  580. This is a Heirloom extension and currently unsupported.
  581. .It Ic \&color Op Cm 1 | 0
  582. Activate or deactivate colors.
  583. This is a groff extension and currently ignored.
  584. .It Ic \&composite Ar from to
  585. Define a name component for composite glyph names.
  586. This is a groff extension and currently unsupported.
  587. .It Ic \&continue
  588. Immediately start the next iteration of a
  589. .Ic \&while
  590. loop.
  591. Currently unsupported.
  592. .It Ic \&cp Op Cm 1 | 0
  593. Switch
  594. .Nm
  595. compatibility mode on or off.
  596. Currently ignored.
  597. .It Ic \&cropat Ar left top width height
  598. Set the CropBox page parameter for PDF generation.
  599. This is a Heirloom extension and currently ignored.
  600. .It Ic \&cs Ar font Op Ar width Op Ar emsize
  601. Constant character spacing mode.
  602. Currently ignored.
  603. .It Ic \&cu Op Ar N
  604. Underline next
  605. .Ar N
  606. input lines including whitespace.
  607. Currently ignored.
  608. .It Ic \&da Ar divname
  609. Append to a diversion.
  610. Currently unsupported.
  611. .It Ic \&dch Ar macroname Op Ar dist
  612. Change a trap location in the current diversion.
  613. This is a Heirloom extension and currently unsupported.
  614. .It Ic \&de Ar macroname Op Ar endmacro
  615. Define a
  616. .Nm
  617. macro.
  618. Its syntax can be either
  619. .Bd -literal -offset indent
  620. .Pf . Ic \&de Ar macroname
  621. .Ar definition
  622. \&..
  623. .Ed
  624. .Pp
  625. or
  626. .Bd -literal -offset indent
  627. .Pf . Ic \&de Ar macroname endmacro
  628. .Ar definition
  629. .Pf . Ar endmacro
  630. .Ed
  631. .Pp
  632. Both forms define or redefine the macro
  633. .Ar macroname
  634. to represent the
  635. .Ar definition ,
  636. which may consist of one or more input lines, including the newline
  637. characters terminating each line, optionally containing calls to
  638. .Nm
  639. requests,
  640. .Nm
  641. macros or high-level macros like
  642. .Xr man 7
  643. or
  644. .Xr mdoc 7
  645. macros, whichever applies to the document in question.
  646. .Pp
  647. Specifying a custom
  648. .Ar endmacro
  649. works in the same way as for
  650. .Ic \&ig ;
  651. namely, the call to
  652. .Sq Pf . Ar endmacro
  653. first ends the
  654. .Ar definition ,
  655. and after that, it is also evaluated as a
  656. .Nm
  657. request or
  658. .Nm
  659. macro, but not as a high-level macro.
  660. .Pp
  661. The macro can be invoked later using the syntax
  662. .Pp
  663. .D1 Pf . Ar macroname Op Ar argument Op Ar argument ...
  664. .Pp
  665. Regarding argument parsing, see
  666. .Sx MACRO SYNTAX
  667. above.
  668. .Pp
  669. The line invoking the macro will be replaced
  670. in the input stream by the
  671. .Ar definition ,
  672. replacing all occurrences of
  673. .No \e\e$ Ns Ar N ,
  674. where
  675. .Ar N
  676. is a digit, by the
  677. .Ar N Ns th Ar argument .
  678. For example,
  679. .Bd -literal -offset indent
  680. \&.de ZN
  681. \efI\e^\e\e$1\e^\efP\e\e$2
  682. \&..
  683. \&.ZN XtFree .
  684. .Ed
  685. .Pp
  686. produces
  687. .Pp
  688. .D1 \efI\e^XtFree\e^\efP.
  689. .Pp
  690. in the input stream, and thus in the output: \fI\^XtFree\^\fP.
  691. Each occurrence of \e\e$* is replaced with all the arguments,
  692. joined together with single space characters.
  693. The variant \e\e$@ is similar, except that each argument is
  694. individually quoted.
  695. .Pp
  696. Since macros and user-defined strings share a common string table,
  697. defining a macro
  698. .Ar macroname
  699. clobbers the user-defined string
  700. .Ar macroname ,
  701. and the
  702. .Ar definition
  703. can also be printed using the
  704. .Sq \e*
  705. string interpolation syntax described below
  706. .Ic ds ,
  707. but this is rarely useful because every macro definition contains at least
  708. one explicit newline character.
  709. .Pp
  710. In order to prevent endless recursion, both groff and
  711. .Xr mandoc 1
  712. limit the stack depth for expanding macros and strings
  713. to a large, but finite number, and
  714. .Xr mandoc 1
  715. also limits the length of the expanded input line.
  716. Do not rely on the exact values of these limits.
  717. .It Ic \&de1 Ar macroname Op Ar endmacro
  718. Define a
  719. .Nm
  720. macro that will be executed with
  721. .Nm
  722. compatibility mode switched off during macro execution.
  723. This is a groff extension.
  724. Since
  725. .Xr mandoc 1
  726. does not implement
  727. .Nm
  728. compatibility mode at all, it handles this request as an alias for
  729. .Ic \&de .
  730. .It Ic \&defcolor Ar newname scheme component ...
  731. Define a color name.
  732. This is a groff extension and currently ignored.
  733. .It Ic \&dei Ar macrostring Op Ar endstring
  734. Define a
  735. .Nm
  736. macro, specifying the macro name indirectly (groff extension).
  737. The syntax of this request is the same as that of
  738. .Ic \&de .
  739. The effect is the same as:
  740. .Pp
  741. .D1 Pf . Cm \&de No \e* Ns Bo Ar macrostring Bc Op \e* Ns Bq Ar endstring
  742. .It Ic \&dei1 Ar macrostring Op Ar endstring
  743. Define a
  744. .Nm
  745. macro that will be executed with
  746. .Nm
  747. compatibility mode switched off during macro execution,
  748. specifying the macro name indirectly (groff extension).
  749. Since
  750. .Xr mandoc 1
  751. does not implement
  752. .Nm
  753. compatibility mode at all, it handles this request as an alias for
  754. .Ic \&dei .
  755. .It Ic \&device Ar string ...
  756. .It Ic \&devicem Ar stringname
  757. These two requests only make sense with the groff-specific intermediate
  758. output format and are unsupported.
  759. .It Ic \&di Ar divname
  760. Begin a diversion.
  761. Currently unsupported.
  762. .It Ic \&do Ar command Op Ar argument ...
  763. Execute
  764. .Nm
  765. request or macro line with compatibility mode disabled.
  766. Currently unsupported.
  767. .It Ic \&ds Ar stringname Op Oo \(dq Oc Ns Ar string
  768. Define a user-defined string.
  769. The
  770. .Ar stringname
  771. and
  772. .Ar string
  773. arguments are space-separated.
  774. If the
  775. .Ar string
  776. begins with a double-quote character, that character will not be part
  777. of the string.
  778. All remaining characters on the input line form the
  779. .Ar string ,
  780. including whitespace and double-quote characters, even trailing ones.
  781. .Pp
  782. The
  783. .Ar string
  784. can be interpolated into subsequent text by using
  785. .No \e* Ns Bq Ar stringname
  786. for a
  787. .Ar stringname
  788. of arbitrary length, or \e*(NN or \e*N if the length of
  789. .Ar stringname
  790. is two or one characters, respectively.
  791. Interpolation can be prevented by escaping the leading backslash;
  792. that is, an asterisk preceded by an even number of backslashes
  793. does not trigger string interpolation.
  794. .Pp
  795. Since user-defined strings and macros share a common string table,
  796. defining a string
  797. .Ar stringname
  798. clobbers the macro
  799. .Ar stringname ,
  800. and the
  801. .Ar stringname
  802. used for defining a string can also be invoked as a macro,
  803. in which case the following input line will be appended to the
  804. .Ar string ,
  805. forming a new input line passed to the
  806. .Nm
  807. parser.
  808. For example,
  809. .Bd -literal -offset indent
  810. \&.ds badidea .S
  811. \&.badidea
  812. H SYNOPSIS
  813. .Ed
  814. .Pp
  815. invokes the
  816. .Ic SH
  817. macro when used in a
  818. .Xr man 7
  819. document.
  820. Such abuse is of course strongly discouraged.
  821. .It Ic \&ds1 Ar stringname Op Oo \(dq Oc Ns Ar string
  822. Define a user-defined string that will be expanded with
  823. .Nm
  824. compatibility mode switched off during string expansion.
  825. This is a groff extension.
  826. Since
  827. .Xr mandoc 1
  828. does not implement
  829. .Nm
  830. compatibility mode at all, it handles this request as an alias for
  831. .Ic \&ds .
  832. .It Ic \&dwh Ar dist macroname
  833. Set a location trap in the current diversion.
  834. This is a Heirloom extension and currently unsupported.
  835. .It Ic \&dt Op Ar dist macroname
  836. Set a trap within a diversion.
  837. Currently unsupported.
  838. .It Ic \&ec Op Ar char
  839. Enable the escape mechanism and change the escape character.
  840. The
  841. .Ar char
  842. argument defaults to the backslash
  843. .Pq Sq \e .
  844. .It Ic \&ecr
  845. Restore the escape character.
  846. Currently unsupported.
  847. .It Ic \&ecs
  848. Save the escape character.
  849. Currently unsupported.
  850. .It Ic \&el Ar body
  851. The
  852. .Dq else
  853. half of an if/else conditional.
  854. Pops a result off the stack of conditional evaluations pushed by
  855. .Ic \&ie
  856. and uses it as its conditional.
  857. If no stack entries are present (e.g., due to no prior
  858. .Ic \&ie
  859. calls)
  860. then false is assumed.
  861. The syntax of this request is similar to
  862. .Ic \&if
  863. except that the conditional is missing.
  864. .It Ic \&em Ar macroname
  865. Set a trap at the end of input.
  866. Currently unsupported.
  867. .It Ic \&EN
  868. End an equation block.
  869. See
  870. .Ic \&EQ .
  871. .It Ic \&eo
  872. Disable the escape mechanism completely.
  873. .It Ic \&EP
  874. End a picture started by
  875. .Ic \&BP .
  876. This is a Heirloom extension and currently unsupported.
  877. .It Ic \&EQ
  878. Begin an equation block.
  879. See
  880. .Xr eqn 7
  881. for a description of the equation language.
  882. .It Ic \&errprint Ar message
  883. Print a string like an error message.
  884. This is a Heirloom extension and currently ignored.
  885. .It Ic \&ev Op Ar envname
  886. Switch to another environment.
  887. Currently unsupported.
  888. .It Ic \&evc Op Ar envname
  889. Copy an environment into the current environment.
  890. Currently unsupported.
  891. .It Ic \&ex
  892. Abort processing and exit.
  893. Currently unsupported.
  894. .It Ic \&fallback Ar curfont font ...
  895. Select the fallback sequence for a font.
  896. This is a Heirloom extension and currently ignored.
  897. .It Ic \&fam Op Ar familyname
  898. Change the font family.
  899. This is a groff extension and currently ignored.
  900. .It Ic \&fc Op Ar delimchar Op Ar padchar
  901. Define a delimiting and a padding character for fields.
  902. Currently unsupported.
  903. .It Ic \&fchar Ar glyphname Op Ar string
  904. Define a fallback glyph.
  905. Currently unsupported.
  906. .It Ic \&fcolor Ar colorname
  907. Set the fill color for \eD objects.
  908. This is a groff extension and currently ignored.
  909. .It Ic \&fdeferlig Ar font string ...
  910. Defer ligature building.
  911. This is a Heirloom extension and currently ignored.
  912. .It Ic \&feature Cm + Ns | Ns Cm - Ns Ar name
  913. Enable or disable an OpenType feature.
  914. This is a Heirloom extension and currently ignored.
  915. .It Ic \&fi
  916. Break the output line and switch to fill mode,
  917. which is active by default but can be ended with the
  918. .Ic \&nf
  919. request.
  920. In fill mode, input from subsequent input lines is added to
  921. the same output line until the next word no longer fits,
  922. at which point the output line is broken.
  923. This request is implied by the
  924. .Xr mdoc 7
  925. .Ic \&Sh
  926. macro and by the
  927. .Xr man 7
  928. .Ic \&SH ,
  929. .Ic \&SS ,
  930. and
  931. .Ic \&EE
  932. macros.
  933. .It Ic \&fkern Ar font minkern
  934. Control the use of kerning tables for a font.
  935. This is a Heirloom extension and currently ignored.
  936. .It Ic \&fl
  937. Flush output.
  938. Currently ignored.
  939. .It Ic \&flig Ar font string char ...
  940. Define ligatures.
  941. This is a Heirloom extension and currently ignored.
  942. .It Ic \&fp Ar position font Op Ar filename
  943. Assign font position.
  944. Currently ignored.
  945. .It Ic \&fps Ar mapname ...
  946. Mount a font with a special character map.
  947. This is a Heirloom extension and currently ignored.
  948. .It Ic \&fschar Ar font glyphname Op Ar string
  949. Define a font-specific fallback glyph.
  950. This is a groff extension and currently unsupported.
  951. .It Ic \&fspacewidth Ar font Op Ar afmunits
  952. Set a font-specific width for the space character.
  953. This is a Heirloom extension and currently ignored.
  954. .It Ic \&fspecial Ar curfont Op Ar font ...
  955. Conditionally define a special font.
  956. This is a groff extension and currently ignored.
  957. .It Ic \&ft Op Ar font
  958. Change the font; see
  959. .Sx Font Selection .
  960. The
  961. .Ar font
  962. argument defaults to
  963. .Cm P .
  964. .It Ic \&ftr Ar newname Op Ar oldname
  965. Translate font name.
  966. This is a groff extension and currently ignored.
  967. .It Ic \&fzoom Ar font Op Ar permille
  968. Zoom font size.
  969. Currently ignored.
  970. .It Ic \&gcolor Op Ar colorname
  971. Set glyph color.
  972. This is a groff extension and currently ignored.
  973. .It Ic \&hc Op Ar char
  974. Set the hyphenation character.
  975. Currently ignored.
  976. .It Ic \&hcode Ar char code ...
  977. Set hyphenation codes of characters.
  978. Currently ignored.
  979. .It Ic \&hidechar Ar font char ...
  980. Hide characters in a font.
  981. This is a Heirloom extension and currently ignored.
  982. .It Ic \&hla Ar language
  983. Set hyphenation language.
  984. This is a groff extension and currently ignored.
  985. .It Ic \&hlm Op Ar number
  986. Set maximum number of consecutive hyphenated lines.
  987. Currently ignored.
  988. .It Ic \&hpf Ar filename
  989. Load hyphenation pattern file.
  990. This is a groff extension and currently ignored.
  991. .It Ic \&hpfa Ar filename
  992. Load hyphenation pattern file, appending to the current patterns.
  993. This is a groff extension and currently ignored.
  994. .It Ic \&hpfcode Ar code code ...
  995. Define mapping values for character codes in hyphenation patterns.
  996. This is a groff extension and currently ignored.
  997. .It Ic \&hw Ar word ...
  998. Specify hyphenation points in words.
  999. Currently ignored.
  1000. .It Ic \&hy Op Ar mode
  1001. Set automatic hyphenation mode.
  1002. Currently ignored.
  1003. .It Ic \&hylang Ar language
  1004. Set hyphenation language.
  1005. This is a Heirloom extension and currently ignored.
  1006. .It Ic \&hylen Ar nchar
  1007. Minimum word length for hyphenation.
  1008. This is a Heirloom extension and currently ignored.
  1009. .It Ic \&hym Op Ar length
  1010. Set hyphenation margin.
  1011. This is a groff extension and currently ignored.
  1012. .It Ic \&hypp Ar penalty ...
  1013. Define hyphenation penalties.
  1014. This is a Heirloom extension and currently ignored.
  1015. .It Ic \&hys Op Ar length
  1016. Set hyphenation space.
  1017. This is a groff extension and currently ignored.
  1018. .It Ic \&ie Ar condition body
  1019. The
  1020. .Dq if
  1021. half of an if/else conditional.
  1022. The result of the conditional is pushed into a stack used by subsequent
  1023. invocations of
  1024. .Ic \&el ,
  1025. which may be separated by any intervening input (or not exist at all).
  1026. Its syntax is equivalent to
  1027. .Ic \&if .
  1028. .It Ic \&if Ar condition body
  1029. Begin a conditional.
  1030. This request can also be written as follows:
  1031. .Bd -unfilled -offset indent
  1032. .Pf . Ic \&if Ar condition No \e{ Ns Ar body
  1033. .Ar body ... Ns \e}
  1034. .Ed
  1035. .Bd -unfilled -offset indent
  1036. .Pf . Ic \&if Ar condition No \e{\e
  1037. .Ar body ...
  1038. .Pf . No \e}
  1039. .Ed
  1040. .Pp
  1041. The
  1042. .Ar condition
  1043. is a boolean expression.
  1044. Currently,
  1045. .Xr mandoc 1
  1046. supports the following subset of roff conditionals:
  1047. .Bl -bullet
  1048. .It
  1049. If
  1050. .Sq \&!
  1051. is prefixed to
  1052. .Ar condition ,
  1053. it is logically inverted.
  1054. .It
  1055. If the first character of
  1056. .Ar condition
  1057. is
  1058. .Sq n
  1059. .Pq nroff mode
  1060. or
  1061. .Sq o
  1062. .Pq odd page ,
  1063. it evaluates to true, and the
  1064. .Ar body
  1065. starts with the next character.
  1066. .It
  1067. If the first character of
  1068. .Ar condition
  1069. is
  1070. .Sq e
  1071. .Pq even page ,
  1072. .Sq t
  1073. .Pq troff mode ,
  1074. or
  1075. .Sq v
  1076. .Pq vroff mode ,
  1077. it evaluates to false, and the
  1078. .Ar body
  1079. starts with the next character.
  1080. .It
  1081. If the first character of
  1082. .Ar condition
  1083. is
  1084. .Sq c
  1085. .Pq character available ,
  1086. it evaluates to true if the following character is an ASCII character
  1087. or a valid character escape sequence, or to false otherwise.
  1088. The
  1089. .Ar body
  1090. starts with the character following that next character.
  1091. .It
  1092. If the first character of
  1093. .Ar condition
  1094. is
  1095. .Sq d ,
  1096. it evaluates to true if the rest of
  1097. .Ar condition
  1098. is the name of an existing user defined macro or string;
  1099. otherwise, it evaluates to false.
  1100. .It
  1101. If the first character of
  1102. .Ar condition
  1103. is
  1104. .Sq r ,
  1105. it evaluates to true if the rest of
  1106. .Ar condition
  1107. is the name of an existing number register;
  1108. otherwise, it evaluates to false.
  1109. .It
  1110. If the
  1111. .Ar condition
  1112. starts with a parenthesis or with an optionally signed
  1113. integer number, it is evaluated according to the rules of
  1114. .Sx Numerical expressions
  1115. explained below.
  1116. It evaluates to true if the result is positive,
  1117. or to false if the result is zero or negative.
  1118. .It
  1119. Otherwise, the first character of
  1120. .Ar condition
  1121. is regarded as a delimiter and it evaluates to true if the string
  1122. extending from its first to its second occurrence is equal to the
  1123. string extending from its second to its third occurrence.
  1124. .It
  1125. If
  1126. .Ar condition
  1127. cannot be parsed, it evaluates to false.
  1128. .El
  1129. .Pp
  1130. If a conditional is false, its children are not processed, but are
  1131. syntactically interpreted to preserve the integrity of the input
  1132. document.
  1133. Thus,
  1134. .Pp
  1135. .D1 \&.if t .ig
  1136. .Pp
  1137. will discard the
  1138. .Sq \&.ig ,
  1139. which may lead to interesting results, but
  1140. .Pp
  1141. .D1 \&.if t .if t \e{\e
  1142. .Pp
  1143. will continue to syntactically interpret to the block close of the final
  1144. conditional.
  1145. Sub-conditionals, in this case, obviously inherit the truth value of
  1146. the parent.
  1147. .Pp
  1148. If the
  1149. .Ar body
  1150. section is begun by an escaped brace
  1151. .Sq \e{ ,
  1152. scope continues until the end of the input line containing the
  1153. matching closing-brace escape sequence
  1154. .Sq \e} .
  1155. If the
  1156. .Ar body
  1157. is not enclosed in braces, scope continues until the end of the line.
  1158. If the
  1159. .Ar condition
  1160. is followed by a
  1161. .Ar body
  1162. on the same line, whether after a brace or not, then requests and macros
  1163. .Em must
  1164. begin with a control character.
  1165. It is generally more intuitive, in this case, to write
  1166. .Bd -unfilled -offset indent
  1167. .Pf . Ic \&if Ar condition No \e{\e
  1168. .Pf . Ar request
  1169. .Pf . No \e}
  1170. .Ed
  1171. .Pp
  1172. than having the request or macro follow as
  1173. .Pp
  1174. .D1 Pf . Ic \&if Ar condition Pf \e{. Ar request
  1175. .Pp
  1176. The scope of a conditional is always parsed, but only executed if the
  1177. conditional evaluates to true.
  1178. .Pp
  1179. Note that the
  1180. .Sq \e}
  1181. is converted into a zero-width escape sequence if not passed as a
  1182. standalone macro
  1183. .Sq \&.\e} .
  1184. For example,
  1185. .Pp
  1186. .D1 \&.Fl a \e} b
  1187. .Pp
  1188. will result in
  1189. .Sq \e}
  1190. being considered an argument of the
  1191. .Sq \&Fl
  1192. macro.
  1193. .It Ic \&ig Op Ar endmacro
  1194. Ignore input.
  1195. Its syntax can be either
  1196. .Bd -literal -offset indent
  1197. .Pf . Cm \&ig
  1198. .Ar ignored text
  1199. \&..
  1200. .Ed
  1201. .Pp
  1202. or
  1203. .Bd -literal -offset indent
  1204. .Pf . Cm \&ig Ar endmacro
  1205. .Ar ignored text
  1206. .Pf . Ar endmacro
  1207. .Ed
  1208. .Pp
  1209. In the first case, input is ignored until a
  1210. .Sq \&..
  1211. request is encountered on its own line.
  1212. In the second case, input is ignored until the specified
  1213. .Sq Pf . Ar endmacro
  1214. is encountered.
  1215. Do not use the escape character
  1216. .Sq \e
  1217. anywhere in the definition of
  1218. .Ar endmacro ;
  1219. it would cause very strange behaviour.
  1220. .Pp
  1221. When the
  1222. .Ar endmacro
  1223. is a roff request or a roff macro, like in
  1224. .Pp
  1225. .D1 \&.ig if
  1226. .Pp
  1227. the subsequent invocation of
  1228. .Ic \&if
  1229. will first terminate the
  1230. .Ar ignored text ,
  1231. then be invoked as usual.
  1232. Otherwise, it only terminates the
  1233. .Ar ignored text ,
  1234. and arguments following it or the
  1235. .Sq \&..
  1236. request are discarded.
  1237. .It Ic \&in Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
  1238. Change indentation.
  1239. See
  1240. .Xr man 7 .
  1241. Ignored in
  1242. .Xr mdoc 7 .
  1243. .It Ic \&index Ar register stringname substring
  1244. Find a substring in a string.
  1245. This is a Heirloom extension and currently unsupported.
  1246. .It Ic \&it Ar expression macro
  1247. Set an input line trap.
  1248. The named
  1249. .Ar macro
  1250. will be invoked after processing the number of input text lines
  1251. specified by the numerical
  1252. .Ar expression .
  1253. While evaluating the
  1254. .Ar expression ,
  1255. the unit suffixes described below
  1256. .Sx Scaling Widths
  1257. are ignored.
  1258. .It Ic \&itc Ar expression macro
  1259. Set an input line trap, not counting lines ending with \ec.
  1260. Currently unsupported.
  1261. .It Ic \&IX Ar class keystring
  1262. To support the generation of a table of contents,
  1263. .Xr pod2man 1
  1264. emits this user-defined macro, usually without defining it.
  1265. To avoid reporting large numbers of spurious errors,
  1266. .Xr mandoc 1
  1267. ignores it.
  1268. .It Ic \&kern Op Cm 1 | 0
  1269. Switch kerning on or off.
  1270. Currently ignored.
  1271. .It Ic \&kernafter Ar font char ... afmunits ...
  1272. Increase kerning after some characters.
  1273. This is a Heirloom extension and currently ignored.
  1274. .It Ic \&kernbefore Ar font char ... afmunits ...
  1275. Increase kerning before some characters.
  1276. This is a Heirloom extension and currently ignored.
  1277. .It Ic \&kernpair Ar font char ... font char ... afmunits
  1278. Add a kerning pair to the kerning table.
  1279. This is a Heirloom extension and currently ignored.
  1280. .It Ic \&lc Op Ar glyph
  1281. Define a leader repetition character.
  1282. Currently unsupported.
  1283. .It Ic \&lc_ctype Ar localename
  1284. Set the
  1285. .Dv LC_CTYPE
  1286. locale.
  1287. This is a Heirloom extension and currently unsupported.
  1288. .It Ic \&lds Ar macroname string
  1289. Define a local string.
  1290. This is a Heirloom extension and currently unsupported.
  1291. .It Ic \&length Ar register string
  1292. Count the number of input characters in a string.
  1293. Currently unsupported.
  1294. .It Ic \&letadj Ar lspmin lshmin letss lspmax lshmax
  1295. Dynamic letter spacing and reshaping.
  1296. This is a Heirloom extension and currently ignored.
  1297. .It Ic \&lf Ar lineno Op Ar filename
  1298. Change the line number for error messages.
  1299. Ignored because insecure.
  1300. .It Ic \&lg Op Cm 1 | 0
  1301. Switch the ligature mechanism on or off.
  1302. Currently ignored.
  1303. .It Ic \&lhang Ar font char ... afmunits
  1304. Hang characters at left margin.
  1305. This is a Heirloom extension and currently ignored.
  1306. .It Ic \&linetabs Op Cm 1 | 0
  1307. Enable or disable line-tabs mode.
  1308. This is a groff extension and currently unsupported.
  1309. .It Ic \&ll Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
  1310. Change the output line length.
  1311. If the
  1312. .Ar width
  1313. argument is omitted, the line length is reset to its previous value.
  1314. The default setting for terminal output is 78n.
  1315. If a sign is given, the line length is added to or subtracted from;
  1316. otherwise, it is set to the provided value.
  1317. Using this request in new manuals is discouraged for several reasons,
  1318. among others because it overrides the
  1319. .Xr mandoc 1
  1320. .Fl O Cm width
  1321. command line option.
  1322. .It Ic \&lnr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment
  1323. Set local number register.
  1324. This is a Heirloom extension and currently unsupported.
  1325. .It Ic \&lnrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment
  1326. Set local floating-point register.
  1327. This is a Heirloom extension and currently unsupported.
  1328. .It Ic \&lpfx Ar string
  1329. Set a line prefix.
  1330. This is a Heirloom extension and currently unsupported.
  1331. .It Ic \&ls Op Ar factor
  1332. Set line spacing.
  1333. It takes one integer argument specifying the vertical distance of
  1334. subsequent output text lines measured in v units.
  1335. Currently ignored.
  1336. .It Ic \&lsm Ar macroname
  1337. Set a leading spaces trap.
  1338. This is a groff extension and currently unsupported.
  1339. .It Ic \&lt Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
  1340. Set title line length.
  1341. Currently ignored.
  1342. .It Ic \&mc Ar glyph Op Ar dist
  1343. Print margin character in the right margin.
  1344. The
  1345. .Ar dist
  1346. is currently ignored; instead, 1n is used.
  1347. .It Ic \&mediasize Ar media
  1348. Set the device media size.
  1349. This is a Heirloom extension and currently ignored.
  1350. .It Ic \&minss Ar width
  1351. Set minimum word space.
  1352. This is a Heirloom extension and currently ignored.
  1353. .It Ic \&mk Op Ar register
  1354. Mark vertical position.
  1355. Currently ignored.
  1356. .It Ic \&mso Ar filename
  1357. Load a macro file using the search path.
  1358. Ignored because insecure.
  1359. .It Ic \&na
  1360. Disable adjusting without changing the adjustment mode.
  1361. Currently ignored.
  1362. .It Ic \&ne Op Ar height
  1363. Declare the need for the specified minimum vertical space
  1364. before the next trap or the bottom of the page.
  1365. Currently ignored.
  1366. .It Ic \&nf
  1367. Break the output line and switch to no-fill mode.
  1368. Subsequent input lines are kept together on the same output line
  1369. even when exceeding the right margin,
  1370. and line breaks in subsequent input cause output line breaks.
  1371. This request is implied by the
  1372. .Xr mdoc 7
  1373. .Ic \&Bd Fl unfilled
  1374. and
  1375. .Ic \&Bd Fl literal
  1376. macros and by the
  1377. .Xr man 7
  1378. .Ic \&EX
  1379. macro.
  1380. The
  1381. .Ic \&fi
  1382. request switches back to the default fill mode.
  1383. .It Ic \&nh
  1384. Turn off automatic hyphenation mode.
  1385. Currently ignored.
  1386. .It Ic \&nhychar Ar char ...
  1387. Define hyphenation-inhibiting characters.
  1388. This is a Heirloom extension and currently ignored.
  1389. .It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent
  1390. Print line numbers.
  1391. Currently unsupported.
  1392. .It Ic \&nn Op Ar number
  1393. Temporarily turn off line numbering.
  1394. Currently unsupported.
  1395. .It Ic \&nop Ar body
  1396. Execute the rest of the input line as a request, macro, or text line,
  1397. skipping the
  1398. .Ic \&nop
  1399. request and any space characters immediately following it.
  1400. This is mostly used to indent text lines inside macro definitions.
  1401. .It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize
  1402. Define or change a register.
  1403. A register is an arbitrary string value that defines some sort of state,
  1404. which influences parsing and/or formatting.
  1405. For the syntax of
  1406. .Ar expression ,
  1407. see
  1408. .Sx Numerical expressions
  1409. below.
  1410. If it is prefixed by a sign, the register will be
  1411. incremented or decremented instead of assigned to.
  1412. .Pp
  1413. The
  1414. .Ar stepsize
  1415. is used by the
  1416. .Ic \en+
  1417. auto-increment feature.
  1418. It remains unchanged when omitted while changing an existing register,
  1419. and it defaults to 0 when defining a new register.
  1420. .Pp
  1421. The following
  1422. .Ar register
  1423. is handled specially:
  1424. .Bl -tag -width Ds
  1425. .It Cm nS
  1426. If set to a positive integer value, certain
  1427. .Xr mdoc 7
  1428. macros will behave in the same way as in the
  1429. .Em SYNOPSIS
  1430. section.
  1431. If set to 0, these macros will behave in the same way as outside the
  1432. .Em SYNOPSIS
  1433. section, even when called within the
  1434. .Em SYNOPSIS
  1435. section itself.
  1436. Note that starting a new
  1437. .Xr mdoc 7
  1438. section with the
  1439. .Ic \&Sh
  1440. macro will reset this register.
  1441. .El
  1442. .It Xo
  1443. .Ic \&nrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
  1444. .Op Ar increment
  1445. .Xc
  1446. Define or change a floating-point register.
  1447. This is a Heirloom extension and currently unsupported.
  1448. .It Ic \&nroff
  1449. Force nroff mode.
  1450. This is a groff extension and currently ignored.
  1451. .It Ic \&ns
  1452. Turn on no-space mode.
  1453. Currently ignored.
  1454. .It Ic \&nx Op Ar filename
  1455. Abort processing of the current input file and process another one.
  1456. Ignored because insecure.
  1457. .It Ic \&open Ar stream file
  1458. Open a file for writing.
  1459. Ignored because insecure.
  1460. .It Ic \&opena Ar stream file
  1461. Open a file for appending.
  1462. Ignored because insecure.
  1463. .It Ic \&os
  1464. Output saved vertical space.
  1465. Currently ignored.
  1466. .It Ic \&output Ar string
  1467. Output directly to intermediate output.
  1468. Not supported.
  1469. .It Ic \&padj Op Cm 1 | 0
  1470. Globally control paragraph-at-once adjustment.
  1471. This is a Heirloom extension and currently ignored.
  1472. .It Ic \&papersize Ar media
  1473. Set the paper size.
  1474. This is a Heirloom extension and currently ignored.
  1475. .It Ic \&pc Op Ar char
  1476. Change the page number character.
  1477. Currently ignored.
  1478. .It Ic \&pev
  1479. Print environments.
  1480. This is a groff extension and currently ignored.
  1481. .It Ic \&pi Ar command
  1482. Pipe output to a shell command.
  1483. Ignored because insecure.
  1484. .It Ic \&PI
  1485. Low-level request used by
  1486. .Ic \&BP .
  1487. This is a Heirloom extension and currently unsupported.
  1488. .It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
  1489. Change page length.
  1490. Currently ignored.
  1491. .It Ic \&pm
  1492. Print names and sizes of macros, strings, and diversions
  1493. to standard error output.
  1494. Currently ignored.
  1495. .It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number
  1496. Change the page number of the next page.
  1497. Currently ignored.
  1498. .It Ic \&pnr
  1499. Print all number registers on standard error output.
  1500. Currently ignored.
  1501. .It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset
  1502. Set a horizontal page offset.
  1503. If no argument is specified, the page offset is reverted to its
  1504. previous value.
  1505. If a sign is specified, the new page offset is calculated relative
  1506. to the current one; otherwise, it is absolute.
  1507. The argument follows the syntax of
  1508. .Sx Scaling Widths
  1509. and the default scaling unit is
  1510. .Cm m .
  1511. .It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size
  1512. Change point size.
  1513. Currently ignored.
  1514. .It Ic \&psbb Ar filename
  1515. Retrieve the bounding box of a PostScript file.
  1516. Currently unsupported.
  1517. .It Ic \&pshape Ar indent length ...
  1518. Set a special shape for the current paragraph.
  1519. This is a Heirloom extension and currently unsupported.
  1520. .It Ic \&pso Ar command
  1521. Include output of a shell command.
  1522. Ignored because insecure.
  1523. .It Ic \&ptr
  1524. Print the names and positions of all traps on standard error output.
  1525. This is a groff extension and currently ignored.
  1526. .It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
  1527. Change post-vertical spacing.
  1528. This is a groff extension and currently ignored.
  1529. .It Ic \&rchar Ar glyph ...
  1530. Remove glyph definitions.
  1531. Currently unsupported.
  1532. .It Ic \&rd Op Ar prompt Op Ar argument ...
  1533. Read from standard input.
  1534. Currently ignored.
  1535. .It Ic \&recursionlimit Ar maxrec maxtail
  1536. Set the maximum stack depth for recursive macros.
  1537. This is a Heirloom extension and currently ignored.
  1538. .It Ic \&return Op Ar twice
  1539. Exit the presently executed macro and return to the caller.
  1540. The argument is currently ignored.
  1541. .It Ic \&rfschar Ar font glyph ...
  1542. Remove font-specific fallback glyph definitions.
  1543. Currently unsupported.
  1544. .It Ic \&rhang Ar font char ... afmunits
  1545. Hang characters at right margin.
  1546. This is a Heirloom extension and currently ignored.
  1547. .It Ic \&rj Op Ar N
  1548. Justify the next
  1549. .Ar N
  1550. input lines to the right margin without filling.
  1551. .Ar N
  1552. defaults to 1.
  1553. An argument of 0 or less ends right adjustment.
  1554. .It Ic \&rm Ar macroname
  1555. Remove a request, macro or string.
  1556. .It Ic \&rn Ar oldname newname
  1557. Rename a request, macro, diversion, or string.
  1558. In
  1559. .Xr mandoc 1 ,
  1560. user-defined macros,
  1561. .Xr mdoc 7
  1562. and
  1563. .Xr man 7
  1564. macros, and user-defined strings can be renamed, but renaming of
  1565. predefined strings and of
  1566. .Nm
  1567. requests is not supported, and diversions are not implemented at all.
  1568. .It Ic \&rnn Ar oldname newname
  1569. Rename a number register.
  1570. Currently unsupported.
  1571. .It Ic \&rr Ar register
  1572. Remove a register.
  1573. .It Ic \&rs
  1574. End no-space mode.
  1575. Currently ignored.
  1576. .It Ic \&rt Op Ar dist
  1577. Return to marked vertical position.
  1578. Currently ignored.
  1579. .It Ic \&schar Ar glyph Op Ar string
  1580. Define global fallback glyph.
  1581. This is a groff extension and currently unsupported.
  1582. .It Ic \&sentchar Ar char ...
  1583. Define sentence-ending characters.
  1584. This is a Heirloom extension and currently ignored.
  1585. .It Ic \&shc Op Ar glyph
  1586. Change the soft hyphen character.
  1587. Currently ignored.
  1588. .It Ic \&shift Op Ar number
  1589. Shift macro arguments
  1590. .Ar number
  1591. times, by default once: \e\e$i becomes what \e\e$i+number was.
  1592. Also decrement \en(.$ by
  1593. .Ar number .
  1594. .It Ic \&sizes Ar size ...
  1595. Define permissible point sizes.
  1596. This is a groff extension and currently ignored.
  1597. .It Ic \&so Ar filename
  1598. Include a source file.
  1599. The file is read and its contents processed as input in place of the
  1600. .Ic \&so
  1601. request line.
  1602. To avoid inadvertent inclusion of unrelated files,
  1603. .Xr mandoc 1
  1604. only accepts relative paths not containing the strings
  1605. .Qq ../
  1606. and
  1607. .Qq /.. .
  1608. .Pp
  1609. This request requires
  1610. .Xr man 1
  1611. to change to the right directory before calling
  1612. .Xr mandoc 1 ,
  1613. per convention to the root of the manual tree.
  1614. Typical usage looks like:
  1615. .Pp
  1616. .Dl \&.so man3/Xcursor.3
  1617. .Pp
  1618. As the whole concept is rather fragile, the use of
  1619. .Ic \&so
  1620. is discouraged.
  1621. Use
  1622. .Xr ln 1
  1623. instead.
  1624. .It Ic \&sp Op Ar height
  1625. Break the output line and emit vertical space.
  1626. The argument follows the syntax of
  1627. .Sx Scaling Widths
  1628. and defaults to one blank line
  1629. .Pq Li 1v .
  1630. .It Ic \&spacewidth Op Cm 1 | 0
  1631. Set the space width from the font metrics file.
  1632. This is a Heirloom extension and currently ignored.
  1633. .It Ic \&special Op Ar font ...
  1634. Define a special font.
  1635. This is a groff extension and currently ignored.
  1636. .It Ic \&spreadwarn Op Ar width
  1637. Warn about wide spacing between words.
  1638. Currently ignored.
  1639. .It Ic \&ss Ar wordspace Op Ar sentencespace
  1640. Set space character size.
  1641. Currently ignored.
  1642. .It Ic \&sty Ar position style
  1643. Associate style with a font position.
  1644. This is a groff extension and currently ignored.
  1645. .It Ic \&substring Ar stringname startpos Op Ar endpos
  1646. Replace a user-defined string with a substring.
  1647. Currently unsupported.
  1648. .It Ic \&sv Op Ar height
  1649. Save vertical space.
  1650. Currently ignored.
  1651. .It Ic \&sy Ar command
  1652. Execute shell command.
  1653. Ignored because insecure.
  1654. .It Ic \&T&
  1655. Re-start a table layout, retaining the options of the prior table
  1656. invocation.
  1657. See
  1658. .Ic \&TS .
  1659. .It Ic \&ta Op Ar width ... Op Cm T Ar width ...
  1660. Set tab stops.
  1661. Each
  1662. .Ar width
  1663. argument follows the syntax of
  1664. .Sx Scaling Widths .
  1665. If prefixed by a plus sign, it is relative to the previous tab stop.
  1666. The arguments after the
  1667. .Cm T
  1668. marker are used repeatedly as often as needed; for each reuse,
  1669. they are taken relative to the last previously established tab stop.
  1670. When
  1671. .Ic \&ta
  1672. is called without arguments, all tab stops are cleared.
  1673. .It Ic \&tc Op Ar glyph
  1674. Change tab repetition character.
  1675. Currently unsupported.
  1676. .It Ic \&TE
  1677. End a table context.
  1678. See
  1679. .Ic \&TS .
  1680. .It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width
  1681. Break the output line and indent the next output line by
  1682. .Ar width .
  1683. If a sign is specified, the temporary indentation is calculated
  1684. relative to the current indentation; otherwise, it is absolute.
  1685. The argument follows the syntax of
  1686. .Sx Scaling Widths
  1687. and the default scaling unit is
  1688. .Cm m .
  1689. .It Ic \&tkf Ar font minps width1 maxps width2
  1690. Enable track kerning for a font.
  1691. Currently ignored.
  1692. .It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap
  1693. Print a title line.
  1694. Currently unsupported.
  1695. .It Ic \&tm Ar string
  1696. Print to standard error output.
  1697. Currently ignored.
  1698. .It Ic \&tm1 Ar string
  1699. Print to standard error output, allowing leading blanks.
  1700. This is a groff extension and currently ignored.
  1701. .It Ic \&tmc Ar string
  1702. Print to standard error output without a trailing newline.
  1703. This is a groff extension and currently ignored.
  1704. .It Ic \&tr Ar glyph glyph ...
  1705. Output character translation.
  1706. The first glyph in each pair is replaced by the second one.
  1707. Character escapes can be used; for example,
  1708. .Pp
  1709. .Dl tr \e(xx\e(yy
  1710. .Pp
  1711. replaces all invocations of \e(xx with \e(yy.
  1712. .It Ic \&track Ar font minps width1 maxps width2
  1713. Static letter space tracking.
  1714. This is a Heirloom extension and currently ignored.
  1715. .It Ic \&transchar Ar char ...
  1716. Define transparent characters for sentence-ending.
  1717. This is a Heirloom extension and currently ignored.
  1718. .It Ic \&trf Ar filename
  1719. Output the contents of a file, disallowing invalid characters.
  1720. This is a groff extension and ignored because insecure.
  1721. .It Ic \&trimat Ar left top width height
  1722. Set the TrimBox page parameter for PDF generation.
  1723. This is a Heirloom extension and currently ignored.
  1724. .It Ic \&trin Ar glyph glyph ...
  1725. Output character translation, ignored by
  1726. .Ic \&asciify .
  1727. Currently unsupported.
  1728. .It Ic \&trnt Ar glyph glyph ...
  1729. Output character translation, ignored by \e!.
  1730. Currently unsupported.
  1731. .It Ic \&troff
  1732. Force troff mode.
  1733. This is a groff extension and currently ignored.
  1734. .It Ic \&TS
  1735. Begin a table, which formats input in aligned rows and columns.
  1736. See
  1737. .Xr tbl 7
  1738. for a description of the tbl language.
  1739. .It Ic \&uf Ar font
  1740. Globally set the underline font.
  1741. Currently ignored.
  1742. .It Ic \&ul Op Ar N
  1743. Underline next
  1744. .Ar N
  1745. input lines.
  1746. Currently ignored.
  1747. .It Ic \&unformat Ar divname
  1748. Unformat spaces and tabs in a diversion.
  1749. Currently unsupported.
  1750. .It Ic \&unwatch Ar macroname
  1751. Disable notification for string or macro.
  1752. This is a Heirloom extension and currently ignored.
  1753. .It Ic \&unwatchn Ar register
  1754. Disable notification for register.
  1755. This is a Heirloom extension and currently ignored.
  1756. .It Ic \&vpt Op Cm 1 | 0
  1757. Enable or disable vertical position traps.
  1758. This is a groff extension and currently ignored.
  1759. .It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
  1760. Change vertical spacing.
  1761. Currently ignored.
  1762. .It Ic \&warn Ar flags
  1763. Set warning level.
  1764. Currently ignored.
  1765. .It Ic \&warnscale Ar si
  1766. Set the scaling indicator used in warnings.
  1767. This is a groff extension and currently ignored.
  1768. .It Ic \&watch Ar macroname
  1769. Notify on change of string or macro.
  1770. This is a Heirloom extension and currently ignored.
  1771. .It Ic \&watchlength Ar maxlength
  1772. On change, report the contents of macros and strings
  1773. up to the specified length.
  1774. This is a Heirloom extension and currently ignored.
  1775. .It Ic \&watchn Ar register
  1776. Notify on change of register.
  1777. This is a Heirloom extension and currently ignored.
  1778. .It Ic \&wh Ar dist Op Ar macroname
  1779. Set a page location trap.
  1780. Currently unsupported.
  1781. .It Ic \&while Ar condition body
  1782. Repeated execution while a
  1783. .Ar condition
  1784. is true, with syntax similar to
  1785. .Ic \&if .
  1786. Currently implemented with two restrictions: cannot nest,
  1787. and each loop must start and end in the same scope.
  1788. .It Ic \&write Oo \(dq Oc Ns Ar string
  1789. Write to an open file.
  1790. Ignored because insecure.
  1791. .It Ic \&writec Oo \(dq Oc Ns Ar string
  1792. Write to an open file without appending a newline.
  1793. Ignored because insecure.
  1794. .It Ic \&writem Ar macroname
  1795. Write macro or string to an open file.
  1796. Ignored because insecure.
  1797. .It Ic \&xflag Ar level
  1798. Set the extension level.
  1799. This is a Heirloom extension and currently ignored.
  1800. .El
  1801. .Ss Numerical expressions
  1802. The
  1803. .Ic \&nr ,
  1804. .Ic \&if ,
  1805. and
  1806. .Ic \&ie
  1807. requests accept integer numerical expressions as arguments.
  1808. These are always evaluated using the C
  1809. .Vt int
  1810. type; integer overflow works the same way as in the C language.
  1811. Numbers consist of an arbitrary number of digits
  1812. .Sq 0
  1813. to
  1814. .Sq 9
  1815. prefixed by an optional sign
  1816. .Sq +
  1817. or
  1818. .Sq - .
  1819. Each number may be followed by one optional scaling unit described below
  1820. .Sx Scaling Widths .
  1821. The following equations hold:
  1822. .Bd -literal -offset indent
  1823. 1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240
  1824. 254c = 100i = 24000u = 24000
  1825. 1f = 65536u = 65536
  1826. .Ed
  1827. .Pp
  1828. The following binary operators are implemented.
  1829. Unless otherwise stated, they behave as in the C language:
  1830. .Pp
  1831. .Bl -tag -width 2n -compact
  1832. .It Ic +
  1833. addition
  1834. .It Ic -
  1835. subtraction
  1836. .It Ic *
  1837. multiplication
  1838. .It Ic /
  1839. division
  1840. .It Ic %
  1841. remainder of division
  1842. .It Ic <
  1843. less than
  1844. .It Ic >
  1845. greater than
  1846. .It Ic ==
  1847. equal to
  1848. .It Ic =
  1849. equal to, same effect as
  1850. .Ic ==
  1851. (this differs from C)
  1852. .It Ic <=
  1853. less than or equal to
  1854. .It Ic >=
  1855. greater than or equal to
  1856. .It Ic <>
  1857. not equal to (corresponds to C
  1858. .Ic != ;
  1859. this one is of limited portability, it is supported by Heirloom roff,
  1860. but not by groff)
  1861. .It Ic &
  1862. logical and (corresponds to C
  1863. .Ic && )
  1864. .It Ic \&:
  1865. logical or (corresponds to C
  1866. .Ic || )
  1867. .It Ic <?
  1868. minimum (not available in C)
  1869. .It Ic >?
  1870. maximum (not available in C)
  1871. .El
  1872. .Pp
  1873. There is no concept of precedence; evaluation proceeds from left to right,
  1874. except when subexpressions are enclosed in parentheses.
  1875. Inside parentheses, whitespace is ignored.
  1876. .Sh ESCAPE SEQUENCE REFERENCE
  1877. The
  1878. .Xr mandoc 1
  1879. .Nm
  1880. parser recognises the following escape sequences.
  1881. In
  1882. .Xr mdoc 7
  1883. and
  1884. .Xr man 7
  1885. documents, using escape sequences is discouraged except for those
  1886. described in the
  1887. .Sx LANGUAGE SYNTAX
  1888. section above.
  1889. .Pp
  1890. A backslash followed by any character not listed here
  1891. simply prints that character itself.
  1892. .Bl -tag -width Ds
  1893. .It Ic \e<newline>
  1894. A backslash at the end of an input line can be used to continue the
  1895. logical input line on the next physical input line, joining the text
  1896. on both lines together as if it were on a single input line.
  1897. .It Ic \e<space>
  1898. The escape sequence backslash-space
  1899. .Pq Sq \e\ \&
  1900. is an unpaddable space-sized non-breaking space character; see
  1901. .Sx Whitespace
  1902. and
  1903. .Xr mandoc_char 7 .
  1904. .It Ic \e!
  1905. Embed text up to and including the end of the input line into the
  1906. current diversion or into intermediate output without interpreting
  1907. requests, macros, and escapes.
  1908. Currently unsupported.
  1909. .It Ic \e\(dq
  1910. The rest of the input line is treated as
  1911. .Sx Comments .
  1912. .It Ic \e#
  1913. Line continuation with comment.
  1914. Discard the rest of the physical input line and continue the logical
  1915. input line on the next physical input line, joining the text on
  1916. both lines together as if it were on a single input line.
  1917. This is a groff extension.
  1918. .It Ic \e$ Ns Ar arg
  1919. Macro argument expansion, see
  1920. .Ic \&de .
  1921. .It Ic \e%
  1922. Hyphenation allowed at this point of the word; ignored by
  1923. .Xr mandoc 1 .
  1924. .It Ic \e&
  1925. Non-printing zero-width character,
  1926. often used for various kinds of escaping; see
  1927. .Sx Whitespace ,
  1928. .Xr mandoc_char 7 ,
  1929. and the
  1930. .Dq MACRO SYNTAX
  1931. and
  1932. .Dq Delimiters
  1933. sections in
  1934. .Xr mdoc 7 .
  1935. .It Ic \e\(aq
  1936. Acute accent special character; use
  1937. .Ic \e(aa
  1938. instead.
  1939. .It Ic \e( Ns Ar cc
  1940. .Sx Special Characters
  1941. with two-letter names, see
  1942. .Xr mandoc_char 7 .
  1943. .It Ic \e)
  1944. Zero-width space transparent to end-of-sentence detection;
  1945. ignored by
  1946. .Xr mandoc 1 .
  1947. .It Ic \e*[ Ns Ar name Ns Ic \&]
  1948. Interpolate the string with the
  1949. .Ar name .
  1950. For short names, there are variants
  1951. .Ic \e* Ns Ar c
  1952. and
  1953. .Ic \e*( Ns Ar cc .
  1954. .Pp
  1955. One string is predefined on the
  1956. .Nm
  1957. language level:
  1958. .Ic \e*(.T
  1959. expands to the name of the output device,
  1960. for example ascii, utf8, ps, pdf, html, or markdown.
  1961. .Pp
  1962. Macro sets traditionally predefine additional strings which are not
  1963. portable and differ across implementations.
  1964. Those supported by
  1965. .Xr mandoc 1
  1966. are listed in
  1967. .Xr mandoc_char 7 .
  1968. .Pp
  1969. Strings can be defined, changed, and deleted with the
  1970. .Ic \&ds ,
  1971. .Ic \&as ,
  1972. and
  1973. .Ic \&rm
  1974. requests.
  1975. .It Ic \e,
  1976. Left italic correction (groff extension); ignored by
  1977. .Xr mandoc 1 .
  1978. .It Ic \e-
  1979. Special character
  1980. .Dq mathematical minus sign ;
  1981. see
  1982. .Xr mandoc_char 7
  1983. for details.
  1984. .It Ic \e/
  1985. Right italic correction (groff extension); ignored by
  1986. .Xr mandoc 1 .
  1987. .It Ic \e:
  1988. Breaking the line is allowed at this point of the word
  1989. without inserting a hyphen.
  1990. .It Ic \e?
  1991. Embed the text up to the next
  1992. .Ic \e?
  1993. into the current diversion without interpreting requests, macros,
  1994. and escapes.
  1995. This is a groff extension and currently unsupported.
  1996. .It Ic \e[ Ns Ar name Ns Ic \&]
  1997. .Sx Special Characters
  1998. with names of arbitrary length, see
  1999. .Xr mandoc_char 7 .
  2000. .It Ic \e^
  2001. One-twelfth em half-narrow space character, effectively zero-width in
  2002. .Xr mandoc 1 .
  2003. .It Ic \e_
  2004. Underline special character; use
  2005. .Ic \e(ul
  2006. instead.
  2007. .It Ic \e`
  2008. Grave accent special character; use
  2009. .Ic \e(ga
  2010. instead.
  2011. .It Ic \e{
  2012. Begin conditional input; see
  2013. .Ic \&if .
  2014. .It Ic \e\(ba
  2015. One-sixth em narrow space character, effectively zero-width in
  2016. .Xr mandoc 1 .
  2017. .It Ic \e}
  2018. End conditional input; see
  2019. .Ic \&if .
  2020. .It Ic \e~
  2021. Paddable non-breaking space character.
  2022. .It Ic \e0
  2023. Digit width space character.
  2024. .It Ic \eA\(aq Ns Ar string Ns Ic \(aq
  2025. Anchor definition; ignored by
  2026. .Xr mandoc 1 .
  2027. .It Ic \ea
  2028. Leader character; ignored by
  2029. .Xr mandoc 1 .
  2030. .It Ic \eB\(aq Ns Ar string Ns Ic \(aq
  2031. Interpolate
  2032. .Sq 1
  2033. if
  2034. .Ar string
  2035. conforms to the syntax of
  2036. .Sx Numerical expressions
  2037. explained above or
  2038. .Sq 0
  2039. otherwise.
  2040. .It Ic \eb\(aq Ns Ar string Ns Ic \(aq
  2041. Bracket building function; ignored by
  2042. .Xr mandoc 1 .
  2043. .It Ic \eC\(aq Ns Ar name Ns Ic \(aq
  2044. .Sx Special Characters
  2045. with names of arbitrary length.
  2046. .It Ic \ec
  2047. When encountered at the end of an input text line,
  2048. the next input text line is considered to continue that line,
  2049. even if there are request or macro lines in between.
  2050. No whitespace is inserted.
  2051. .It Ic \eD\(aq Ns Ar string Ns Ic \(aq
  2052. Draw graphics function; ignored by
  2053. .Xr mandoc 1 .
  2054. .It Ic \ed
  2055. Move down by half a line; ignored by
  2056. .Xr mandoc 1 .
  2057. .It Ic \eE
  2058. Escape character intended to not be interpreted in copy mode.
  2059. In
  2060. .Xr mandoc 1 ,
  2061. it currently does the same as
  2062. .Ic \e
  2063. itself.
  2064. .It Ic \ee
  2065. Backslash special character.
  2066. .It Ic \eF[ Ns Ar name Ns Ic \&]
  2067. Switch font family (groff extension); ignored by
  2068. .Xr mandoc 1 .
  2069. For short names, there are variants
  2070. .Ic \eF Ns Ar c
  2071. and
  2072. .Ic \eF( Ns Ar cc .
  2073. .It Ic \ef[ Ns Ar name Ns Ic \&]
  2074. Switch to the font
  2075. .Ar name ,
  2076. see
  2077. .Sx Font Selection .
  2078. For short names, there are variants
  2079. .Ic \ef Ns Ar c
  2080. and
  2081. .Ic \ef( Ns Ar cc .
  2082. An empty name
  2083. .Ic \ef[]
  2084. defaults to
  2085. .Ic \efP .
  2086. .It Ic \eg[ Ns Ar name Ns Ic \&]
  2087. Interpolate the format of a number register; ignored by
  2088. .Xr mandoc 1 .
  2089. For short names, there are variants
  2090. .Ic \eg Ns Ar c
  2091. and
  2092. .Ic \eg( Ns Ar cc .
  2093. .It Ic \eH\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq
  2094. Set the height of the current font; ignored by
  2095. .Xr mandoc 1 .
  2096. .It Ic \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns Ic \(aq
  2097. Horizontal motion.
  2098. If the vertical bar is given, the motion is relative to the current
  2099. indentation.
  2100. Otherwise, it is relative to the current position.
  2101. The default scaling unit is
  2102. .Cm m .
  2103. .It Ic \ek[ Ns Ar name Ns Ic \&]
  2104. Mark horizontal input place in register; ignored by
  2105. .Xr mandoc 1 .
  2106. For short names, there are variants
  2107. .Ic \ek Ns Ar c
  2108. and
  2109. .Ic \ek( Ns Ar cc .
  2110. .It Ic \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns Ic \(aq
  2111. Vertical line drawing function; ignored by
  2112. .Xr mandoc 1 .
  2113. .It Ic \el\(aq Ns Ar width Ns Oo Ar c Oc Ns Ic \(aq
  2114. Draw a horizontal line of
  2115. .Ar width
  2116. using the glyph
  2117. .Ar c .
  2118. .It Ic \eM[ Ns Ar name Ns Ic \&]
  2119. Set fill (background) color (groff extension); ignored by
  2120. .Xr mandoc 1 .
  2121. For short names, there are variants
  2122. .Ic \eM Ns Ar c
  2123. and
  2124. .Ic \eM( Ns Ar cc .
  2125. .It Ic \em[ Ns Ar name Ns Ic \&]
  2126. Set glyph drawing color (groff extension); ignored by
  2127. .Xr mandoc 1 .
  2128. For short names, there are variants
  2129. .Ic \em Ns Ar c
  2130. and
  2131. .Ic \em( Ns Ar cc .
  2132. .It Ic \eN\(aq Ns Ar number Ns Ic \(aq
  2133. Character
  2134. .Ar number
  2135. on the current font.
  2136. .It Ic \en Ns Oo +|- Oc Ns Ic \&[ Ns Ar name Ns Ic \&]
  2137. Interpolate the number register
  2138. .Ar name .
  2139. For short names, there are variants
  2140. .Ic \en Ns Ar c
  2141. and
  2142. .Ic \en( Ns Ar cc .
  2143. If the optional sign is specified,
  2144. the register is first incremented or decremented by the
  2145. .Ar stepsize
  2146. that was specified in the relevant
  2147. .Ic \&nr
  2148. request, and the changed value is interpolated.
  2149. .It Ic \eO Ns Ar digit , Ic \eO[5 Ns arguments Ns Ic \&]
  2150. Suppress output.
  2151. This is a groff extension and currently unsupported.
  2152. With an argument of
  2153. .Ic 1 , 2 , 3 ,
  2154. or
  2155. .Ic 4 ,
  2156. it is ignored.
  2157. .It Ic \eo\(aq Ns Ar string Ns Ic \(aq
  2158. Overstrike, writing all the characters contained in the
  2159. .Ar string
  2160. to the same output position.
  2161. In terminal and HTML output modes,
  2162. only the last one of the characters is visible.
  2163. .It Ic \ep
  2164. Break the output line at the end of the current word.
  2165. .It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq
  2166. Set number register; ignored by
  2167. .Xr mandoc 1 .
  2168. .It Ic \er
  2169. Move up by one line; ignored by
  2170. .Xr mandoc 1 .
  2171. .It Ic \eS\(aq Ns Ar number Ns Ic \(aq
  2172. Slant output; ignored by
  2173. .Xr mandoc 1 .
  2174. .It Ic \es\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq
  2175. Change point size; ignored by
  2176. .Xr mandoc 1 .
  2177. Alternative forms
  2178. .Ic \es Ns Oo +|- Oc Ns Ar n ,
  2179. .Ic \es Ns Oo +|- Oc Ns Ic \(aq Ns Ar number Ns Ic \(aq ,
  2180. .Ic \es[ Ns Oo +|- Oc Ns Ar number Ns Ic \&] ,
  2181. and
  2182. .Ic \es Ns Oo +|- Oc Ns Ic \&[ Ns Ar number Ns Ic \&]
  2183. are also parsed and ignored.
  2184. .It Ic \et
  2185. Horizontal tab; ignored by
  2186. .Xr mandoc 1 .
  2187. .It Ic \eu
  2188. Move up by half a line; ignored by
  2189. .Xr mandoc 1 .
  2190. .It Ic \eV[ Ns Ar name Ns Ic \&]
  2191. Interpolate an environment variable; ignored by
  2192. .Xr mandoc 1 .
  2193. For short names, there are variants
  2194. .Ic \eV Ns Ar c
  2195. and
  2196. .Ic \eV( Ns Ar cc .
  2197. .It Ic \ev\(aq Ns Ar number Ns Ic \(aq
  2198. Vertical motion; ignored by
  2199. .Xr mandoc 1 .
  2200. .It Ic \ew\(aq Ns Ar string Ns Ic \(aq
  2201. Interpolate the width of the
  2202. .Ar string .
  2203. The
  2204. .Xr mandoc 1
  2205. implementation assumes that after expansion of user-defined strings, the
  2206. .Ar string
  2207. only contains normal characters, no escape sequences, and that each
  2208. character has a width of 24 basic units.
  2209. .It Ic \eX\(aq Ns Ar string Ns Ic \(aq
  2210. Output
  2211. .Ar string
  2212. as device control function; ignored in nroff mode and by
  2213. .Xr mandoc 1 .
  2214. .It Ic \ex\(aq Ns Ar number Ns Ic \(aq
  2215. Extra line space function; ignored by
  2216. .Xr mandoc 1 .
  2217. .It Ic \eY[ Ns Ar name Ns Ic \&]
  2218. Output a string as a device control function; ignored in nroff mode and by
  2219. .Xr mandoc 1 .
  2220. For short names, there are variants
  2221. .Ic \eY Ns Ar c
  2222. and
  2223. .Ic \eY( Ns Ar cc .
  2224. .It Ic \eZ\(aq Ns Ar string Ns Ic \(aq
  2225. Print
  2226. .Ar string
  2227. with zero width and height; ignored by
  2228. .Xr mandoc 1 .
  2229. .It Ic \ez
  2230. Output the next character without advancing the cursor position.
  2231. .El
  2232. .Sh COMPATIBILITY
  2233. The
  2234. .Xr mandoc 1
  2235. implementation of the
  2236. .Nm
  2237. language is incomplete.
  2238. Major unimplemented features include:
  2239. .Pp
  2240. .Bl -dash -compact
  2241. .It
  2242. For security reasons,
  2243. .Xr mandoc 1
  2244. never reads or writes external files except via
  2245. .Ic \&so
  2246. requests with safe relative paths.
  2247. .It
  2248. There is no automatic hyphenation, no adjustment to the right margin,
  2249. and very limited support for centering; the output is always set flush-left.
  2250. .It
  2251. Support for setting tabulator and leader characters is missing,
  2252. and support for manually changing indentation is limited.
  2253. .It
  2254. The
  2255. .Sq u
  2256. scaling unit is the default terminal unit.
  2257. In traditional troff systems, this unit changes depending on the
  2258. output media.
  2259. .It
  2260. Width measurements are implemented in a crude way
  2261. and often yield wrong results.
  2262. Support for explicit movement requests and escapes is limited.
  2263. .It
  2264. There is no concept of output pages, no support for floats,
  2265. graphics drawing, and picture inclusion;
  2266. terminal output is always continuous.
  2267. .It
  2268. Requests regarding color, font families, font sizes,
  2269. and glyph manipulation are ignored.
  2270. Font support is very limited.
  2271. Kerning is not implemented, and no ligatures are produced.
  2272. .It
  2273. The
  2274. .Qq \(aq
  2275. macro control character does not suppress output line breaks.
  2276. .It
  2277. Diversions and environments are not implemented,
  2278. and support for traps is very incomplete.
  2279. .It
  2280. Use of macros is not supported inside
  2281. .Xr tbl 7
  2282. code.
  2283. .El
  2284. .Pp
  2285. The special semantics of the
  2286. .Cm nS
  2287. number register is an idiosyncrasy of
  2288. .Ox
  2289. manuals and not supported by other
  2290. .Xr mdoc 7
  2291. implementations.
  2292. .Sh SEE ALSO
  2293. .Xr mandoc 1 ,
  2294. .Xr eqn 7 ,
  2295. .Xr man 7 ,
  2296. .Xr mandoc_char 7 ,
  2297. .Xr mdoc 7 ,
  2298. .Xr tbl 7
  2299. .Rs
  2300. .%A Joseph F. Ossanna
  2301. .%A Brian W. Kernighan
  2302. .%I AT&T Bell Laboratories
  2303. .%T Troff User's Manual
  2304. .%R Computing Science Technical Report
  2305. .%N 54
  2306. .%C Murray Hill, New Jersey
  2307. .%D 1976 and 1992
  2308. .%U http://www.kohala.com/start/troff/cstr54.ps
  2309. .Re
  2310. .Rs
  2311. .%A Joseph F. Ossanna
  2312. .%A Brian W. Kernighan
  2313. .%A Gunnar Ritter
  2314. .%T Heirloom Documentation Tools Nroff/Troff User's Manual
  2315. .%D September 17, 2007
  2316. .%U http://heirloom.sourceforge.net/doctools/troff.pdf
  2317. .Re
  2318. .Sh HISTORY
  2319. The RUNOFF typesetting system, whose input forms the basis for
  2320. .Nm ,
  2321. was written in MAD and FAP for the CTSS operating system by Jerome E.
  2322. Saltzer in 1964.
  2323. Doug McIlroy rewrote it in BCPL in 1969, renaming it
  2324. .Nm .
  2325. Dennis M. Ritchie rewrote McIlroy's
  2326. .Nm
  2327. in PDP-11 assembly for
  2328. .At v1 ,
  2329. Joseph F. Ossanna improved roff and renamed it nroff
  2330. for
  2331. .At v2 ,
  2332. then ported nroff to C as troff, which Brian W. Kernighan released with
  2333. .At v7 .
  2334. In 1989, James Clark re-implemented troff in C++, naming it groff.
  2335. .Sh AUTHORS
  2336. .An -nosplit
  2337. This
  2338. .Nm
  2339. reference was written by
  2340. .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
  2341. and
  2342. .An Ingo Schwarze Aq Mt schwarze@openbsd.org .