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