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