Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MAN(7)		     BSD Miscellaneous Information Manual		MAN(7)

NAME
     man -- legacy formatting language for manual pages

DESCRIPTION
     Traditionally, the	man language has been used to write UNIX manuals for
     the man(1)	utility.  It supports limited control of presentational	de-
     tails like	fonts, indentation and spacing.	 This reference	document de-
     scribes the structure of manual pages and the syntax and usage of the man
     language.

     Do	not use	man to write your manuals: It lacks support for	semantic
     markup.  Use the mdoc(7) language,	instead.

     In	a man document,	lines beginning	with the control character `.' are
     called "macro lines".  The	first word is the macro	name.  It usually con-
     sists of two capital letters.  For	a list of available macros, see	MACRO
     OVERVIEW.	The words following the	macro name are arguments to the	macro.

     Lines not beginning with the control character are	called "text lines".
     They provide free-form text to be printed;	the formatting of the text de-
     pends on the respective processing	context:

	   .SH Macro lines change control state.
	   Text	lines are interpreted within the current state.

     Many aspects of the basic syntax of the man language are based on the
     roff(7) language; see the LANGUAGE	SYNTAX and MACRO SYNTAX	sections in
     the roff(7) manual	for details, in	particular regarding comments, escape
     sequences,	whitespace, and	quoting.

MANUAL STRUCTURE
     Each man document must contain the	TH macro describing the	document's
     section and title.	 It may	occur anywhere in the document,	although con-
     ventionally it appears as the first macro.

     Beyond TH,	at least one macro or text line	must appear in the document.

     The following is a	well-formed skeleton man file for a utility
     "progname":

	   .TH PROGNAME	1 2009-10-10
	   .SH NAME
	   \fBprogname\fR \(en one line	about what it does
	   .\" .SH LIBRARY
	   .\" For sections 2, 3, and 9	only.
	   .\" Not used	in OpenBSD.
	   .SH SYNOPSIS
	   \fBprogname\fR [\fB\-options\fR] \fIfile ...\fR
	   .SH DESCRIPTION
	   The \fBfoo\fR utility processes files ...
	   .\" .Sh CONTEXT
	   .\" For section 9 functions only.
	   .\" .SH IMPLEMENTATION NOTES
	   .\" Not used	in OpenBSD.
	   .\" .SH RETURN VALUES
	   .\" For sections 2, 3, and 9	function return	values only.
	   .\" .SH ENVIRONMENT
	   .\" For sections 1, 6, 7, and 8 only.
	   .\" .SH FILES
	   .\" .SH EXIT	STATUS
	   .\" For sections 1, 6, and 8	only.
	   .\" .SH EXAMPLES
	   .\" .SH DIAGNOSTICS
	   .\" For sections 1, 4, 6, 7,	8, and 9 printf/stderr messages	only.
	   .\" .SH ERRORS
	   .\" For sections 2, 3, 4, and 9 errno settings only.
	   .\" .SH SEE ALSO
	   .\" .BR foobar ( 1 )
	   .\" .SH STANDARDS
	   .\" .SH HISTORY
	   .\" .SH AUTHORS
	   .\" .SH CAVEATS
	   .\" .SH BUGS
	   .\" .SH SECURITY CONSIDERATIONS
	   .\" Not used	in OpenBSD.

     The sections in a man document are	conventionally ordered as they appear
     above.  Sections should be	composed as follows:

	   NAME
	   The name(s) and a short description of the documented material.
	   The syntax for this is generally as follows:

		 \fBname\fR \(en description

	   LIBRARY
	   The name of the library containing the documented material, which
	   is assumed to be a function in a section 2 or 3 manual.  For	func-
	   tions in the	C library, this	may be as follows:

		 Standard C Library (libc, -lc)

	   SYNOPSIS
	   Documents the utility invocation syntax, function call syntax, or
	   device configuration.

	   For the first, utilities (sections 1, 6, and	8), this is generally
	   structured as follows:

		 \fBname\fR [-\fBab\fR]	[-\fBc\fR\fIarg\fR] \fBpath\fR...

	   For the second, function calls (sections 2, 3, 9):

		 .B char *name(char *\fIarg\fR);

	   And for the third, configurations (section 4):

		 .B name* at cardbus? function?

	   Manuals not in these	sections generally don't need a	SYNOPSIS.

	   DESCRIPTION
	   This	expands	upon the brief,	one-line description in	NAME.  It usu-
	   ally	contains a break-down of the options (if documenting a com-
	   mand).

	   CONTEXT
	   This	section	lists the contexts in which functions can be called in
	   section 9.  The contexts are	autoconf, process, or interrupt.

	   IMPLEMENTATION NOTES
	   Implementation-specific notes should	be kept	here.  This is useful
	   when	implementing standard functions	that may have side effects or
	   notable algorithmic implications.

	   RETURN VALUES
	   This	section	documents the return values of functions in sections
	   2, 3, and 9.

	   ENVIRONMENT
	   Documents any usages	of environment variables, e.g.,	environ(7).

	   FILES
	   Documents files used.  It's helpful to document both	the file name
	   and a short description of how the file is used (created, modified,
	   etc.).

	   EXIT	STATUS
	   This	section	documents the command exit status for section 1, 6,
	   and 8 utilities.  Historically, this	information was	described in
	   DIAGNOSTICS,	a practise that	is now discouraged.

	   EXAMPLES
	   Example usages.  This often contains	snippets of well-formed, well-
	   tested invocations.	Make sure that examples	work properly!

	   DIAGNOSTICS
	   Documents error conditions.	In section 4 and 9 manuals, these are
	   usually messages printed by the kernel to the console and to	the
	   kernel log.	In section 1, 6, 7, and	8, these are usually messages
	   printed by userland programs	to the standard	error output.

	   Historically, this section was used in place	of EXIT	STATUS for
	   manuals in sections 1, 6, and 8; however, this practise is discour-
	   aged.

	   ERRORS
	   Documents errno(2) settings in sections 2, 3, 4, and	9.

	   SEE ALSO
	   References other manuals with related topics.  This section should
	   exist for most manuals.

		 .BR bar ( 1 ),

	   Cross-references should conventionally be ordered first by section,
	   then	alphabetically.

	   STANDARDS
	   References any standards implemented	or used, such as

		 IEEE Std 1003.2 (\(lqPOSIX.2\(rq)

	   If not adhering to any standards, the HISTORY section should	be
	   used.

	   HISTORY
	   A brief history of the subject, including where support first ap-
	   peared.

	   AUTHORS
	   Credits to the person or persons who	wrote the code and/or documen-
	   tation.  Authors should generally be	noted by both name and email
	   address.

	   CAVEATS
	   Common misuses and misunderstandings	should be explained in this
	   section.

	   BUGS
	   Known bugs, limitations, and	work-arounds should be described in
	   this	section.

	   SECURITY CONSIDERATIONS
	   Documents any security precautions that operators should consider.

MACRO OVERVIEW
     This overview is sorted such that macros of similar purpose are listed
     together, to help find the	best macro for any given purpose.  Deprecated
     macros are	not included in	the overview, but can be found in the alpha-
     betical reference below.

   Page	header and footer meta-data
     TH		  set the title: title section date [source [volume]]
     AT		  display AT&T UNIX version in the page	footer (<= 1 argument)
     UC		  display BSD version in the page footer (<= 1 argument)

   Sections and	paragraphs
     SH		  section header (one line)
     SS		  subsection header (one line)
     PP, LP, P	  start	an undecorated paragraph (no arguments)
     RS, RE	  reset	the left margin: [width]
     IP		  indented paragraph: [head [width]]
     TP		  tagged paragraph: [width]
     HP		  hanged paragraph: [width]
     PD		  set vertical paragraph distance: [height]
     br		  force	output line break in text mode (no arguments)
     sp		  force	vertical space:	[height]
     fi, nf	  fill mode and	no-fill	mode (no arguments)
     in		  additional indent: [width]

   Physical markup
     B		  boldface font
     I		  italic font
     R		  roman	(default) font
     SB		  small	boldface font
     SM		  small	roman font
     BI		  alternate between boldface and italic	fonts
     BR		  alternate between boldface and roman fonts
     IB		  alternate between italic and boldface	fonts
     IR		  alternate between italic and roman fonts
     RB		  alternate between roman and boldface fonts
     RI		  alternate between roman and italic fonts

MACRO REFERENCE
     This section is a canonical reference to all macros, arranged alphabeti-
     cally.  For the scoping of	individual macros, see MACRO SYNTAX.

   AT
     Sets the volume for the footer for	compatibility with man pages from AT&T
     UNIX releases.  The optional arguments specify which release it is	from.

   B
     Text is rendered in bold face.

     See also I	and R.

   BI
     Text is rendered alternately in bold face and italic.  Thus, `.BI this
     word and that' causes `this' and `and' to render in bold face, while
     `word' and	`that' render in italics.  Whitespace between arguments	is
     omitted in	output.

     Examples:

	   .BI bold italic bold	italic

     The output	of this	example	will be	emboldened "bold" and italicised
     "italic", with spaces stripped between arguments.

     See also IB, BR, RB, RI, and IR.

   BR
     Text is rendered alternately in bold face and roman (the default font).
     Whitespace	between	arguments is omitted in	output.

     See BI for	an equivalent example.

     See also BI, IB, RB, RI, and IR.

   DT
     Has no effect.  Included for compatibility.

   EE
     This is a non-standard GNU	extension, included only for compatibility.
     In	mandoc(1), it does the same as fi.

   EX
     This is a non-standard GNU	extension, included only for compatibility.
     In	mandoc(1), it does the same as nf.

   HP
     Begin a paragraph whose initial output line is left-justified, but	subse-
     quent output lines	are indented, with the following syntax:

	   .HP [width]

     The width argument	is a roff(7) scaling width.  If	specified, it's	saved
     for later paragraph left-margins; if unspecified, the saved or default
     width is used.

     See also IP, LP, P, PP, and TP.

   I
     Text is rendered in italics.

     See also B	and R.

   IB
     Text is rendered alternately in italics and bold face.  Whitespace	be-
     tween arguments is	omitted	in output.

     See BI for	an equivalent example.

     See also BI, BR, RB, RI, and IR.

   IP
     Begin an indented paragraph with the following syntax:

	   .IP [head [width]]

     The width argument	is a roff(7) scaling width defining the	left margin.
     It's saved	for later paragraph left-margins; if unspecified, the saved or
     default width is used.

     The head argument is used as a leading term, flushed to the left margin.
     This is useful for	bulleted paragraphs and	so on.

     See also HP, LP, P, PP, and TP.

   IR
     Text is rendered alternately in italics and roman (the default font).
     Whitespace	between	arguments is omitted in	output.

     See BI for	an equivalent example.

     See also BI, IB, BR, RB, and RI.

   LP
     Begin an undecorated paragraph.  The scope	of a paragraph is closed by a
     subsequent	paragraph, sub-section,	section, or end	of file.  The saved
     paragraph left-margin width is reset to the default.

     See also HP, IP, P, PP, and TP.

   OP
     Optional command-line argument.  This is a	non-standard GNU extension,
     included only for compatibility.  It has the following syntax:

	   .OP key [value]

     The key is	usually	a command-line flag and	value its argument.

   P
     Synonym for LP.

     See also HP, IP, LP, PP, and TP.

   PD
     Specify the vertical space	to be inserted before each new paragraph.
     The syntax	is as follows:

	   .PD [height]

     The height	argument is a roff(7) scaling width.  It defaults to 1v.  If
     the unit is omitted, v is assumed.

     This macro	affects	the spacing before any subsequent instances of HP, IP,
     LP, P, PP,	SH, SS,	and TP.

   PP
     Synonym for LP.

     See also HP, IP, LP, P, and TP.

   R
     Text is rendered in roman (the default font).

     See also I	and B.

   RB
     Text is rendered alternately in roman (the	default	font) and bold face.
     Whitespace	between	arguments is omitted in	output.

     See BI for	an equivalent example.

     See also BI, IB, BR, RI, and IR.

   RE
     Explicitly	close out the scope of a prior RS.  The	default	left margin is
     restored to the state before that RS invocation.

     The syntax	is as follows:

	   .RE [level]

     Without an	argument, the most recent RS block is closed out.  If level is
     1,	all open RS blocks are closed out.  Otherwise, level - 1 nested	RS
     blocks remain open.

   RI
     Text is rendered alternately in roman (the	default	font) and italics.
     Whitespace	between	arguments is omitted in	output.

     See BI for	an equivalent example.

     See also BI, IB, BR, RB, and IR.

   RS
     Temporarily reset the default left	margin.	 This has the following	syn-
     tax:

	   .RS [width]

     The width argument	is a roff(7) scaling width.  If	not specified, the
     saved or default width is used.

     See also RE.

   SB
     Text is rendered in small size (one point smaller than the	default	font)
     bold face.

   SH
     Begin a section.  The scope of a section is only closed by	another	sec-
     tion or the end of	file.  The paragraph left-margin width is reset	to the
     default.

   SM
     Text is rendered in small size (one point smaller than the	default	font).

   SS
     Begin a sub-section.  The scope of	a sub-section is closed	by a subse-
     quent sub-section,	section, or end	of file.  The paragraph	left-margin
     width is reset to the default.

   TH
     Sets the title of the manual page for use in the page header and footer
     with the following	syntax:

	   .TH title section date [source [volume]]

     Conventionally, the document title	is given in all	caps.  The recommended
     date format is YYYY-MM-DD as specified in the ISO-8601 standard; if the
     argument does not conform,	it is printed verbatim.	 If the	date is	empty
     or	not specified, the current date	is used.  The optional source string
     specifies the organisation	providing the utility.	When unspecified,
     mandoc(1) uses its	-Ios argument.	The volume string replaces the default
     rendered volume, which is dictated	by the manual section.

     Examples:

	   .TH CVS 5 1992-02-12	GNU

   TP
     Begin a paragraph where the head, if exceeding the	indentation width, is
     followed by a newline; if not, the	body follows on	the same line after a
     buffer to the indentation width.  Subsequent output lines are indented.
     The syntax	is as follows:

	   .TP [width]

     The width argument	is a roff(7) scaling width.  If	specified, it's	saved
     for later paragraph left-margins; if unspecified, the saved or default
     width is used.

     See also HP, IP, LP, P, and PP.

   UC
     Sets the volume for the footer for	compatibility with man pages from BSD
     releases.	The optional first argument specifies which release it is
     from.

   UE
     End a uniform resource identifier block.  This is a non-standard GNU ex-
     tension, included only for	compatibility.	See UE.

   UR
     Begin a uniform resource identifier block.	 This is a non-standard	GNU
     extension,	included only for compatibility.  It has the following syntax:

	   .UR uri
	   link	description to be shown
	   .UE

   br
     Breaks the	current	line.  Consecutive invocations have no further effect.

     See also sp.

   fi
     End literal mode begun by nf.

   in
     Indent relative to	the current indentation:

	   .in [width]

     If	width is signed, the new offset	is relative.  Otherwise, it is abso-
     lute.  This value is reset	upon the next paragraph, section, or sub-sec-
     tion.

   nf
     Begin literal mode: all subsequent	free-form lines	have their end of line
     boundaries	preserved.  May	be ended by fi.	 Literal mode is implicitly
     ended by SH or SS.

   sp
     Insert vertical spaces into output	with the following syntax:

	   .sp [height]

     The height	argument is a scaling width as described in roff(7).  If 0,
     this is equivalent	to the br macro.  Defaults to 1, if unspecified.

     See also br.

