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