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