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