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