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