Annotation of mandoc/roff.7, Revision 1.62
1.62 ! schwarze 1: .\" $Id: roff.7,v 1.61 2014/12/25 17:23:32 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.62 ! schwarze 18: .Dd $Mdocdate: December 25 2014 $
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.17 schwarze 398: Note that the
1.15 kristaps 399: .Nm
1.17 schwarze 400: language defines many more requests not implemented in
1.15 kristaps 401: .Xr mandoc 1 .
402: .Ss \&ad
403: Set line adjustment mode.
404: This line-scoped request is intended to have one argument to select
1.62 ! schwarze 405: normal, left, right, or center adjustment for subsequent text.
1.15 kristaps 406: Currently, it is ignored including its arguments,
407: and the number of arguments is not checked.
1.3 kristaps 408: .Ss \&am
1.15 kristaps 409: Append to a macro definition.
410: The syntax of this request is the same as that of
411: .Sx \&de .
1.3 kristaps 412: .Ss \&ami
1.15 kristaps 413: Append to a macro definition, specifying the macro name indirectly.
414: The syntax of this request is the same as that of
415: .Sx \&dei .
1.3 kristaps 416: .Ss \&am1
1.15 kristaps 417: Append to a macro definition, switching roff compatibility mode off
418: during macro execution.
419: The syntax of this request is the same as that of
420: .Sx \&de1 .
1.55 schwarze 421: Since
422: .Xr mandoc 1
423: does not implement
424: .Nm
425: compatibility mode at all, it handles this request as an alias for
426: .Sx \&am .
1.47 schwarze 427: .Ss \&as
428: Append to a user-defined string.
429: The syntax of this request is the same as that of
430: .Sx \&ds .
431: If a user-defined string with the specified name does not yet exist,
432: it is set to the empty string before appending.
1.39 kristaps 433: .Ss \&cc
434: Changes the control character.
435: Its syntax is as follows:
436: .Bd -literal -offset indent
437: .Pf . Cm \&cc Op Ar c
438: .Ed
439: .Pp
440: If
441: .Ar c
442: is not specified, the control character is reset to
443: .Sq \&. .
444: Trailing characters are ignored.
1.47 schwarze 445: .Ss \&ce
446: Center some lines.
447: This line-scoped request is intended to take one integer argument,
448: specifying how many lines to center.
449: Currently, it is ignored including its arguments, and the number
450: of arguments is not checked.
1.3 kristaps 451: .Ss \&de
1.17 schwarze 452: Define a
1.15 kristaps 453: .Nm
454: macro.
455: Its syntax can be either
456: .Bd -literal -offset indent
457: .Pf . Cm \&de Ar name
458: .Ar macro definition
459: \&..
460: .Ed
461: .Pp
462: or
463: .Bd -literal -offset indent
464: .Pf . Cm \&de Ar name Ar end
465: .Ar macro definition
466: .Pf . Ar end
467: .Ed
468: .Pp
469: Both forms define or redefine the macro
470: .Ar name
471: to represent the
472: .Ar macro definition ,
473: which may consist of one or more input lines, including the newline
474: characters terminating each line, optionally containing calls to
475: .Nm
476: requests,
477: .Nm
478: macros or high-level macros like
479: .Xr man 7
480: or
481: .Xr mdoc 7
482: macros, whichever applies to the document in question.
483: .Pp
484: Specifying a custom
485: .Ar end
486: macro works in the same way as for
487: .Sx \&ig ;
488: namely, the call to
489: .Sq Pf . Ar end
490: first ends the
491: .Ar macro definition ,
492: and after that, it is also evaluated as a
493: .Nm
494: request or
495: .Nm
496: macro, but not as a high-level macro.
497: .Pp
1.17 schwarze 498: The macro can be invoked later using the syntax
1.15 kristaps 499: .Pp
500: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
501: .Pp
1.24 schwarze 502: Regarding argument parsing, see
503: .Sx MACRO SYNTAX
504: above.
1.15 kristaps 505: .Pp
1.17 schwarze 506: The line invoking the macro will be replaced
1.15 kristaps 507: in the input stream by the
508: .Ar macro definition ,
509: replacing all occurrences of
510: .No \e\e$ Ns Ar N ,
1.17 schwarze 511: where
1.15 kristaps 512: .Ar N
513: is a digit, by the
514: .Ar N Ns th Ar argument .
515: For example,
516: .Bd -literal -offset indent
517: \&.de ZN
518: \efI\e^\e\e$1\e^\efP\e\e$2
519: \&..
520: \&.ZN XtFree .
521: .Ed
522: .Pp
523: produces
524: .Pp
525: .D1 \efI\e^XtFree\e^\efP.
526: .Pp
527: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
528: .Pp
1.17 schwarze 529: Since macros and user-defined strings share a common string table,
1.15 kristaps 530: defining a macro
531: .Ar name
532: clobbers the user-defined string
533: .Ar name ,
534: and the
535: .Ar macro definition
536: can also be printed using the
537: .Sq \e*
538: string interpolation syntax described below
539: .Sx ds ,
540: but this is rarely useful because every macro definition contains at least
541: one explicit newline character.
1.16 schwarze 542: .Pp
543: In order to prevent endless recursion, both groff and
544: .Xr mandoc 1
545: limit the stack depth for expanding macros and strings
1.61 schwarze 546: to a large, but finite number, and
547: .Xr mandoc 1
548: also limits the length of the expanded input line.
549: Do not rely on the exact values of these limits.
1.3 kristaps 550: .Ss \&dei
1.17 schwarze 551: Define a
1.15 kristaps 552: .Nm
553: macro, specifying the macro name indirectly.
1.17 schwarze 554: The syntax of this request is the same as that of
1.15 kristaps 555: .Sx \&de .
1.55 schwarze 556: The request
557: .Pp
558: .D1 Pf . Cm \&dei Ar name Op Ar end
559: .Pp
560: has the same effect as:
561: .Pp
562: .D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end
1.15 kristaps 563: .Ss \&de1
1.17 schwarze 564: Define a
1.15 kristaps 565: .Nm
566: macro that will be executed with
567: .Nm
568: compatibility mode switched off during macro execution.
569: This is a GNU extension not available in traditional
570: .Nm
571: implementations and not even in older versions of groff.
572: Since
573: .Xr mandoc 1
574: does not implement
575: .Nm
1.17 schwarze 576: compatibility mode at all, it handles this request as an alias for
1.15 kristaps 577: .Sx \&de .
1.6 schwarze 578: .Ss \&ds
1.15 kristaps 579: Define a user-defined string.
1.13 kristaps 580: Its syntax is as follows:
581: .Pp
1.15 kristaps 582: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13 kristaps 583: .Pp
584: The
1.15 kristaps 585: .Ar name
1.13 kristaps 586: and
1.15 kristaps 587: .Ar string
588: arguments are space-separated.
589: If the
590: .Ar string
591: begins with a double-quote character, that character will not be part
592: of the string.
593: All remaining characters on the input line form the
594: .Ar string ,
595: including whitespace and double-quote characters, even trailing ones.
596: .Pp
1.13 kristaps 597: The
1.15 kristaps 598: .Ar string
599: can be interpolated into subsequent text by using
600: .No \e* Ns Bq Ar name
601: for a
602: .Ar name
603: of arbitrary length, or \e*(NN or \e*N if the length of
604: .Ar name
605: is two or one characters, respectively.
1.17 schwarze 606: Interpolation can be prevented by escaping the leading backslash;
607: that is, an asterisk preceded by an even number of backslashes
608: does not trigger string interpolation.
1.15 kristaps 609: .Pp
610: Since user-defined strings and macros share a common string table,
611: defining a string
612: .Ar name
1.17 schwarze 613: clobbers the macro
1.15 kristaps 614: .Ar name ,
615: and the
616: .Ar name
617: used for defining a string can also be invoked as a macro,
618: in which case the following input line will be appended to the
619: .Ar string ,
620: forming a new input line passed to the
621: .Nm
622: parser.
623: For example,
624: .Bd -literal -offset indent
625: \&.ds badidea .S
626: \&.badidea
627: H SYNOPSIS
628: .Ed
629: .Pp
630: invokes the
631: .Cm SH
632: macro when used in a
633: .Xr man 7
634: document.
635: Such abuse is of course strongly discouraged.
1.5 kristaps 636: .Ss \&el
637: The
638: .Qq else
639: half of an if/else conditional.
640: Pops a result off the stack of conditional evaluations pushed by
641: .Sx \&ie
642: and uses it as its conditional.
643: If no stack entries are present (e.g., due to no prior
644: .Sx \&ie
645: calls)
646: then false is assumed.
1.17 schwarze 647: The syntax of this request is similar to
1.5 kristaps 648: .Sx \&if
649: except that the conditional is missing.
1.27 kristaps 650: .Ss \&EN
651: End an equation block.
652: See
653: .Sx \&EQ .
654: .Ss \&EQ
655: Begin an equation block.
656: See
657: .Xr eqn 7
658: for a description of the equation language.
1.43 schwarze 659: .Ss \&fam
660: Change the font family.
661: This line-scoped request is intended to have one argument specifying
662: the font family to be selected.
663: It is a groff extension, and currently, it is ignored including its
664: arguments, and the number of arguments is not checked.
1.49 schwarze 665: .Ss \&ft
666: Change the font.
667: Its syntax is as follows:
668: .Pp
669: .D1 Pf . Cm \&ft Op Ar font
670: .Pp
671: The following
672: .Ar font
673: arguments are supported:
674: .Bl -tag -width 4n -offset indent
675: .It Cm B , BI , 3 , 4
676: switches to
677: .Sy bold
678: font
679: .It Cm I , 2
680: switches to
681: .Em underlined
682: font
683: .It Cm R , CW , 1
684: switches to normal font
685: .It Cm P No "or no argument"
686: switches back to the previous font
687: .El
688: .Pp
689: This request takes effect only locally, may be overridden by macros
690: and escape sequences, and is only supported in
691: .Xr man 7
692: for now.
1.44 schwarze 693: .Ss \&hw
694: Specify hyphenation points in words.
695: This line-scoped request is currently ignored.
1.15 kristaps 696: .Ss \&hy
697: Set automatic hyphenation mode.
698: This line-scoped request is currently ignored.
1.5 kristaps 699: .Ss \&ie
700: The
701: .Qq if
702: half of an if/else conditional.
703: The result of the conditional is pushed into a stack used by subsequent
704: invocations of
705: .Sx \&el ,
706: which may be separated by any intervening input (or not exist at all).
707: Its syntax is equivalent to
708: .Sx \&if .
1.1 kristaps 709: .Ss \&if
1.7 schwarze 710: Begins a conditional.
1.48 schwarze 711: This request has the following syntax:
712: .Bd -literal -offset indent
713: \&.if COND BODY
714: .Ed
715: .Bd -literal -offset indent
716: \&.if COND \e{BODY
717: BODY...\e}
718: .Ed
719: .Bd -literal -offset indent
720: \&.if COND \e{\e
721: BODY...
722: \&.\e}
723: .Ed
724: .Pp
725: COND is a conditional statement.
726: Currently,
727: .Xr mandoc 1
728: supports the following subset of roff conditionals:
729: .Bl -bullet
730: .It
731: If
732: .Sq \&!
733: is prefixed to COND, the condition is logically inverted.
734: .It
735: If the first character of COND is
736: .Sq n
737: .Pq nroff mode
738: or
739: .Sq o
740: .Pq odd page ,
741: COND evaluates to true.
742: .It
743: If the first character of COND is
744: .Sq c
745: .Pq character available ,
746: .Sq d
747: .Pq string defined ,
748: .Sq e
749: .Pq even page ,
750: .Sq r
751: .Pq register accessed ,
752: .Sq t
753: .Pq troff mode ,
1.59 schwarze 754: or
755: .Sq v
756: .Pq vroff mode ,
1.48 schwarze 757: COND evaluates to false.
758: .It
1.53 schwarze 759: If COND starts with a parenthesis or with an optionally signed
760: integer number, it is evaluated according to the rules of
761: .Sx Numerical expressions
762: explained below.
1.57 schwarze 763: It evaluates to true if the result is positive,
1.53 schwarze 764: or to false if the result is zero or negative.
1.48 schwarze 765: .It
766: Otherwise, the first character of COND is regarded as a delimiter
767: and COND evaluates to true if the string extending from its first
768: to its second occurrence is equal to the string extending from its
769: second to its third occurrence.
770: .It
771: If COND cannot be parsed, it evaluates to false.
772: .El
773: .Pp
1.3 kristaps 774: If a conditional is false, its children are not processed, but are
775: syntactically interpreted to preserve the integrity of the input
776: document.
777: Thus,
778: .Pp
1.17 schwarze 779: .D1 \&.if t .ig
1.3 kristaps 780: .Pp
781: will discard the
782: .Sq \&.ig ,
783: which may lead to interesting results, but
784: .Pp
1.17 schwarze 785: .D1 \&.if t .if t \e{\e
1.3 kristaps 786: .Pp
787: will continue to syntactically interpret to the block close of the final
788: conditional.
789: Sub-conditionals, in this case, obviously inherit the truth value of
790: the parent.
1.1 kristaps 791: .Pp
792: If the BODY section is begun by an escaped brace
793: .Sq \e{ ,
1.48 schwarze 794: scope continues until the end of the input line containing the
795: matching closing-brace escape sequence
796: .Sq \e} .
1.17 schwarze 797: If the BODY is not enclosed in braces, scope continues until
798: the end of the line.
1.1 kristaps 799: If the COND is followed by a BODY on the same line, whether after a
1.17 schwarze 800: brace or not, then requests and macros
1.1 kristaps 801: .Em must
802: begin with a control character.
803: It is generally more intuitive, in this case, to write
804: .Bd -literal -offset indent
805: \&.if COND \e{\e
806: \&.foo
807: bar
808: \&.\e}
809: .Ed
810: .Pp
1.17 schwarze 811: than having the request or macro follow as
1.1 kristaps 812: .Pp
813: .D1 \&.if COND \e{ .foo
814: .Pp
815: The scope of a conditional is always parsed, but only executed if the
816: conditional evaluates to true.
817: .Pp
1.29 kristaps 818: Note that the
1.1 kristaps 819: .Sq \e}
1.29 kristaps 820: is converted into a zero-width escape sequence if not passed as a
821: standalone macro
822: .Sq \&.\e} .
823: For example,
824: .Pp
825: .D1 \&.Fl a \e} b
826: .Pp
827: will result in
1.8 kristaps 828: .Sq \e}
1.29 kristaps 829: being considered an argument of the
830: .Sq \&Fl
831: macro.
1.1 kristaps 832: .Ss \&ig
1.2 kristaps 833: Ignore input.
1.15 kristaps 834: Its syntax can be either
835: .Bd -literal -offset indent
836: .Pf . Cm \&ig
837: .Ar ignored text
1.2 kristaps 838: \&..
839: .Ed
1.15 kristaps 840: .Pp
841: or
842: .Bd -literal -offset indent
843: .Pf . Cm \&ig Ar end
844: .Ar ignored text
845: .Pf . Ar end
1.2 kristaps 846: .Ed
847: .Pp
848: In the first case, input is ignored until a
849: .Sq \&..
1.17 schwarze 850: request is encountered on its own line.
1.15 kristaps 851: In the second case, input is ignored until the specified
852: .Sq Pf . Ar end
853: macro is encountered.
854: Do not use the escape character
1.2 kristaps 855: .Sq \e
1.15 kristaps 856: anywhere in the definition of
857: .Ar end ;
858: it would cause very strange behaviour.
859: .Pp
860: When the
861: .Ar end
862: macro is a roff request or a roff macro, like in
1.2 kristaps 863: .Pp
864: .D1 \&.ig if
865: .Pp
866: the subsequent invocation of
867: .Sx \&if
1.15 kristaps 868: will first terminate the
869: .Ar ignored text ,
870: then be invoked as usual.
871: Otherwise, it only terminates the
872: .Ar ignored text ,
873: and arguments following it or the
874: .Sq \&..
1.17 schwarze 875: request are discarded.
1.50 schwarze 876: .Ss \&ll
877: Change the output line length.
878: Its syntax is as follows:
879: .Pp
1.51 schwarze 880: .D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width
1.50 schwarze 881: .Pp
882: If the
883: .Ar width
884: argument is omitted, the line length is reset to its previous value.
885: The default setting for terminal output is 78n.
1.51 schwarze 886: If a sign is given, the line length is added to or subtracted from;
887: otherwise, it is set to the provided value.
1.50 schwarze 888: Using this request in new manuals is discouraged for several reasons,
889: among others because it overrides the
890: .Xr mandoc 1
891: .Fl O Cm width
892: command line option.
1.15 kristaps 893: .Ss \&ne
894: Declare the need for the specified minimum vertical space
895: before the next trap or the bottom of the page.
896: This line-scoped request is currently ignored.
897: .Ss \&nh
898: Turn off automatic hyphenation mode.
899: This line-scoped request is currently ignored.
1.10 kristaps 900: .Ss \&nr
1.45 schwarze 901: Define or change a register.
1.10 kristaps 902: A register is an arbitrary string value that defines some sort of state,
903: which influences parsing and/or formatting.
904: Its syntax is as follows:
905: .Pp
1.53 schwarze 906: .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression
1.10 kristaps 907: .Pp
1.53 schwarze 908: For the syntax of
909: .Ar expression ,
910: see
911: .Sx Numerical expressions
912: below.
1.46 schwarze 913: If it is prefixed by a sign, the register will be
1.45 schwarze 914: incremented or decremented instead of assigned to.
915: .Pp
916: The following register
1.15 kristaps 917: .Ar name
1.45 schwarze 918: is handled specially:
1.10 kristaps 919: .Bl -tag -width Ds
920: .It Cm nS
921: If set to a positive integer value, certain
922: .Xr mdoc 7
1.17 schwarze 923: macros will behave in the same way as in the
1.10 kristaps 924: .Em SYNOPSIS
1.11 kristaps 925: section.
1.17 schwarze 926: If set to 0, these macros will behave in the same way as outside the
927: .Em SYNOPSIS
928: section, even when called within the
1.10 kristaps 929: .Em SYNOPSIS
1.17 schwarze 930: section itself.
931: Note that starting a new
1.11 kristaps 932: .Xr mdoc 7
1.17 schwarze 933: section with the
934: .Cm \&Sh
935: macro will reset this register.
1.10 kristaps 936: .El
1.26 schwarze 937: .Ss \&ns
938: Turn on no-space mode.
939: This line-scoped request is intended to take no arguments.
1.58 schwarze 940: Currently, it is ignored including its arguments,
941: and the number of arguments is not checked.
942: .Ss \&pl
943: Change page length.
944: This line-scoped request is intended to take one height argument.
1.26 schwarze 945: Currently, it is ignored including its arguments,
946: and the number of arguments is not checked.
947: .Ss \&ps
948: Change point size.
949: This line-scoped request is intended to take one numerical argument.
950: Currently, it is ignored including its arguments,
951: and the number of arguments is not checked.
1.52 schwarze 952: .Ss \&rm
953: Remove a request, macro or string.
954: Its syntax is as follows:
955: .Pp
956: .D1 Pf \. Cm \&rm Ar name
957: .Ss \&rr
958: Remove a register.
959: Its syntax is as follows:
960: .Pp
961: .D1 Pf \. Cm \&rr Ar name
1.15 kristaps 962: .Ss \&so
963: Include a source file.
964: Its syntax is as follows:
965: .Pp
966: .D1 Pf \. Cm \&so Ar file
967: .Pp
968: The
969: .Ar file
970: will be read and its contents processed as input in place of the
971: .Sq \&.so
972: request line.
1.28 kristaps 973: To avoid inadvertent inclusion of unrelated files,
1.15 kristaps 974: .Xr mandoc 1
975: only accepts relative paths not containing the strings
976: .Qq ../
977: and
978: .Qq /.. .
1.37 schwarze 979: .Pp
980: This request requires
981: .Xr man 1
982: to change to the right directory before calling
983: .Xr mandoc 1 ,
984: per convention to the root of the manual tree.
985: Typical usage looks like:
986: .Pp
987: .Dl \&.so man3/Xcursor.3
988: .Pp
989: As the whole concept is rather fragile, the use of
990: .Sx \&so
991: is discouraged.
992: Use
993: .Xr ln 1
994: instead.
1.26 schwarze 995: .Ss \&ta
996: Set tab stops.
997: This line-scoped request can take an arbitrary number of arguments.
998: Currently, it is ignored including its arguments.
1.6 schwarze 999: .Ss \&tr
1000: Output character translation.
1.30 kristaps 1001: Its syntax is as follows:
1002: .Pp
1003: .D1 Pf \. Cm \&tr Ar [ab]+
1004: .Pp
1005: Pairs of
1006: .Ar ab
1007: characters are replaced
1008: .Ar ( a
1009: for
1010: .Ar b ) .
1011: Replacement (or origin) characters may also be character escapes; thus,
1012: .Pp
1013: .Dl tr \e(xx\e(yy
1014: .Pp
1015: replaces all invocations of \e(xx with \e(yy.
1.20 kristaps 1016: .Ss \&T&
1017: Re-start a table layout, retaining the options of the prior table
1018: invocation.
1019: See
1020: .Sx \&TS .
1021: .Ss \&TE
1022: End a table context.
1023: See
1024: .Sx \&TS .
1025: .Ss \&TS
1026: Begin a table, which formats input in aligned rows and columns.
1.23 kristaps 1027: See
1028: .Xr tbl 7
1029: for a description of the tbl language.
1.53 schwarze 1030: .Ss Numerical expressions
1031: The
1032: .Sx \&nr ,
1033: .Sx \&if ,
1034: and
1035: .Sx \&ie
1036: requests accept integer numerical expressions as arguments.
1037: These are always evaluated using the C
1038: .Vt int
1039: type; integer overflow works the same way as in the C language.
1040: Numbers consist of an arbitrary number of digits
1041: .Sq 0
1042: to
1043: .Sq 9
1044: prefixed by an optional sign
1045: .Sq +
1046: or
1047: .Sq - .
1048: .Pp
1049: The following binary operators are implemented.
1050: Unless otherwise stated, they behave as in the C language:
1051: .Pp
1052: .Bl -tag -width 2n -compact
1053: .It Ic +
1054: addition
1055: .It Ic -
1056: subtraction
1057: .It Ic *
1058: multiplication
1059: .It Ic /
1060: division
1061: .It Ic %
1062: remainder of division
1063: .It Ic <
1064: less than
1065: .It Ic >
1066: greater than
1067: .It Ic ==
1068: equal to
1069: .It Ic =
1070: equal to, same effect as
1071: .Ic ==
1072: (this differs from C)
1073: .It Ic <=
1074: less than or equal to
1075: .It Ic >=
1076: greater than or equal to
1077: .It Ic <>
1078: not equal to (corresponds to C
1079: .Ic != ;
1080: this one is of limited portability, it is supported by Heirloom roff,
1081: but not by groff)
1082: .It Ic &
1083: logical and (corresponds to C
1084: .Ic && )
1085: .It Ic \&:
1086: logical or (corresponds to C
1087: .Ic \&|| )
1088: .It Ic <?
1089: minimum (not available in C)
1090: .It Ic >?
1091: maximum (not available in C)
1092: .El
1093: .Pp
1094: There is no concept of precendence; evaluation proceeds from left to right,
1095: except when subexpressions are enclosed in parantheses.
1096: Inside parentheses, whitespace is ignored.
1.46 schwarze 1097: .Sh ESCAPE SEQUENCE REFERENCE
1098: The
1099: .Xr mandoc 1
1100: .Nm
1101: parser recognises the following escape sequences.
1102: Note that the
1103: .Nm
1104: language defines more escape sequences not implemented in
1105: .Xr mandoc 1 .
1106: In
1107: .Xr mdoc 7
1108: and
1109: .Xr man 7
1110: documents, using escape sequences is discouraged except for those
1111: described in the
1112: .Sx LANGUAGE SYNTAX
1113: section above.
1114: .Pp
1115: A backslash followed by any character not listed here
1116: simply prints that character itself.
1117: .Ss \e<newline>
1118: A backslash at the end of an input line can be used to continue the
1119: logical input line on the next physical input line, joining the text
1120: on both lines together as if it were on a single input line.
1121: .Ss \e<space>
1122: The escape sequence backslash-space
1123: .Pq Sq \e\ \&
1124: is an unpaddable space-sized non-breaking space character; see
1125: .Sx Whitespace .
1126: .Ss \e\(dq
1127: The rest of the input line is treated as
1128: .Sx Comments .
1129: .Ss \e%
1130: Hyphenation allowed at this point of the word; ignored by
1131: .Xr mandoc 1 .
1132: .Ss \e&
1133: Non-printing zero-width character; see
1134: .Sx Whitespace .
1135: .Ss \e\(aq
1136: Acute accent special character; use
1137: .Sq \e(aa
1138: instead.
1139: .Ss \e( Ns Ar cc
1140: .Sx Special Characters
1141: with two-letter names, see
1142: .Xr mandoc_char 7 .
1143: .Ss \e*[ Ns Ar name ]
1144: Interpolate the string with the
1145: .Ar name ;
1146: see
1147: .Sx Predefined Strings
1148: and
1149: .Sx ds .
1150: For short names, there are variants
1151: .No \e* Ns Ar c
1152: and
1153: .No \e*( Ns Ar cc .
1154: .Ss \e-
1155: Special character
1156: .Dq mathematical minus sign .
1157: .Ss \e[ Ns Ar name ]
1158: .Sx Special Characters
1159: with names of arbitrary length, see
1160: .Xr mandoc_char 7 .
1161: .Ss \e^
1162: One-twelfth em half-narrow space character, effectively zero-width in
1163: .Xr mandoc 1 .
1164: .Ss \e`
1165: Grave accent special character; use
1166: .Sq \e(ga
1167: instead.
1168: .Ss \e{
1169: Begin conditional input; see
1170: .Sx if .
1171: .Ss \e\(ba
1172: One-sixth em narrow space character, effectively zero-width in
1173: .Xr mandoc 1 .
1174: .Ss \e}
1175: End conditional input; see
1176: .Sx if .
1177: .Ss \e~
1178: Paddable non-breaking space character.
1179: .Ss \e0
1180: Digit width space character.
1181: .Ss \eA\(aq Ns Ar string Ns \(aq
1182: Anchor definition; ignored by
1183: .Xr mandoc 1 .
1184: .Ss \eB\(aq Ns Ar string Ns \(aq
1.54 schwarze 1185: Interpolate
1186: .Sq 1
1187: if
1.46 schwarze 1188: .Ar string
1.54 schwarze 1189: conforms to the syntax of
1190: .Sx Numerical expressions
1191: explained above and
1192: .Sq 0
1193: otherwise.
1.46 schwarze 1194: .Ss \eb\(aq Ns Ar string Ns \(aq
1195: Bracket building function; ignored by
1196: .Xr mandoc 1 .
1197: .Ss \eC\(aq Ns Ar name Ns \(aq
1198: .Sx Special Characters
1199: with names of arbitrary length.
1200: .Ss \ec
1.60 schwarze 1201: When encountered at the end of an input text line,
1202: the next input text line is considered to continue that line,
1203: even if there are request or macro lines in between.
1204: No whitespace is inserted.
1.46 schwarze 1205: .Ss \eD\(aq Ns Ar string Ns \(aq
1206: Draw graphics function; ignored by
1207: .Xr mandoc 1 .
1208: .Ss \ed
1209: Move down by half a line; ignored by
1210: .Xr mandoc 1 .
1211: .Ss \ee
1212: Backslash special character.
1213: .Ss \eF[ Ns Ar name ]
1214: Switch font family (groff extension); ignored by
1215: .Xr mandoc 1 .
1216: For short names, there are variants
1217: .No \eF Ns Ar c
1218: and
1219: .No \eF( Ns Ar cc .
1220: .Ss \ef[ Ns Ar name ]
1221: Switch to the font
1222: .Ar name ,
1223: see
1224: .Sx Text Decoration .
1225: For short names, there are variants
1226: .No \ef Ns Ar c
1227: and
1228: .No \ef( Ns Ar cc .
1229: .Ss \eg[ Ns Ar name ]
1230: Interpolate the format of a number register; ignored by
1231: .Xr mandoc 1 .
1232: For short names, there are variants
1233: .No \eg Ns Ar c
1234: and
1235: .No \eg( Ns Ar cc .
1236: .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
1237: Set the height of the current font; ignored by
1238: .Xr mandoc 1 .
1239: .Ss \eh\(aq Ns Ar number Ns \(aq
1240: Horizontal motion; ignored by
1241: .Xr mandoc 1 .
1242: .Ss \ek[ Ns Ar name ]
1243: Mark horizontal input place in register; ignored by
1244: .Xr mandoc 1 .
1245: For short names, there are variants
1246: .No \ek Ns Ar c
1247: and
1248: .No \ek( Ns Ar cc .
1249: .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
1250: Vertical line drawing function; ignored by
1251: .Xr mandoc 1 .
1252: .Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
1253: Horizontal line drawing function; ignored by
1254: .Xr mandoc 1 .
1255: .Ss \eM[ Ns Ar name ]
1256: Set fill (background) color (groff extension); ignored by
1257: .Xr mandoc 1 .
1258: For short names, there are variants
1259: .No \eM Ns Ar c
1260: and
1261: .No \eM( Ns Ar cc .
1262: .Ss \em[ Ns Ar name ]
1263: Set glyph drawing color (groff extension); ignored by
1264: .Xr mandoc 1 .
1265: For short names, there are variants
1266: .No \em Ns Ar c
1267: and
1268: .No \em( Ns Ar cc .
1269: .Ss \eN\(aq Ns Ar number Ns \(aq
1270: Character
1271: .Ar number
1272: on the current font.
1273: .Ss \en[ Ns Ar name ]
1274: Interpolate the number register
1275: .Ar name .
1276: For short names, there are variants
1277: .No \en Ns Ar c
1278: and
1279: .No \en( Ns Ar cc .
1280: .Ss \eo\(aq Ns Ar string Ns \(aq
1281: Overstrike
1282: .Ar string ;
1283: ignored by
1284: .Xr mandoc 1 .
1285: .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
1286: Set number register; ignored by
1287: .Xr mandoc 1 .
1288: .Ss \eS\(aq Ns Ar number Ns \(aq
1289: Slant output; ignored by
1290: .Xr mandoc 1 .
1291: .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
1292: Change point size; ignored by
1293: .Xr mandoc 1 .
1294: Alternative forms
1295: .No \es Ns Oo +|- Oc Ns Ar n ,
1296: .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
1297: .No \es Ns [ Oo +|- Oc Ns Ar number ] ,
1298: and
1299: .No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
1300: are also parsed and ignored.
1301: .Ss \et
1302: Horizontal tab; ignored by
1303: .Xr mandoc 1 .
1304: .Ss \eu
1305: Move up by half a line; ignored by
1306: .Xr mandoc 1 .
1307: .Ss \eV[ Ns Ar name ]
1308: Interpolate an environment variable; ignored by
1309: .Xr mandoc 1 .
1310: For short names, there are variants
1311: .No \eV Ns Ar c
1312: and
1313: .No \eV( Ns Ar cc .
1314: .Ss \ev\(aq Ns Ar number Ns \(aq
1315: Vertical motion; ignored by
1316: .Xr mandoc 1 .
1317: .Ss \ew\(aq Ns Ar string Ns \(aq
1318: Interpolate the width of the
1.54 schwarze 1319: .Ar string .
1320: The
1321: .Xr mandoc 1
1322: implementation assumes that after expansion of user-defined strings, the
1323: .Ar string
1324: only contains normal characters, no escape sequences, and that each
1325: character has a width of 24 basic units.
1.46 schwarze 1326: .Ss \eX\(aq Ns Ar string Ns \(aq
1327: Output
1328: .Ar string
1329: as device control function; ignored in nroff mode and by
1330: .Xr mandoc 1 .
1331: .Ss \ex\(aq Ns Ar number Ns \(aq
1332: Extra line space function; ignored by
1333: .Xr mandoc 1 .
1334: .Ss \eY[ Ns Ar name ]
1335: Output a string as a device control function; ignored in nroff mode and by
1336: .Xr mandoc 1 .
1337: For short names, there are variants
1338: .No \eY Ns Ar c
1339: and
1340: .No \eY( Ns Ar cc .
1341: .Ss \eZ\(aq Ns Ar string Ns \(aq
1342: Print
1343: .Ar string
1344: with zero width and height; ignored by
1345: .Xr mandoc 1 .
1346: .Ss \ez
1347: Output the next character without advancing the cursor position;
1348: approximated in
1349: .Xr mandoc 1
1350: by simply skipping the next character.
1.2 kristaps 1351: .Sh COMPATIBILITY
1.40 schwarze 1352: This section documents compatibility between mandoc and other
1.17 schwarze 1353: .Nm
1354: implementations, at this time limited to GNU troff
1.2 kristaps 1355: .Pq Qq groff .
1356: The term
1357: .Qq historic groff
1.17 schwarze 1358: refers to groff version 1.15.
1.2 kristaps 1359: .Pp
1360: .Bl -dash -compact
1.56 kristaps 1361: .It
1362: The
1363: .Sq u
1364: scaling unit is the default terminal unit.
1365: In traditional troff systems, this unit would change depending on the
1366: output media.
1.10 kristaps 1367: .It
1.27 kristaps 1368: In mandoc, the
1369: .Sx \&EQ ,
1370: .Sx \&TE ,
1371: .Sx \&TS ,
1372: and
1373: .Sx \&T& ,
1374: macros are considered regular macros.
1375: In all other
1376: .Nm
1377: implementations, these are special macros that must be specified without
1378: spacing between the control character (which must be a period) and the
1379: macro name.
1380: .It
1.10 kristaps 1381: The
1382: .Cm nS
1.17 schwarze 1383: register is only compatible with OpenBSD's groff-1.15.
1.2 kristaps 1384: .It
1.17 schwarze 1385: Historic groff did not accept white-space before a custom
1386: .Ar end
1387: macro for the
1.2 kristaps 1388: .Sx \&ig
1.17 schwarze 1389: request.
1.4 kristaps 1390: .It
1391: The
1392: .Sx \&if
1393: and family would print funny white-spaces with historic groff when
1.17 schwarze 1394: using the next-line syntax.
1.2 kristaps 1395: .El
1.17 schwarze 1396: .Sh SEE ALSO
1397: .Xr mandoc 1 ,
1.27 kristaps 1398: .Xr eqn 7 ,
1.17 schwarze 1399: .Xr man 7 ,
1400: .Xr mandoc_char 7 ,
1.23 kristaps 1401: .Xr mdoc 7 ,
1402: .Xr tbl 7
1.17 schwarze 1403: .Rs
1404: .%A Joseph F. Ossanna
1405: .%A Brian W. Kernighan
1406: .%I AT&T Bell Laboratories
1407: .%T Troff User's Manual
1408: .%R Computing Science Technical Report
1409: .%N 54
1410: .%C Murray Hill, New Jersey
1411: .%D 1976 and 1992
1412: .%U http://www.kohala.com/start/troff/cstr54.ps
1413: .Re
1414: .Rs
1415: .%A Joseph F. Ossanna
1416: .%A Brian W. Kernighan
1417: .%A Gunnar Ritter
1418: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
1419: .%D September 17, 2007
1420: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
1421: .Re
1422: .Sh HISTORY
1.35 kristaps 1423: The RUNOFF typesetting system, whose input forms the basis for
1.17 schwarze 1424: .Nm ,
1.35 kristaps 1425: was written in MAD and FAP for the CTSS operating system by Jerome E.
1426: Saltzer in 1964.
1427: Doug McIlroy rewrote it in BCPL in 1969, renaming it
1428: .Nm .
1429: Dennis M. Ritchie rewrote McIlroy's
1.36 schwarze 1430: .Nm
1431: in PDP-11 assembly for
1.35 kristaps 1432: .At v1 ,
1433: Joseph F. Ossanna improved roff and renamed it nroff
1434: for
1435: .At v2 ,
1436: then ported nroff to C as troff, which Brian W. Kernighan released with
1437: .At v7 .
1438: In 1989, James Clarke re-implemented troff in C++, naming it groff.
1.1 kristaps 1439: .Sh AUTHORS
1.15 kristaps 1440: .An -nosplit
1.31 kristaps 1441: This
1.1 kristaps 1442: .Nm
1443: reference was written by
1.41 schwarze 1444: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1.15 kristaps 1445: and
1.41 schwarze 1446: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb