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