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