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

FreeBSD Manual Pages

  
 
  

home | help 
STYLE.MDOC(5)		    BSD	File Formats Manual		 STYLE.MDOC(5)

NAME
     style.mdoc	-- FreeBSD mdoc(7) file	style guide

DESCRIPTION
     This file specifies the preferred style for manual	pages in the FreeBSD
     source tree.

   Code	Examples
     - Use literal formatting for examples and literal shell commands, e.g.:

	     Then run
	     .Dq Li make install clean .

       which renders as:

	     Then run "make install clean".

       The incorrect way would be to use macros	like Nm	to stylize the command
       invocation:

	     Then run
	     .Dq Nm make Cm install Cm clean .

       which renders as:

	     Then run "make install clean".

   EXAMPLES Section
     - Format the EXAMPLES section in the following way:

	     .Bl -tag -width 0n
	     .It Sy Example 1\&: No Doing Something
	     .Pp
	     The following command does	something.
	     .Bd -literal -offset 2n
	     .Li # Ic make -VLEGAL
	     .Ed
	     .It Sy Example 2\&: No Doing Something Different
	     .Pp
	     The following command does	something different.
	     .Bd -literal -offset 2n
	     .Li # Ic bectl list
	     .Ed
	     .Pp
	     It	is good	to know	this command.
	     .El

       which renders as:

	     Example 1:	Doing Something

	       The following command does something.

		 # make	-VLEGAL

	     Example 2:	Doing Something	Different

	       The following command does something different.

		 # bectl list

	       It is good to know this command.

   Synopsis Formatting
     - Do not put whitespace between alternative parameters separated with a
       pipe ("|"), e.g.:

	     .Cm compression Cm	on Ns |	Ns Cm off
	     .Cm install Fl -all Ns | Ns Ar portname Ar	...

       which in	the SYNOPSIS section is	rendered as:

	     compression on|off
	     install --all|portname ...

     - Use Cm to stylize characters that are command modifiers (e.g., ",", "@"
       or "=").	 For example:

	     .Sm off
	     .Fl -meet Cm = Ar who Oo Cm , Ar who " " Ar "..." Oc Cm @ Ar where
	     .Sm on

       which renders as:

	     --meet=who[,who ...]@where

       instead of:

	     .Sm off
	     .Fl -meet No = Ar who Oo ,	Ar who " " Ar "..." Oc @ Ar where
	     .Sm on

       which would render as:

	     --meet=who[,who ...]@where

       It is important to realize that in the correct example, ",", "@"	and
       "=" are stylized	with Cm.  At the same time, the	square brackets	("[]")
       are not stylized	as they	do not belong to the syntax of the --meet
       flag.

   Quoting
     - Use the Dq ("") macro for quoting.  Use the Sq (`') macro for quoting
       inside quotes.  The use of the Qq ("") macro is usually not necessary.

   Variables
     - Use Va instead of Dv for	sysctl(8) variables like kdb.enter.panic.

     - Use the angle brackets Aq ("<>")	macro for arguments (Ar) when they are
       mixed with similarly stylized macros like Pa or Va, e.g.:

	     .Va critical_filesystems_ Ns Aq Ar	type

       which renders as:

	     critical_filesystems_<type>

       instead of:

	     .Va critical_filesystems_ Ns Ar type

       that would be rendered as:

	     critical_filesystems_type

SEE ALSO
     man(1), mandoc(1),	mdoc(7), style(9)

HISTORY
     This manual page first appeared in	FreeBSD	13.0.

AUTHORS
     Mateusz Piotrowski	<0mp@FreeBSD.org>

BSD				 June 30, 2020				   BSD
NAME | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS

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

home | help