Changeset View
Changeset View
Standalone View
Standalone View
share/man/man5/style.mdoc.5
.\" | .\" | ||||
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | ||||
.\" | .\" | ||||
.\" Copyright (c) 2018-2019 Mateusz Piotrowski <0mp@FreeBSD.org> | .\" Copyright (c) 2018-2021 Mateusz Piotrowski <0mp@FreeBSD.org> | ||||
.\" | .\" | ||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
.\" are met: | .\" are met: | ||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||
.\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||
.\" | .\" | ||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | ||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | ||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd June 30, 2020 | .Dd December 3, 2021 | ||||
.Dt STYLE.MDOC 5 | .Dt STYLE.MDOC 5 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm style.mdoc | .Nm style.mdoc | ||||
.Nd | .Nd | ||||
.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 "" | .Bl -dash -width "" | ||||
.It | .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 . | \&.Ql make install clean . | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
which renders as: | which renders as: | ||||
.Bd -filled -offset indent | .Bd -filled -offset indent | ||||
Then run | Then run | ||||
.Dq Li make install clean . | .Ql make install clean . | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
The incorrect way would be to use macros like | The incorrect way would be to use macros like | ||||
.Sy \&Nm | .Sy \&Nm | ||||
to stylize the command invocation: | to stylize the command invocation: | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
Then run | Then run | ||||
\&.Dq Nm make Cm install Cm clean . | \&.Ql 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 . | .Ql Nm make Cm install Cm clean . | ||||
.Ed | .Ed | ||||
.It | |||||
The | |||||
.Sy \&Ql | |||||
macro is the preferred macro for formatting literal inline fragments. | |||||
Historically, | |||||
.Sy \&Dq \&Li | |||||
was the preferred way before the deprecation of | |||||
.Sy \&Li . | |||||
.El | .El | ||||
.Ss EXAMPLES Section | .Ss EXAMPLES Section | ||||
.Bl -dash -width "" | .Bl -dash -width "" | ||||
.It | .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 | ||||
▲ Show 20 Lines • Show All 174 Lines • Show Last 20 Lines |