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