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