Annotation of mandoc/roff.7, Revision 1.44
1.44 ! schwarze 1: .\" $Id: roff.7,v 1.43 2013/10/14 01:43:14 schwarze Exp $
1.1 kristaps 2: .\"
1.33 schwarze 3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\" Copyright (c) 2010, 2011 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.44 ! schwarze 18: .Dd $Mdocdate: October 14 2013 $
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.33 schwarze 35: requests intermixed with their
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
44: requests.
45: Only these requests supported by
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
88: indicates the start of an escape sequence for
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.
96: .Ss Comments
97: Text following an escaped double-quote
98: .Sq \e\(dq ,
99: whether in a request, macro, or text line, is ignored to the end of the line.
100: A request line beginning with a control character and comment escape
101: .Sq \&.\e\(dq
102: is also ignored.
103: Furthermore, request lines with only a control character and optional
104: trailing whitespace are stripped from input.
105: .Pp
106: Examples:
107: .Bd -literal -offset indent -compact
108: \&.\e\(dq This is a comment line.
109: \&.\e\(dq The next line is ignored:
110: \&.
111: \&.Sh EXAMPLES \e\(dq This is a comment, too.
112: \&example text \e\(dq And so is this.
113: .Ed
114: .Ss Special Characters
115: Special characters are used to encode special glyphs and are rendered
116: differently across output media.
117: They may occur in request, macro, and text lines.
118: Sequences begin with the escape character
119: .Sq \e
120: followed by either an open-parenthesis
121: .Sq \&(
122: for two-character sequences; an open-bracket
123: .Sq \&[
124: for n-character sequences (terminated at a close-bracket
125: .Sq \&] ) ;
126: or a single one character sequence.
127: .Pp
128: Examples:
129: .Bl -tag -width Ds -offset indent -compact
130: .It Li \e(em
131: Two-letter em dash escape.
132: .It Li \ee
133: One-letter backslash escape.
134: .El
135: .Pp
136: See
1.17 schwarze 137: .Xr mandoc_char 7
1.33 schwarze 138: for a complete list.
139: .Ss Text Decoration
140: Terms may be text-decorated using the
141: .Sq \ef
142: escape followed by an indicator: B (bold), I (italic), R (regular), or P
143: (revert to previous mode).
144: A numerical representation 3, 2, or 1 (bold, italic, and regular,
145: respectively) may be used instead.
1.34 kristaps 146: The indicator or numerical representative may be preceded by C
147: (constant-width), which is ignored.
1.33 schwarze 148: .Pp
1.42 schwarze 149: The two-character indicator
150: .Sq BI
151: requests a font that is both bold and italic.
152: It may not be portable to old roff implementations.
153: .Pp
1.33 schwarze 154: Examples:
155: .Bl -tag -width Ds -offset indent -compact
156: .It Li \efBbold\efR
1.42 schwarze 157: Write in \fBbold\fP, then switch to regular font mode.
1.33 schwarze 158: .It Li \efIitalic\efP
1.42 schwarze 159: Write in \fIitalic\fP, then return to previous font mode.
160: .It Li \ef(BIbold italic\efP
161: Write in \f(BIbold italic\fP, then return to previous font mode.
1.33 schwarze 162: .El
163: .Pp
164: Text decoration is
165: .Em not
166: recommended for
167: .Xr mdoc 7 ,
168: which encourages semantic annotation.
169: .Ss Predefined Strings
170: Predefined strings, like
171: .Sx Special Characters ,
172: mark special output glyphs.
173: Predefined strings are escaped with the slash-asterisk,
174: .Sq \e* :
175: single-character
176: .Sq \e*X ,
177: two-character
178: .Sq \e*(XX ,
179: and N-character
180: .Sq \e*[N] .
181: .Pp
182: Examples:
183: .Bl -tag -width Ds -offset indent -compact
184: .It Li \e*(Am
185: Two-letter ampersand predefined string.
186: .It Li \e*q
187: One-letter double-quote predefined string.
188: .El
189: .Pp
190: Predefined strings are not recommended for use,
191: as they differ across implementations.
192: Those supported by
193: .Xr mandoc 1
194: are listed in
195: .Xr mandoc_char 7 .
196: Manuals using these predefined strings are almost certainly not portable.
197: .Ss Whitespace
198: Whitespace consists of the space character.
199: In text lines, whitespace is preserved within a line.
200: In request and macro lines, whitespace delimits arguments and is discarded.
201: .Pp
202: Unescaped trailing spaces are stripped from text line input unless in a
203: literal context.
204: In general, trailing whitespace on any input line is discouraged for
205: reasons of portability.
206: In the rare case that a blank character is needed at the end of an
207: input line, it may be forced by
208: .Sq \e\ \e& .
209: .Pp
210: Literal space characters can be produced in the output
211: using escape sequences.
212: In macro lines, they can also be included in arguments using quotation; see
213: .Sx MACRO SYNTAX
214: for details.
215: .Pp
216: Blank text lines, which may include whitespace, are only permitted
217: within literal contexts.
218: If the first character of a text line is a space, that line is printed
219: with a leading newline.
220: .Ss Scaling Widths
221: Many requests and macros support scaled widths for their arguments.
222: The syntax for a scaled width is
223: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
224: where a decimal must be preceded or followed by at least one digit.
225: Negative numbers, while accepted, are truncated to zero.
226: .Pp
227: The following scaling units are accepted:
228: .Pp
229: .Bl -tag -width Ds -offset indent -compact
230: .It c
231: centimetre
232: .It i
233: inch
234: .It P
235: pica (~1/6 inch)
236: .It p
237: point (~1/72 inch)
238: .It f
239: synonym for
240: .Sq u
241: .It v
242: default vertical span
243: .It m
244: width of rendered
245: .Sq m
246: .Pq em
247: character
248: .It n
249: width of rendered
250: .Sq n
251: .Pq en
252: character
253: .It u
254: default horizontal span
255: .It M
256: mini-em (~1/100 em)
257: .El
258: .Pp
259: Using anything other than
260: .Sq m ,
261: .Sq n ,
262: .Sq u ,
263: or
264: .Sq v
265: is necessarily non-portable across output media.
266: See
267: .Sx COMPATIBILITY .
268: .Pp
269: If a scaling unit is not provided, the numerical value is interpreted
270: under the default rules of
271: .Sq v
272: for vertical spaces and
273: .Sq u
274: for horizontal ones.
275: .Pp
276: Examples:
277: .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
278: .It Li \&.Bl -tag -width 2i
279: two-inch tagged list indentation in
280: .Xr mdoc 7
281: .It Li \&.HP 2i
282: two-inch tagged list indentation in
283: .Xr man 7
284: .It Li \&.sp 2v
285: two vertical spaces
286: .El
287: .Ss Sentence Spacing
288: Each sentence should terminate at the end of an input line.
289: By doing this, a formatter will be able to apply the proper amount of
290: spacing after the end of sentence (unescaped) period, exclamation mark,
291: or question mark followed by zero or more non-sentence closing
292: delimiters
293: .Po
294: .Sq \&) ,
295: .Sq \&] ,
296: .Sq \&' ,
297: .Sq \&"
298: .Pc .
299: .Pp
300: The proper spacing is also intelligently preserved if a sentence ends at
301: the boundary of a macro line.
302: .Pp
303: Examples:
304: .Bd -literal -offset indent -compact
305: Do not end sentences mid-line like this. Instead,
306: end a sentence like this.
307: A macro would end like this:
308: \&.Xr mandoc 1 \&.
309: .Ed
1.17 schwarze 310: .Sh REQUEST SYNTAX
311: A request or macro line consists of:
312: .Pp
313: .Bl -enum -compact
314: .It
315: the control character
316: .Sq \&.
1.1 kristaps 317: or
1.17 schwarze 318: .Sq \(aq
319: at the beginning of the line,
320: .It
321: optionally an arbitrary amount of whitespace,
322: .It
323: the name of the request or the macro, which is one word of arbitrary
324: length, terminated by whitespace,
325: .It
326: and zero or more arguments delimited by whitespace.
327: .El
328: .Pp
329: Thus, the following request lines are all equivalent:
1.1 kristaps 330: .Bd -literal -offset indent
1.17 schwarze 331: \&.ig end
332: \&.ig end
333: \&. ig end
1.1 kristaps 334: .Ed
1.24 schwarze 335: .Sh MACRO SYNTAX
1.33 schwarze 336: Macros are provided by the
337: .Xr mdoc 7
338: and
339: .Xr man 7
340: languages and can be defined by the
1.24 schwarze 341: .Sx \&de
342: request.
343: When called, they follow the same syntax as requests, except that
344: macro arguments may optionally be quoted by enclosing them
345: in double quote characters
346: .Pq Sq \(dq .
1.33 schwarze 347: Quoted text, even if it contains whitespace or would cause
348: a macro invocation when unquoted, is always considered literal text.
349: Inside quoted text, pairs of double quote characters
350: .Pq Sq Qq
351: resolve to single double quote characters.
352: .Pp
1.32 kristaps 353: To be recognised as the beginning of a quoted argument, the opening
1.24 schwarze 354: quote character must be preceded by a space character.
355: A quoted argument extends to the next double quote character that is not
356: part of a pair, or to the end of the input line, whichever comes earlier.
357: Leaving out the terminating double quote character at the end of the line
358: is discouraged.
359: For clarity, if more arguments follow on the same input line,
360: it is recommended to follow the terminating double quote character
361: by a space character; in case the next character after the terminating
362: double quote character is anything else, it is regarded as the beginning
363: of the next, unquoted argument.
364: .Pp
365: Both in quoted and unquoted arguments, pairs of backslashes
366: .Pq Sq \e\e
367: resolve to single backslashes.
368: In unquoted arguments, space characters can alternatively be included
369: by preceding them with a backslash
370: .Pq Sq \e\~ ,
371: but quoting is usually better for clarity.
1.33 schwarze 372: .Pp
373: Examples:
374: .Bl -tag -width Ds -offset indent -compact
375: .It Li .Fn strlen \(dqconst char *s\(dq
376: Group arguments
377: .Qq const char *s
378: into one function argument.
379: If unspecified,
380: .Qq const ,
381: .Qq char ,
382: and
383: .Qq *s
384: would be considered separate arguments.
385: .It Li .Op \(dqFl a\(dq
386: Consider
387: .Qq \&Fl a
388: as literal text instead of a flag macro.
389: .El
1.15 kristaps 390: .Sh REQUEST REFERENCE
1.17 schwarze 391: The
1.15 kristaps 392: .Xr mandoc 1
393: .Nm
1.32 kristaps 394: parser recognises the following requests.
1.17 schwarze 395: Note that the
1.15 kristaps 396: .Nm
1.17 schwarze 397: language defines many more requests not implemented in
1.15 kristaps 398: .Xr mandoc 1 .
399: .Ss \&ad
400: Set line adjustment mode.
401: This line-scoped request is intended to have one argument to select
1.32 kristaps 402: normal, left, right, or centre adjustment for subsequent text.
1.15 kristaps 403: Currently, it is ignored including its arguments,
404: and the number of arguments is not checked.
1.3 kristaps 405: .Ss \&am
1.15 kristaps 406: Append to a macro definition.
407: The syntax of this request is the same as that of
408: .Sx \&de .
409: It is currently ignored by
410: .Xr mandoc 1 ,
411: as are its children.
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 .
416: It is currently ignored by
417: .Xr mandoc 1 ,
418: as are its children.
1.3 kristaps 419: .Ss \&am1
1.15 kristaps 420: Append to a macro definition, switching roff compatibility mode off
421: during macro execution.
422: The syntax of this request is the same as that of
423: .Sx \&de1 .
424: It is currently ignored by
425: .Xr mandoc 1 ,
426: as are its children.
1.39 kristaps 427: .Ss \&cc
428: Changes the control character.
429: Its syntax is as follows:
430: .Bd -literal -offset indent
431: .Pf . Cm \&cc Op Ar c
432: .Ed
433: .Pp
434: If
435: .Ar c
436: is not specified, the control character is reset to
437: .Sq \&. .
438: Trailing characters are ignored.
1.3 kristaps 439: .Ss \&de
1.17 schwarze 440: Define a
1.15 kristaps 441: .Nm
442: macro.
443: Its syntax can be either
444: .Bd -literal -offset indent
445: .Pf . Cm \&de Ar name
446: .Ar macro definition
447: \&..
448: .Ed
449: .Pp
450: or
451: .Bd -literal -offset indent
452: .Pf . Cm \&de Ar name Ar end
453: .Ar macro definition
454: .Pf . Ar end
455: .Ed
456: .Pp
457: Both forms define or redefine the macro
458: .Ar name
459: to represent the
460: .Ar macro definition ,
461: which may consist of one or more input lines, including the newline
462: characters terminating each line, optionally containing calls to
463: .Nm
464: requests,
465: .Nm
466: macros or high-level macros like
467: .Xr man 7
468: or
469: .Xr mdoc 7
470: macros, whichever applies to the document in question.
471: .Pp
472: Specifying a custom
473: .Ar end
474: macro works in the same way as for
475: .Sx \&ig ;
476: namely, the call to
477: .Sq Pf . Ar end
478: first ends the
479: .Ar macro definition ,
480: and after that, it is also evaluated as a
481: .Nm
482: request or
483: .Nm
484: macro, but not as a high-level macro.
485: .Pp
1.17 schwarze 486: The macro can be invoked later using the syntax
1.15 kristaps 487: .Pp
488: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
489: .Pp
1.24 schwarze 490: Regarding argument parsing, see
491: .Sx MACRO SYNTAX
492: above.
1.15 kristaps 493: .Pp
1.17 schwarze 494: The line invoking the macro will be replaced
1.15 kristaps 495: in the input stream by the
496: .Ar macro definition ,
497: replacing all occurrences of
498: .No \e\e$ Ns Ar N ,
1.17 schwarze 499: where
1.15 kristaps 500: .Ar N
501: is a digit, by the
502: .Ar N Ns th Ar argument .
503: For example,
504: .Bd -literal -offset indent
505: \&.de ZN
506: \efI\e^\e\e$1\e^\efP\e\e$2
507: \&..
508: \&.ZN XtFree .
509: .Ed
510: .Pp
511: produces
512: .Pp
513: .D1 \efI\e^XtFree\e^\efP.
514: .Pp
515: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
516: .Pp
1.17 schwarze 517: Since macros and user-defined strings share a common string table,
1.15 kristaps 518: defining a macro
519: .Ar name
520: clobbers the user-defined string
521: .Ar name ,
522: and the
523: .Ar macro definition
524: can also be printed using the
525: .Sq \e*
526: string interpolation syntax described below
527: .Sx ds ,
528: but this is rarely useful because every macro definition contains at least
529: one explicit newline character.
1.16 schwarze 530: .Pp
531: In order to prevent endless recursion, both groff and
532: .Xr mandoc 1
533: limit the stack depth for expanding macros and strings
534: to a large, but finite number.
535: Do not rely on the exact value of this limit.
1.3 kristaps 536: .Ss \&dei
1.17 schwarze 537: Define a
1.15 kristaps 538: .Nm
539: macro, specifying the macro name indirectly.
1.17 schwarze 540: The syntax of this request is the same as that of
1.15 kristaps 541: .Sx \&de .
542: It is currently ignored by
543: .Xr mandoc 1 ,
544: as are its children.
545: .Ss \&de1
1.17 schwarze 546: Define a
1.15 kristaps 547: .Nm
548: macro that will be executed with
549: .Nm
550: compatibility mode switched off during macro execution.
551: This is a GNU extension not available in traditional
552: .Nm
553: implementations and not even in older versions of groff.
554: Since
555: .Xr mandoc 1
556: does not implement
557: .Nm
1.17 schwarze 558: compatibility mode at all, it handles this request as an alias for
1.15 kristaps 559: .Sx \&de .
1.6 schwarze 560: .Ss \&ds
1.15 kristaps 561: Define a user-defined string.
1.13 kristaps 562: Its syntax is as follows:
563: .Pp
1.15 kristaps 564: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13 kristaps 565: .Pp
566: The
1.15 kristaps 567: .Ar name
1.13 kristaps 568: and
1.15 kristaps 569: .Ar string
570: arguments are space-separated.
571: If the
572: .Ar string
573: begins with a double-quote character, that character will not be part
574: of the string.
575: All remaining characters on the input line form the
576: .Ar string ,
577: including whitespace and double-quote characters, even trailing ones.
578: .Pp
1.13 kristaps 579: The
1.15 kristaps 580: .Ar string
581: can be interpolated into subsequent text by using
582: .No \e* Ns Bq Ar name
583: for a
584: .Ar name
585: of arbitrary length, or \e*(NN or \e*N if the length of
586: .Ar name
587: is two or one characters, respectively.
1.17 schwarze 588: Interpolation can be prevented by escaping the leading backslash;
589: that is, an asterisk preceded by an even number of backslashes
590: does not trigger string interpolation.
1.15 kristaps 591: .Pp
592: Since user-defined strings and macros share a common string table,
593: defining a string
594: .Ar name
1.17 schwarze 595: clobbers the macro
1.15 kristaps 596: .Ar name ,
597: and the
598: .Ar name
599: used for defining a string can also be invoked as a macro,
600: in which case the following input line will be appended to the
601: .Ar string ,
602: forming a new input line passed to the
603: .Nm
604: parser.
605: For example,
606: .Bd -literal -offset indent
607: \&.ds badidea .S
608: \&.badidea
609: H SYNOPSIS
610: .Ed
611: .Pp
612: invokes the
613: .Cm SH
614: macro when used in a
615: .Xr man 7
616: document.
617: Such abuse is of course strongly discouraged.
1.5 kristaps 618: .Ss \&el
619: The
620: .Qq else
621: half of an if/else conditional.
622: Pops a result off the stack of conditional evaluations pushed by
623: .Sx \&ie
624: and uses it as its conditional.
625: If no stack entries are present (e.g., due to no prior
626: .Sx \&ie
627: calls)
628: then false is assumed.
1.17 schwarze 629: The syntax of this request is similar to
1.5 kristaps 630: .Sx \&if
631: except that the conditional is missing.
1.27 kristaps 632: .Ss \&EN
633: End an equation block.
634: See
635: .Sx \&EQ .
636: .Ss \&EQ
637: Begin an equation block.
638: See
639: .Xr eqn 7
640: for a description of the equation language.
1.43 schwarze 641: .Ss \&fam
642: Change the font family.
643: This line-scoped request is intended to have one argument specifying
644: the font family to be selected.
645: It is a groff extension, and currently, it is ignored including its
646: arguments, and the number of arguments is not checked.
1.44 ! schwarze 647: .Ss \&hw
! 648: Specify hyphenation points in words.
! 649: This line-scoped request is currently ignored.
1.15 kristaps 650: .Ss \&hy
651: Set automatic hyphenation mode.
652: This line-scoped request is currently ignored.
1.5 kristaps 653: .Ss \&ie
654: The
655: .Qq if
656: half of an if/else conditional.
657: The result of the conditional is pushed into a stack used by subsequent
658: invocations of
659: .Sx \&el ,
660: which may be separated by any intervening input (or not exist at all).
661: Its syntax is equivalent to
662: .Sx \&if .
1.1 kristaps 663: .Ss \&if
1.7 schwarze 664: Begins a conditional.
665: Right now, the conditional evaluates to true
666: if and only if it starts with the letter
667: .Sy n ,
1.17 schwarze 668: indicating processing in nroff style as opposed to troff style.
1.3 kristaps 669: If a conditional is false, its children are not processed, but are
670: syntactically interpreted to preserve the integrity of the input
671: document.
672: Thus,
673: .Pp
1.17 schwarze 674: .D1 \&.if t .ig
1.3 kristaps 675: .Pp
676: will discard the
677: .Sq \&.ig ,
678: which may lead to interesting results, but
679: .Pp
1.17 schwarze 680: .D1 \&.if t .if t \e{\e
1.3 kristaps 681: .Pp
682: will continue to syntactically interpret to the block close of the final
683: conditional.
684: Sub-conditionals, in this case, obviously inherit the truth value of
685: the parent.
1.17 schwarze 686: This request has the following syntax:
687: .Bd -literal -offset indent
1.1 kristaps 688: \&.if COND \e{\e
689: BODY...
690: \&.\e}
691: .Ed
1.17 schwarze 692: .Bd -literal -offset indent
1.1 kristaps 693: \&.if COND \e{ BODY
1.2 kristaps 694: BODY... \e}
695: .Ed
1.17 schwarze 696: .Bd -literal -offset indent
1.2 kristaps 697: \&.if COND \e{ BODY
1.1 kristaps 698: BODY...
699: \&.\e}
700: .Ed
1.17 schwarze 701: .Bd -literal -offset indent
1.1 kristaps 702: \&.if COND \e
703: BODY
704: .Ed
705: .Pp
1.9 kristaps 706: COND is a conditional statement.
707: roff allows for complicated conditionals; mandoc is much simpler.
708: At this time, mandoc supports only
709: .Sq n ,
710: evaluating to true;
711: and
712: .Sq t ,
713: .Sq e ,
714: and
715: .Sq o ,
716: evaluating to false.
717: All other invocations are read up to the next end of line or space and
718: evaluate as false.
1.1 kristaps 719: .Pp
720: If the BODY section is begun by an escaped brace
721: .Sq \e{ ,
1.17 schwarze 722: scope continues until a closing-brace escape sequence
1.1 kristaps 723: .Sq \.\e} .
1.17 schwarze 724: If the BODY is not enclosed in braces, scope continues until
725: the end of the line.
1.1 kristaps 726: If the COND is followed by a BODY on the same line, whether after a
1.17 schwarze 727: brace or not, then requests and macros
1.1 kristaps 728: .Em must
729: begin with a control character.
730: It is generally more intuitive, in this case, to write
731: .Bd -literal -offset indent
732: \&.if COND \e{\e
733: \&.foo
734: bar
735: \&.\e}
736: .Ed
737: .Pp
1.17 schwarze 738: than having the request or macro follow as
1.1 kristaps 739: .Pp
740: .D1 \&.if COND \e{ .foo
741: .Pp
742: The scope of a conditional is always parsed, but only executed if the
743: conditional evaluates to true.
744: .Pp
1.29 kristaps 745: Note that the
1.1 kristaps 746: .Sq \e}
1.29 kristaps 747: is converted into a zero-width escape sequence if not passed as a
748: standalone macro
749: .Sq \&.\e} .
750: For example,
751: .Pp
752: .D1 \&.Fl a \e} b
753: .Pp
754: will result in
1.8 kristaps 755: .Sq \e}
1.29 kristaps 756: being considered an argument of the
757: .Sq \&Fl
758: macro.
1.1 kristaps 759: .Ss \&ig
1.2 kristaps 760: Ignore input.
1.15 kristaps 761: Its syntax can be either
762: .Bd -literal -offset indent
763: .Pf . Cm \&ig
764: .Ar ignored text
1.2 kristaps 765: \&..
766: .Ed
1.15 kristaps 767: .Pp
768: or
769: .Bd -literal -offset indent
770: .Pf . Cm \&ig Ar end
771: .Ar ignored text
772: .Pf . Ar end
1.2 kristaps 773: .Ed
774: .Pp
775: In the first case, input is ignored until a
776: .Sq \&..
1.17 schwarze 777: request is encountered on its own line.
1.15 kristaps 778: In the second case, input is ignored until the specified
779: .Sq Pf . Ar end
780: macro is encountered.
781: Do not use the escape character
1.2 kristaps 782: .Sq \e
1.15 kristaps 783: anywhere in the definition of
784: .Ar end ;
785: it would cause very strange behaviour.
786: .Pp
787: When the
788: .Ar end
789: macro is a roff request or a roff macro, like in
1.2 kristaps 790: .Pp
791: .D1 \&.ig if
792: .Pp
793: the subsequent invocation of
794: .Sx \&if
1.15 kristaps 795: will first terminate the
796: .Ar ignored text ,
797: then be invoked as usual.
798: Otherwise, it only terminates the
799: .Ar ignored text ,
800: and arguments following it or the
801: .Sq \&..
1.17 schwarze 802: request are discarded.
1.15 kristaps 803: .Ss \&ne
804: Declare the need for the specified minimum vertical space
805: before the next trap or the bottom of the page.
806: This line-scoped request is currently ignored.
807: .Ss \&nh
808: Turn off automatic hyphenation mode.
809: This line-scoped request is currently ignored.
1.6 schwarze 810: .Ss \&rm
811: Remove a request, macro or string.
1.15 kristaps 812: This request is intended to have one argument,
1.6 schwarze 813: the name of the request, macro or string to be undefined.
814: Currently, it is ignored including its arguments,
815: and the number of arguments is not checked.
1.10 kristaps 816: .Ss \&nr
817: Define a register.
818: A register is an arbitrary string value that defines some sort of state,
819: which influences parsing and/or formatting.
820: Its syntax is as follows:
821: .Pp
1.15 kristaps 822: .D1 Pf \. Cm \&nr Ar name Ar value
1.10 kristaps 823: .Pp
824: The
1.15 kristaps 825: .Ar value
1.10 kristaps 826: may, at the moment, only be an integer.
1.15 kristaps 827: So far, only the following register
828: .Ar name
829: is recognised:
1.10 kristaps 830: .Bl -tag -width Ds
831: .It Cm nS
832: If set to a positive integer value, certain
833: .Xr mdoc 7
1.17 schwarze 834: macros will behave in the same way as in the
1.10 kristaps 835: .Em SYNOPSIS
1.11 kristaps 836: section.
1.17 schwarze 837: If set to 0, these macros will behave in the same way as outside the
838: .Em SYNOPSIS
839: section, even when called within the
1.10 kristaps 840: .Em SYNOPSIS
1.17 schwarze 841: section itself.
842: Note that starting a new
1.11 kristaps 843: .Xr mdoc 7
1.17 schwarze 844: section with the
845: .Cm \&Sh
846: macro will reset this register.
1.10 kristaps 847: .El
1.26 schwarze 848: .Ss \&ns
849: Turn on no-space mode.
850: This line-scoped request is intended to take no arguments.
851: Currently, it is ignored including its arguments,
852: and the number of arguments is not checked.
853: .Ss \&ps
854: Change point size.
855: This line-scoped request is intended to take one numerical argument.
856: Currently, it is ignored including its arguments,
857: and the number of arguments is not checked.
1.15 kristaps 858: .Ss \&so
859: Include a source file.
860: Its syntax is as follows:
861: .Pp
862: .D1 Pf \. Cm \&so Ar file
863: .Pp
864: The
865: .Ar file
866: will be read and its contents processed as input in place of the
867: .Sq \&.so
868: request line.
1.28 kristaps 869: To avoid inadvertent inclusion of unrelated files,
1.15 kristaps 870: .Xr mandoc 1
871: only accepts relative paths not containing the strings
872: .Qq ../
873: and
874: .Qq /.. .
1.37 schwarze 875: .Pp
876: This request requires
877: .Xr man 1
878: to change to the right directory before calling
879: .Xr mandoc 1 ,
880: per convention to the root of the manual tree.
881: Typical usage looks like:
882: .Pp
883: .Dl \&.so man3/Xcursor.3
884: .Pp
885: As the whole concept is rather fragile, the use of
886: .Sx \&so
887: is discouraged.
888: Use
889: .Xr ln 1
890: instead.
1.26 schwarze 891: .Ss \&ta
892: Set tab stops.
893: This line-scoped request can take an arbitrary number of arguments.
894: Currently, it is ignored including its arguments.
1.6 schwarze 895: .Ss \&tr
896: Output character translation.
1.30 kristaps 897: Its syntax is as follows:
898: .Pp
899: .D1 Pf \. Cm \&tr Ar [ab]+
900: .Pp
901: Pairs of
902: .Ar ab
903: characters are replaced
904: .Ar ( a
905: for
906: .Ar b ) .
907: Replacement (or origin) characters may also be character escapes; thus,
908: .Pp
909: .Dl tr \e(xx\e(yy
910: .Pp
911: replaces all invocations of \e(xx with \e(yy.
1.20 kristaps 912: .Ss \&T&
913: Re-start a table layout, retaining the options of the prior table
914: invocation.
915: See
916: .Sx \&TS .
917: .Ss \&TE
918: End a table context.
919: See
920: .Sx \&TS .
921: .Ss \&TS
922: Begin a table, which formats input in aligned rows and columns.
1.23 kristaps 923: See
924: .Xr tbl 7
925: for a description of the tbl language.
1.2 kristaps 926: .Sh COMPATIBILITY
1.40 schwarze 927: This section documents compatibility between mandoc and other
1.17 schwarze 928: .Nm
929: implementations, at this time limited to GNU troff
1.2 kristaps 930: .Pq Qq groff .
931: The term
932: .Qq historic groff
1.17 schwarze 933: refers to groff version 1.15.
1.2 kristaps 934: .Pp
935: .Bl -dash -compact
1.10 kristaps 936: .It
1.27 kristaps 937: In mandoc, the
938: .Sx \&EQ ,
939: .Sx \&TE ,
940: .Sx \&TS ,
941: and
942: .Sx \&T& ,
943: macros are considered regular macros.
944: In all other
945: .Nm
946: implementations, these are special macros that must be specified without
947: spacing between the control character (which must be a period) and the
948: macro name.
949: .It
1.10 kristaps 950: The
951: .Cm nS
1.17 schwarze 952: register is only compatible with OpenBSD's groff-1.15.
1.2 kristaps 953: .It
1.17 schwarze 954: Historic groff did not accept white-space before a custom
955: .Ar end
956: macro for the
1.2 kristaps 957: .Sx \&ig
1.17 schwarze 958: request.
1.4 kristaps 959: .It
960: The
961: .Sx \&if
962: and family would print funny white-spaces with historic groff when
1.17 schwarze 963: using the next-line syntax.
1.2 kristaps 964: .El
1.17 schwarze 965: .Sh SEE ALSO
966: .Xr mandoc 1 ,
1.27 kristaps 967: .Xr eqn 7 ,
1.17 schwarze 968: .Xr man 7 ,
969: .Xr mandoc_char 7 ,
1.23 kristaps 970: .Xr mdoc 7 ,
971: .Xr tbl 7
1.17 schwarze 972: .Rs
973: .%A Joseph F. Ossanna
974: .%A Brian W. Kernighan
975: .%I AT&T Bell Laboratories
976: .%T Troff User's Manual
977: .%R Computing Science Technical Report
978: .%N 54
979: .%C Murray Hill, New Jersey
980: .%D 1976 and 1992
981: .%U http://www.kohala.com/start/troff/cstr54.ps
982: .Re
983: .Rs
984: .%A Joseph F. Ossanna
985: .%A Brian W. Kernighan
986: .%A Gunnar Ritter
987: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
988: .%D September 17, 2007
989: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
990: .Re
991: .Sh HISTORY
1.35 kristaps 992: The RUNOFF typesetting system, whose input forms the basis for
1.17 schwarze 993: .Nm ,
1.35 kristaps 994: was written in MAD and FAP for the CTSS operating system by Jerome E.
995: Saltzer in 1964.
996: Doug McIlroy rewrote it in BCPL in 1969, renaming it
997: .Nm .
998: Dennis M. Ritchie rewrote McIlroy's
1.36 schwarze 999: .Nm
1000: in PDP-11 assembly for
1.35 kristaps 1001: .At v1 ,
1002: Joseph F. Ossanna improved roff and renamed it nroff
1003: for
1004: .At v2 ,
1005: then ported nroff to C as troff, which Brian W. Kernighan released with
1006: .At v7 .
1007: In 1989, James Clarke re-implemented troff in C++, naming it groff.
1.1 kristaps 1008: .Sh AUTHORS
1.15 kristaps 1009: .An -nosplit
1.31 kristaps 1010: This
1.1 kristaps 1011: .Nm
1012: reference was written by
1.41 schwarze 1013: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1.15 kristaps 1014: and
1.41 schwarze 1015: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to roff.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc