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