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 | |||||