Differential D28642 Diff 83924 share/man/man5/style.mdoc.5

Changeset View

Standalone View

share/man/man5/style.mdoc.5

	Show All 34 Lines
	.Fx			.Fx
	.Xr mdoc 7			.Xr mdoc 7
	file style guide			file style guide
	.Sh DESCRIPTION			.Sh DESCRIPTION
	This file specifies the preferred style for manual pages in the			This file specifies the preferred style for manual pages in the
	.Fx			.Fx
	source tree.			source tree.
	.Ss Code Examples			.Ss Code Examples
	.Bl -dash -width ""
	.It
	Use literal formatting for examples and literal shell commands, e.g.:			Use literal formatting for examples and literal shell commands, e.g.:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	Then run			Then run
	\&.Dq Li make install clean .			\&.Dq Li make install clean .
	.Ed			.Ed
	.Pp			.Pp
	which renders as:			which renders as:
	.Bd -filled -offset indent			.Bd -filled -offset indent
	Show All 9 Lines
	\&.Dq Nm make Cm install Cm clean .			\&.Dq Nm make Cm install Cm clean .
	.Ed			.Ed
	.Pp			.Pp
	which renders as:			which renders as:
	.Bd -filled -offset indent			.Bd -filled -offset indent
	Then run			Then run
	.Dq Nm make Cm install Cm clean .			.Dq Nm make Cm install Cm clean .
	.Ed			.Ed
	.El
	.Ss EXAMPLES Section			.Ss EXAMPLES Section
	.Bl -dash -width ""
	.It
	Format the			Format the
	.Sx EXAMPLES			.Sx EXAMPLES
	section in the following way:			section in the following way:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	\&.Bl -tag -width 0n			\&.Bl -tag -width 0n
	\&.It Sy Example 1\\&: No Doing Something			\&.It Sy Example 1\\&: No Doing Something
	\&.Pp			\&.Pp
	The following command does something.			The following command does something.
	Show All 25 Lines
	The following command does something different.			The following command does something different.
	.Bd -literal -offset 2n			.Bd -literal -offset 2n
	.Li # Ic bectl list			.Li # Ic bectl list
	.Ed			.Ed
	.Pp			.Pp
	It is good to know this command.			It is good to know this command.
	.El			.El
	.Ed			.Ed
	.El
	.Ss Synopsis Formatting			.Ss Synopsis Formatting
	.Bl -dash -width ""
	.It
	Do not put whitespace between alternative parameters separated with a pipe			Do not put whitespace between alternative parameters separated with a pipe
	.Pq Dq \| ,			.Pq Dq \| ,
	e.g.:			e.g.:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	\&.Cm compression Cm on Ns \| Ns Cm off			\&.Cm compression Cm on Ns \| Ns Cm off
	\&.Cm install Fl -all Ns \| Ns Ar portname Ar ...			\&.Cm install Fl -all Ns \| Ns Ar portname Ar ...
	.Ed			.Ed
	.Pp			.Pp
	which in the SYNOPSIS section is rendered as:			which in the SYNOPSIS section is rendered as:
	.Bd -unfilled -offset indent			.Bd -unfilled -offset indent
	.Cm compression Cm on Ns \| Ns Cm off			.Cm compression Cm on Ns \| Ns Cm off
	.Cm install Fl -all Ns \| Ns Ar portname Ar ...			.Cm install Fl -all Ns \| Ns Ar portname Ar ...
	.Ed			.Ed
	.It			.Pp
	Use			Use
	.Sy \&Cm			.Sy \&Cm
	to stylize characters that are command modifiers			to stylize characters that are command modifiers
	.Po e.g.,			.Po e.g.,
	.Dq \&, ,			.Dq \&, ,
	.Dq @			.Dq @
	or			or
	.Dq "="			.Dq "="
	Show All 35 Lines
	.Sy \&Cm .			.Sy \&Cm .
	At the same time, the square brackets			At the same time, the square brackets
	.Pq Dq "[]"			.Pq Dq "[]"
	are not stylized as they do not belong to the syntax of the			are not stylized as they do not belong to the syntax of the
	.Fl -meet			.Fl -meet
	flag.			flag.
	.El			.El
	.Ss Quoting			.Ss Quoting
	.Bl -dash -width ""
	.It
	Use the			Use the
	.Sy \&Dq			.Sy \&Dq
	.Pq Do Dc			.Pq Do Dc
	macro			macro
	for quoting.			for quoting.
	Use the			Use the
	.Sy \&Sq			.Sy \&Sq
	.Pq So Sc			.Pq So Sc
	macro for quoting inside quotes.			macro for quoting inside quotes.
	The use of the			The use of the
	.Sy \&Qq			.Sy \&Qq
	.Pq Qo Qc			.Pq Qo Qc
	macro is usually not necessary.			macro is usually not necessary.
	.El			.Ss Loader Tunables And Sysctl Variables
	.Ss Variables			Loader tunables and sysctl variables should be documented in
	.Bl -dash -width ""			.Qq LOADER TUNABLES
	.It			and
	Use			.Qq SYSCTL VARIABLES
				sections, respectively.
				Both sections should provide them inside an
				.Sy \&Bl -tag
				list block using the
	.Sy \&Va			.Sy \&Va
	instead of			macro.
	.Sy \&Dv			Note that
	for			.Xr makewhatis 8
	.Xr sysctl 8			only special cases them if found after the
	variables like			.Sy \&It
	.Va kdb.enter.panic .			macro, and for
	.It			.Xr man 1
				to be able to do tunable/sysctl search, the following format should be used:
				.Bd -literal -offset indent
				\&.Sh LOADER TUNABLES
				Tunables can be set at the
				\&.Xr loader 8
				prompt before booting the kernel or stored in
				\&.Xr loader.conf 5 .
				\&.Bl -tag -width indent
				\&.It Va some.loader.tunable
				Tunable description.
				\&.El
				\&.Sh SYSCTL VARIABLES
				The following variables are available as both
				\&.Xr sysctl 8
				variables and
				\&.Xr loader 8
				tunables:
				\&.Bl -tag -width indent
				\&.It Va some.sysctl.variable
				Variable description.
				\&.El
				.Ed
				.Ss Variables
	Use the angle brackets			Use the angle brackets
	.Sy \&Aq			.Sy \&Aq
	.Pq Dq "<>"			.Pq Dq "<>"
	macro			macro
	for arguments			for arguments
	.Pq Sy \&Ar			.Pq Sy \&Ar
	when they are mixed with similarly stylized macros like			when they are mixed with similarly stylized macros like
	.Sy \&Pa			.Sy \&Pa
	Show All 13 Lines
	.Bd -literal -offset indent			.Bd -literal -offset indent
	\&.Va critical_filesystems_ Ns Ar type			\&.Va critical_filesystems_ Ns Ar type
	.Ed			.Ed
	.Pp			.Pp
	that would be rendered as:			that would be rendered as:
	.Bd -filled -offset indent			.Bd -filled -offset indent
	.Va critical_filesystems_ Ns Ar type			.Va critical_filesystems_ Ns Ar type
	.Ed			.Ed
	.El
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr man 1 ,			.Xr man 1 ,
	.Xr mandoc 1 ,			.Xr mandoc 1 ,
	.Xr mdoc 7 ,			.Xr mdoc 7 ,
	.Xr style 9			.Xr style 9
	.Sh HISTORY			.Sh HISTORY
	This manual page first appeared in			This manual page first appeared in
	.Fx 13.0 .			.Fx 13.0 .
	.Sh AUTHORS			.Sh AUTHORS
	.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org			.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org