MACRO SYNTAX
     The man macros are	classified by scope: line scope	or block scope.	 Line
     macros are	only scoped to the current line	(and, in some situations, the
     subsequent	line).	Block macros are scoped	to the current line and	subse-
     quent lines until closed by another block macro.

   Line	Macros
     Line macros are generally scoped to the current line, with	the body con-
     sisting of	zero or	more arguments.	 If a macro is scoped to the next line
     and the line arguments are	empty, the next	line, which must be text, is
     used instead.  Thus:

	   .I
	   foo

     is	equivalent to `.I foo'.	 If next-line macros are invoked consecu-
     tively, only the last is used.  If	a next-line macro is followed by a
     non-next-line macro, an error is raised, except for br and	sp.

     The syntax	is as follows:

	   .YO [body...]
	   [body...]

	   Macro     Arguments	   Scope	 Notes
	   AT	     <=1	   current
	   B	     n		   next-line
	   BI	     n		   current
	   BR	     n		   current
	   DT	     0		   current
	   EE	     0		   current	 compat
	   EX	     0		   current	 compat
	   I	     n		   next-line
	   IB	     n		   current
	   IR	     n		   current
	   OP	     0,	1	   current	 compat
	   PD	     1		   current
	   R	     n		   next-line
	   RB	     n		   current
	   RI	     n		   current
	   SB	     n		   next-line
	   SM	     n		   next-line
	   TH	     >1, <6	   current
	   UC	     <=1	   current
	   br	     0		   current	 compat
	   fi	     0		   current	 compat
	   in	     1		   current	 compat
	   nf	     0		   current	 compat
	   sp	     1		   current	 compat

     Macros marked as "compat" are included for	compatibility with the signif-
     icant corpus of existing manuals that mix dialects	of roff.  These	macros
     should not	be used	for portable man manuals.

   Block Macros
     Block macros comprise a head and body.  As	with in-line macros, the head
     is	scoped to the current line and,	in one circumstance, the next line
     (the next-line stipulations as in Line Macros apply here as well).

     The syntax	is as follows:

	   .YO [head...]
	   [head...]
	   [body...]

     The closure of body scope may be to the section, where a macro is closed
     by	SH; sub-section, closed	by a section or	SS; part, closed by a section,
     sub-section, or RE; or paragraph, closed by a section, sub-section, part,
     HP, IP, LP, P, PP,	or TP.	No closure refers to an	explicit block closing
     macro.

     As	a rule,	block macros may not be	nested;	thus, calling a	block macro
     while another block macro scope is	open, and the open scope is not	im-
     plicitly closed, is syntactically incorrect.

	   Macro    Arguments	 Head Scope    Body Scope     Notes
	   HP	    <2		 current       paragraph
	   IP	    <3		 current       paragraph
	   LP	    0		 current       paragraph
	   P	    0		 current       paragraph
	   PP	    0		 current       paragraph
	   RE	    0		 current       none	      compat
	   RS	    1		 current       part	      compat
	   SH	    >0		 next-line     section
	   SS	    >0		 next-line     sub-section
	   TP	    n		 next-line     paragraph
	   UE	    0		 current       none	      compat
	   UR	    1		 current       part	      compat

     Macros marked "compat" are	as mentioned in	Line Macros.

     If	a block	macro is next-line scoped, it may only be followed by in-line
     macros for	decorating text.

   Font	handling
     In	man documents, both Physical markup macros and roff(7) `\f' font es-
     cape sequences can	be used	to choose fonts.  In text lines, the effect of
     manual font selection by escape sequences only lasts until	the next macro
     invocation; in macro lines, it only lasts until the end of	the macro
     scope.  Note that macros like BR open and close a font scope for each ar-
     gument.

SEE ALSO
     man(1), mandoc(1),	eqn(7),	mandoc_char(7),	mdoc(7), roff(7), tbl(7)

HISTORY
     The man language first appeared as	a macro	package	for the	roff typeset-
     ting system in Version 7 AT&T UNIX.  It was later rewritten by James
     Clark as a	macro package for groff.  Eric S. Raymond wrote	the extended
     man macros	for groff in 2007.  The	stand-alone implementation that	is
     part of the mandoc(1) utility written by Kristaps Dzonsons	appeared in
     OpenBSD 4.6.

AUTHORS
     This man reference	was written by Kristaps	Dzonsons <kristaps@bsd.lv>.

CAVEATS
     Do	not use	this language.	Use mdoc(7), instead.

BSD			       January 29, 2015				   BSD

NAME | DESCRIPTION | MANUAL STRUCTURE | MACRO OVERVIEW | MACRO REFERENCE | MACRO SYNTAX | SEE ALSO | HISTORY | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=man&sektion=7&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help