Import mdocml-1.10.9
[dragonfly.git] / contrib / mdocml / man.7
CommitLineData
80387638
SW
1.\" $Id: man.7,v 1.94 2011/01/04 23:32:21 kristaps Exp $
2.\"
3.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: January 4 2011 $
18.Dt MAN 7
19.Os
20.Sh NAME
21.Nm man
22.Nd man language reference
23.Sh DESCRIPTION
24The
25.Nm man
26language was historically used to format
27.Ux
28manuals.
29This reference document describes its syntax, structure, and usage.
30.Pp
31.Bf -emphasis
32Do not use
33.Nm
34to write your manuals.
35.Ef
36Use the
37.Xr mdoc 7
38language, instead.
39.Pp
40A
41.Nm
42document follows simple rules: lines beginning with the control
43character
44.Sq \&.
45are parsed for macros.
46Other lines are interpreted within the scope of
47prior macros:
48.Bd -literal -offset indent
49\&.SH Macro lines change control state.
50Other lines are interpreted within the current state.
51.Ed
52.Sh INPUT ENCODING
53.Nm
54documents may contain only graphable 7-bit ASCII characters, the
55space character, and the tab character.
56All manuals must have
57.Ux
58line termination.
59.Pp
60Blank lines are acceptable; where found, the output will assert a
61vertical space.
62.Ss Comments
63Text following a
64.Sq \e\*q ,
65whether in a macro or free-form text line, is ignored to the end of
66line.
67A macro line with only a control character and comment escape,
68.Sq \&.\e\*q ,
69is also ignored.
70Macro lines with only a control character and optionally whitespace are
71stripped from input.
72.Ss Special Characters
73Special characters may occur in both macro and free-form lines.
74Sequences begin with the escape character
75.Sq \e
76followed by either an open-parenthesis
77.Sq \&(
78for two-character sequences; an open-bracket
79.Sq \&[
80for n-character sequences (terminated at a close-bracket
81.Sq \&] ) ;
82or a single one-character sequence.
83See
84.Xr mandoc_char 7
85for a complete list.
86Examples include
87.Sq \e(em
88.Pq em-dash
89and
90.Sq \ee
91.Pq back-slash .
92.Ss Text Decoration
93Terms may be text-decorated using the
94.Sq \ef
95escape followed by an indicator: B (bold), I (italic), R (Roman), or P
96(revert to previous mode):
97.Pp
98.D1 \efBbold\efR \efIitalic\efP
99.Pp
100A numerical representation 3, 2, or 1 (bold, italic, and Roman,
101respectively) may be used instead.
102A text decoration is only valid, if specified in free-form text, until
103the next macro invocation; if specified within a macro, it's only valid
104until the macro closes scope.
105Note that macros like
106.Sx \&BR
107open and close a font scope with each argument.
108.Pp
109The
110.Sq \ef
111attribute is forgotten when entering or exiting a macro block.
112.Ss Whitespace
113Whitespace consists of the space character.
114In free-form lines, whitespace is preserved within a line; unescaped
115trailing spaces are stripped from input (unless in a literal context).
116Blank free-form lines, which may include spaces, are permitted and
117rendered as an empty line.
118.Pp
119In macro lines, whitespace delimits arguments and is discarded.
120If arguments are quoted, whitespace within the quotes is retained.
121.Ss Dates
122The
123.Sx \&TH
124macro is the only
125.Nm
126macro that requires a date.
127The form for this date is the ISO-8601
128standard
129.Cm YYYY-MM-DD .
130.Ss Scaling Widths
131Many macros support scaled widths for their arguments, such as
132stipulating a two-inch paragraph indentation with the following:
133.Bd -literal -offset indent
134\&.HP 2i
135.Ed
136.Pp
137The syntax for scaled widths is
138.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
139where a decimal must be preceded or proceeded by at least one digit.
140Negative numbers, while accepted, are truncated to zero.
141The following scaling units are accepted:
142.Pp
143.Bl -tag -width Ds -offset indent -compact
144.It c
145centimetre
146.It i
147inch
148.It P
149pica (~1/6 inch)
150.It p
151point (~1/72 inch)
152.It f
153synonym for
154.Sq u
155.It v
156default vertical span
157.It m
158width of rendered
159.Sq m
160.Pq em
161character
162.It n
163width of rendered
164.Sq n
165.Pq en
166character
167.It u
168default horizontal span
169.It M
170mini-em (~1/100 em)
171.El
172.Pp
173Using anything other than
174.Sq m ,
175.Sq n ,
176.Sq u ,
177or
178.Sq v
179is necessarily non-portable across output media.
180.Pp
181If a scaling unit is not provided, the numerical value is interpreted
182under the default rules of
183.Sq v
184for vertical spaces and
185.Sq u
186for horizontal ones.
187.Em Note :
188this differs from
189.Xr mdoc 7 ,
190which, if a unit is not provided, will instead interpret the string as
191literal text.
192.Ss Sentence Spacing
193When composing a manual, make sure that sentences end at the end of
194a line.
195By doing so, front-ends will be able to apply the proper amount of
196spacing after the end of sentence (unescaped) period, exclamation mark,
197or question mark followed by zero or more non-sentence closing
198delimiters
199.Po
200.Sq \&) ,
201.Sq \&] ,
202.Sq \&' ,
203.Sq \&"
204.Pc .
205.Sh MANUAL STRUCTURE
206Each
207.Nm
208document must contain the
209.Sx \&TH
210macro describing the document's section and title.
211It may occur anywhere in the document, although conventionally it
212appears as the first macro.
213.Pp
214Beyond
215.Sx \&TH ,
216at least one macro or text node must appear in the document.
217Documents are generally structured as follows:
218.Bd -literal -offset indent
219\&.TH FOO 1 2009-10-10
220\&.SH NAME
221\efBfoo\efR \e(en a description goes here
222\&.\e\*q .SH LIBRARY
223\&.\e\*q For sections 2 & 3 only.
224\&.\e\*q Not used in OpenBSD.
225\&.SH SYNOPSIS
226\efBfoo\efR [\efB\e-options\efR] arguments...
227\&.SH DESCRIPTION
228The \efBfoo\efR utility processes files...
229\&.\e\*q .SH IMPLEMENTATION NOTES
230\&.\e\*q Not used in OpenBSD.
231\&.\e\*q .SH RETURN VALUES
232\&.\e\*q For sections 2, 3, & 9 only.
233\&.\e\*q .SH ENVIRONMENT
234\&.\e\*q For sections 1, 6, 7, & 8 only.
235\&.\e\*q .SH FILES
236\&.\e\*q .SH EXIT STATUS
237\&.\e\*q For sections 1, 6, & 8 only.
238\&.\e\*q .SH EXAMPLES
239\&.\e\*q .SH DIAGNOSTICS
240\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
241\&.\e\*q .SH ERRORS
242\&.\e\*q For sections 2, 3, & 9 only.
243\&.\e\*q .SH SEE ALSO
244\&.\e\*q .BR foo ( 1 )
245\&.\e\*q .SH STANDARDS
246\&.\e\*q .SH HISTORY
247\&.\e\*q .SH AUTHORS
248\&.\e\*q .SH CAVEATS
249\&.\e\*q .SH BUGS
250\&.\e\*q .SH SECURITY CONSIDERATIONS
251\&.\e\*q Not used in OpenBSD.
252.Ed
253.Pp
254The sections in a
255.Nm
256document are conventionally ordered as they appear above.
257Sections should be composed as follows:
258.Bl -ohang -offset indent
259.It Em NAME
260The name(s) and a short description of the documented material.
261The syntax for this is generally as follows:
262.Pp
263.D1 \efBname\efR \e(en description
264.It Em LIBRARY
265The name of the library containing the documented material, which is
266assumed to be a function in a section 2 or 3 manual.
267For functions in the C library, this may be as follows:
268.Pp
269.D1 Standard C Library (libc, -lc)
270.It Em SYNOPSIS
271Documents the utility invocation syntax, function call syntax, or device
272configuration.
273.Pp
274For the first, utilities (sections 1, 6, and 8), this is
275generally structured as follows:
276.Pp
277.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
278.Pp
279For the second, function calls (sections 2, 3, 9):
280.Pp
281.D1 \&.B char *name(char *\efIarg\efR);
282.Pp
283And for the third, configurations (section 4):
284.Pp
285.D1 \&.B name* at cardbus ? function ?
286.Pp
287Manuals not in these sections generally don't need a
288.Em SYNOPSIS .
289.It Em DESCRIPTION
290This expands upon the brief, one-line description in
291.Em NAME .
292It usually contains a break-down of the options (if documenting a
293command).
294.It Em IMPLEMENTATION NOTES
295Implementation-specific notes should be kept here.
296This is useful when implementing standard functions that may have side
297effects or notable algorithmic implications.
298.It Em RETURN VALUES
299This section documents the return values of functions in sections 2, 3, and 9.
300.It Em ENVIRONMENT
301Documents any usages of environment variables, e.g.,
302.Xr environ 7 .
303.It Em FILES
304Documents files used.
305It's helpful to document both the file name and a short description of how
306the file is used (created, modified, etc.).
307.It Em EXIT STATUS
308This section documents the command exit status for
309section 1, 6, and 8 utilities.
310Historically, this information was described in
311.Em DIAGNOSTICS ,
312a practise that is now discouraged.
313.It Em EXAMPLES
314Example usages.
315This often contains snippets of well-formed,
316well-tested invocations.
317Make sure that examples work properly!
318.It Em DIAGNOSTICS
319Documents error conditions.
320This is most useful in section 4 manuals.
321Historically, this section was used in place of
322.Em EXIT STATUS
323for manuals in sections 1, 6, and 8; however, this practise is
324discouraged.
325.It Em ERRORS
326Documents error handling in sections 2, 3, and 9.
327.It Em SEE ALSO
328References other manuals with related topics.
329This section should exist for most manuals.
330.Pp
331.D1 \&.BR bar \&( 1 \&),
332.Pp
333Cross-references should conventionally be ordered
334first by section, then alphabetically.
335.It Em STANDARDS
336References any standards implemented or used, such as
337.Pp
338.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
339.Pp
340If not adhering to any standards, the
341.Em HISTORY
342section should be used.
343.It Em HISTORY
344A brief history of the subject, including where support first appeared.
345.It Em AUTHORS
346Credits to the person or persons who wrote the code and/or documentation.
347Authors should generally be noted by both name and email address.
348.It Em CAVEATS
349Common misuses and misunderstandings should be explained
350in this section.
351.It Em BUGS
352Known bugs, limitations, and work-arounds should be described
353in this section.
354.It Em SECURITY CONSIDERATIONS
355Documents any security precautions that operators should consider.
356.El
357.Sh MACRO SYNTAX
358Macros are one to three characters in length and begin with a
359control character,
360.Sq \&. ,
361at the beginning of the line.
362The
363.Sq \(aq
364macro control character is also accepted.
365An arbitrary amount of whitespace (spaces or tabs) may sit between the
366control character and the macro name.
367Thus, the following are equivalent:
368.Bd -literal -offset indent
369\&.PP
370\&.\ \ \ PP
371.Ed
372.Pp
373The
374.Nm
375macros are classified by scope: line scope or block scope.
376Line macros are only scoped to the current line (and, in some
377situations, the subsequent line).
378Block macros are scoped to the current line and subsequent lines until
379closed by another block macro.
380.Ss Line Macros
381Line macros are generally scoped to the current line, with the body
382consisting of zero or more arguments.
383If a macro is scoped to the next line and the line arguments are empty,
384the next line, which must be text, is used instead.
385Thus:
386.Bd -literal -offset indent
387\&.I
388foo
389.Ed
390.Pp
391is equivalent to
392.Sq \&.I foo .
393If next-line macros are invoked consecutively, only the last is used.
394If a next-line macro is followed by a non-next-line macro, an error is
395raised, except for
396.Sx \&br ,
397.Sx \&sp ,
398and
399.Sx \&na .
400.Pp
401The syntax is as follows:
402.Bd -literal -offset indent
403\&.YO \(lBbody...\(rB
404\(lBbody...\(rB
405.Ed
406.Pp
407.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"
408.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
409.It Sx \&AT Ta <=1 Ta current Ta \&
410.It Sx \&B Ta n Ta next-line Ta \&
411.It Sx \&BI Ta n Ta current Ta \&
412.It Sx \&BR Ta n Ta current Ta \&
413.It Sx \&DT Ta 0 Ta current Ta \&
414.It Sx \&I Ta n Ta next-line Ta \&
415.It Sx \&IB Ta n Ta current Ta \&
416.It Sx \&IR Ta n Ta current Ta \&
417.It Sx \&R Ta n Ta next-line Ta \&
418.It Sx \&RB Ta n Ta current Ta \&
419.It Sx \&RI Ta n Ta current Ta \&
420.It Sx \&SB Ta n Ta next-line Ta \&
421.It Sx \&SM Ta n Ta next-line Ta \&
422.It Sx \&TH Ta >1, <6 Ta current Ta \&
423.It Sx \&UC Ta <=1 Ta current Ta \&
424.It Sx \&br Ta 0 Ta current Ta compat
425.It Sx \&fi Ta 0 Ta current Ta compat
426.It Sx \&ft Ta 1 Ta current Ta compat
427.It Sx \&in Ta 1 Ta current Ta compat
428.It Sx \&na Ta 0 Ta current Ta compat
429.It Sx \&nf Ta 0 Ta current Ta compat
430.It Sx \&sp Ta 1 Ta current Ta compat
431.El
432.Pp
433Macros marked as
434.Qq compat
435are included for compatibility with the significant corpus of existing
436manuals that mix dialects of roff.
437These macros should not be used for portable
438.Nm
439manuals.
440.Ss Block Macros
441Block macros comprise a head and body.
442As with in-line macros, the head is scoped to the current line and, in
443one circumstance, the next line (the next-line stipulations as in
444.Sx Line Macros
445apply here as well).
446.Pp
447The syntax is as follows:
448.Bd -literal -offset indent
449\&.YO \(lBhead...\(rB
450\(lBhead...\(rB
451\(lBbody...\(rB
452.Ed
453.Pp
454The closure of body scope may be to the section, where a macro is closed
455by
456.Sx \&SH ;
457sub-section, closed by a section or
458.Sx \&SS ;
459part, closed by a section, sub-section, or
460.Sx \&RE ;
461or paragraph, closed by a section, sub-section, part,
462.Sx \&HP ,
463.Sx \&IP ,
464.Sx \&LP ,
465.Sx \&P ,
466.Sx \&PP ,
467or
468.Sx \&TP .
469No closure refers to an explicit block closing macro.
470.Pp
471As a rule, block macros may not be nested; thus, calling a block macro
472while another block macro scope is open, and the open scope is not
473implicitly closed, is syntactically incorrect.
474.Pp
475.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"
476.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
477.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
478.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
479.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
480.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
481.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
482.It Sx \&RE Ta 0 Ta current Ta none Ta compat
483.It Sx \&RS Ta 1 Ta current Ta part Ta compat
484.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
485.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
486.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
487.El
488.Pp
489Macros marked
490.Qq compat
491are as mentioned in
492.Sx Line Macros .
493.Pp
494If a block macro is next-line scoped, it may only be followed by in-line
495macros for decorating text.
496.Sh REFERENCE
497This section is a canonical reference to all macros, arranged
498alphabetically.
499For the scoping of individual macros, see
500.Sx MACRO SYNTAX .
501.Ss \&AT
502Sets the volume for the footer for compatibility with man pages from
503.Tn AT&T UNIX
504releases.
505The optional arguments specify which release it is from.
506.Ss \&B
507Text is rendered in bold face.
508.Pp
509See also
510.Sx \&I
511and
512.Sx \&R .
513.Ss \&BI
514Text is rendered alternately in bold face and italic.
515Thus,
516.Sq .BI this word and that
517causes
518.Sq this
519and
520.Sq and
521to render in bold face, while
522.Sq word
523and
524.Sq that
525render in italics.
526Whitespace between arguments is omitted in output.
527.Pp
528Examples:
529.Pp
530.Dl \&.BI bold italic bold italic
531.Pp
532The output of this example will be emboldened
533.Dq bold
534and italicised
535.Dq italic ,
536with spaces stripped between arguments.
537.Pp
538See also
539.Sx \&IB ,
540.Sx \&BR ,
541.Sx \&RB ,
542.Sx \&RI ,
543and
544.Sx \&IR .
545.Ss \&BR
546Text is rendered alternately in bold face and roman (the default font).
547Whitespace between arguments is omitted in output.
548.Pp
549See
550.Sx \&BI
551for an equivalent example.
552.Pp
553See also
554.Sx \&BI ,
555.Sx \&IB ,
556.Sx \&RB ,
557.Sx \&RI ,
558and
559.Sx \&IR .
560.Ss \&DT
561Has no effect.
562Included for compatibility.
563.Ss \&HP
564Begin a paragraph whose initial output line is left-justified, but
565subsequent output lines are indented, with the following syntax:
566.Bd -filled -offset indent
567.Pf \. Sx \&HP
568.Op Cm width
569.Ed
570.Pp
571The
572.Cm width
573argument must conform to
574.Sx Scaling Widths .
575If specified, it's saved for later paragraph left-margins; if unspecified, the
576saved or default width is used.
577.Pp
578See also
579.Sx \&IP ,
580.Sx \&LP ,
581.Sx \&P ,
582.Sx \&PP ,
583and
584.Sx \&TP .
585.Ss \&I
586Text is rendered in italics.
587.Pp
588See also
589.Sx \&B
590and
591.Sx \&R .
592.Ss \&IB
593Text is rendered alternately in italics and bold face.
594Whitespace between arguments is omitted in output.
595.Pp
596See
597.Sx \&BI
598for an equivalent example.
599.Pp
600See also
601.Sx \&BI ,
602.Sx \&BR ,
603.Sx \&RB ,
604.Sx \&RI ,
605and
606.Sx \&IR .
607.Ss \&IP
608Begin an indented paragraph with the following syntax:
609.Bd -filled -offset indent
610.Pf \. Sx \&IP
611.Op Cm head Op Cm width
612.Ed
613.Pp
614The
615.Cm width
616argument defines the width of the left margin and is defined by
617.Sx Scaling Widths .
618It's saved for later paragraph left-margins; if unspecified, the saved or
619default width is used.
620.Pp
621The
622.Cm head
623argument is used as a leading term, flushed to the left margin.
624This is useful for bulleted paragraphs and so on.
625.Pp
626See also
627.Sx \&HP ,
628.Sx \&LP ,
629.Sx \&P ,
630.Sx \&PP ,
631and
632.Sx \&TP .
633.Ss \&IR
634Text is rendered alternately in italics and roman (the default font).
635Whitespace between arguments is omitted in output.
636.Pp
637See
638.Sx \&BI
639for an equivalent example.
640.Pp
641See also
642.Sx \&BI ,
643.Sx \&IB ,
644.Sx \&BR ,
645.Sx \&RB ,
646and
647.Sx \&RI .
648.Ss \&LP
649Begin an undecorated paragraph.
650The scope of a paragraph is closed by a subsequent paragraph,
651sub-section, section, or end of file.
652The saved paragraph left-margin width is reset to the default.
653.Pp
654See also
655.Sx \&HP ,
656.Sx \&IP ,
657.Sx \&P ,
658.Sx \&PP ,
659and
660.Sx \&TP .
661.Ss \&P
662Synonym for
663.Sx \&LP .
664.Pp
665See also
666.Sx \&HP ,
667.Sx \&IP ,
668.Sx \&LP ,
669.Sx \&PP ,
670and
671.Sx \&TP .
672.Ss \&PP
673Synonym for
674.Sx \&LP .
675.Pp
676See also
677.Sx \&HP ,
678.Sx \&IP ,
679.Sx \&LP ,
680.Sx \&P ,
681and
682.Sx \&TP .
683.Ss \&R
684Text is rendered in roman (the default font).
685.Pp
686See also
687.Sx \&I
688and
689.Sx \&B .
690.Ss \&RB
691Text is rendered alternately in roman (the default font) and bold face.
692Whitespace between arguments is omitted in output.
693.Pp
694See
695.Sx \&BI
696for an equivalent example.
697.Pp
698See also
699.Sx \&BI ,
700.Sx \&IB ,
701.Sx \&BR ,
702.Sx \&RI ,
703and
704.Sx \&IR .
705.Ss \&RE
706Explicitly close out the scope of a prior
707.Sx \&RS .
708.Ss \&RI
709Text is rendered alternately in roman (the default font) and italics.
710Whitespace between arguments is omitted in output.
711.Pp
712See
713.Sx \&BI
714for an equivalent example.
715.Pp
716See also
717.Sx \&BI ,
718.Sx \&IB ,
719.Sx \&BR ,
720.Sx \&RB ,
721and
722.Sx \&IR .
723.Ss \&RS
724Begin a part setting the left margin.
725The left margin controls the offset, following an initial indentation,
726to un-indented text such as that of
727.Sx \&PP .
728This has the following syntax:
729.Bd -filled -offset indent
730.Pf \. Sx \&Rs
731.Op Cm width
732.Ed
733.Pp
734The
735.Cm width
736argument must conform to
737.Sx Scaling Widths .
738If not specified, the saved or default width is used.
739.Ss \&SB
740Text is rendered in small size (one point smaller than the default font)
741bold face.
742.Ss \&SH
743Begin a section.
744The scope of a section is only closed by another section or the end of
745file.
746The paragraph left-margin width is reset to the default.
747.Ss \&SM
748Text is rendered in small size (one point smaller than the default
749font).
750.Ss \&SS
751Begin a sub-section.
752The scope of a sub-section is closed by a subsequent sub-section,
753section, or end of file.
754The paragraph left-margin width is reset to the default.
755.Ss \&TH
756Sets the title of the manual page with the following syntax:
757.Bd -filled -offset indent
758.Pf \. Sx \&TH
759.Cm title section
760.Op Cm date Op Cm source Op Cm volume
761.Ed
762.Pp
763At least the upper-case document
764.Cm title
765and the manual
766.Cm section
767arguments must be provided.
768The
769.Cm date
770argument should be formatted as described in
771.Sx Dates ,
772but will be printed verbatim if it is not.
773If the date is not specified, the current date is used.
774The
775.Cm source
776string specifies the organisation providing the utility.
777The
778.Cm volume
779string replaces the default rendered volume, which is dictated by the
780manual section.
781.Pp
782Examples:
783.Pp
784.Dl \&.TH CVS 5 "1992-02-12" GNU
785.Ss \&TP
786Begin a paragraph where the head, if exceeding the indentation width, is
787followed by a newline; if not, the body follows on the same line after a
788buffer to the indentation width.
789Subsequent output lines are indented.
790The syntax is as follows:
791.Bd -filled -offset indent
792.Pf \. Sx \&TP
793.Op Cm width
794.Ed
795.Pp
796The
797.Cm width
798argument must conform to
799.Sx Scaling Widths .
800If specified, it's saved for later paragraph left-margins; if
801unspecified, the saved or default width is used.
802.Pp
803See also
804.Sx \&HP ,
805.Sx \&IP ,
806.Sx \&LP ,
807.Sx \&P ,
808and
809.Sx \&PP .
810.Ss \&UC
811Sets the volume for the footer for compatibility with man pages from
812BSD releases.
813The optional first argument specifies which release it is from.
814.Ss \&br
815Breaks the current line.
816Consecutive invocations have no further effect.
817.Pp
818See also
819.Sx \&sp .
820.Ss \&fi
821End literal mode begun by
822.Sx \&nf .
823.Ss \&ft
824Change the current font mode.
825See
826.Sx Text Decoration
827for a listing of available font modes.
828.Ss \&in
829Indent relative to the current indentation:
830.Pp
831.D1 Pf \. Sx \&in Op Cm width
832.Pp
833If
834.Cm width
835is signed, the new offset is relative.
836Otherwise, it is absolute.
837This value is reset upon the next paragraph, section, or sub-section.
838.Ss \&na
839Don't align to the right margin.
840.Ss \&nf
841Begin literal mode: all subsequent free-form lines have their end of
842line boundaries preserved.
843May be ended by
844.Sx \&fi .
845.Ss \&sp
846Insert vertical spaces into output with the following syntax:
847.Bd -filled -offset indent
848.Pf \. Sx \&sp
849.Op Cm height
850.Ed
851.Pp
852Insert
853.Cm height
854spaces, which must conform to
855.Sx Scaling Widths .
856If 0, this is equivalent to the
857.Sx \&br
858macro.
859Defaults to 1, if unspecified.
860.Pp
861See also
862.Sx \&br .
863.Sh COMPATIBILITY
864This section documents areas of questionable portability between
865implementations of the
866.Nm
867language.
868.Pp
869.Bl -dash -compact
870.It
871In quoted literals, GNU troff allowed pair-wise double-quotes to produce
872a standalone double-quote in formatted output.
873It is not known whether this behaviour is exhibited by other formatters.
874.It
875troff suppresses a newline before
876.Sq \(aq
877macro output; in mandoc, it is an alias for the standard
878.Sq \&.
879control character.
880.It
881The
882.Sq \eh
883.Pq horizontal position ,
884.Sq \ev
885.Pq vertical position ,
886.Sq \em
887.Pq text colour ,
888.Sq \eM
889.Pq text filling colour ,
890.Sq \ez
891.Pq zero-length character ,
892.Sq \ew
893.Pq string length ,
894.Sq \ek
895.Pq horizontal position marker ,
896.Sq \eo
897.Pq text overstrike ,
898and
899.Sq \es
900.Pq text size
901escape sequences are all discarded in mandoc.
902.It
903The
904.Sq \ef
905scaling unit is accepted by mandoc, but rendered as the default unit.
906.It
907The
908.Sx \&sp
909macro does not accept negative values in mandoc.
910In GNU troff, this would result in strange behaviour.
911.El
912.Sh SEE ALSO
913.Xr man 1 ,
914.Xr mandoc 1 ,
915.Xr mandoc_char 7 ,
916.Xr mdoc 7 ,
917.Xr roff 7 ,
918.Xr tbl 7
919.Sh HISTORY
920The
921.Nm
922language first appeared as a macro package for the roff typesetting
923system in
924.At v7 .
925It was later rewritten by James Clark as a macro package for groff.
926The stand-alone implementation that is part of the
927.Xr mandoc 1
928utility written by Kristaps Dzonsons appeared in
929.Ox 4.6 .
930.Sh AUTHORS
931This
932.Nm
933reference was written by
934.An Kristaps Dzonsons Aq kristaps@bsd.lv .
935.Sh CAVEATS
936Do not use this language.
937Use
938.Xr mdoc 7 ,
939instead.