Differential D33394 Diff 102087 share/man/man5/style.mdoc.5

Changeset 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-2021 Mateusz Piotrowski <0mp@FreeBSD.org>			.\" Copyright (c) 2018-2022 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 December 3, 2021			.Dd January 29, 2022
	.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
	▲ Show 20 Lines • Show All 76 Lines • ▼ Show 20 Lines
	.Pp			.Pp
	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
				.El
				.Ss Lists
				.Bl -dash -width ""
				.It
				The
				.Fl width
				argument to the
				.Sy \&.Bl
				macro should match the length of the longest item in the list, e.g.:
				bjkUnsubmitted Not Done Inline Actions Should we note that when replicating the "longest item in the list" as the -width argument, macros should be excluded? bjk: Should we note that when replicating the "longest item in the list" as the -width argument…
				0mpAuthorUnsubmitted Done Inline Actions This is a nice idea. In a way, it's implicitly suggested in line 133 `\&.Bl -tag -width "-a address"`. But perhaps we can add an explicit note about this convention. 0mp: This is a nice idea. In a way, it's implicitly suggested in line 133 `\&.Bl -tag -width "-a…
				.Bd -literal -offset indent
				\&.Bl -tag -width "-a address"
				\&.It Fl a Ar address
				Set the address.
				\&.It Fl v
				Print the version.
				\&.El
				.Ed
				.Pp
				In case the longest item is too long and hurts readability,
				the recommendation is to set
				the
				.Fl width
				argument
				to
				.Ql indent ,
				e.g.:
				.Bd -literal -offset indent
				\&.Bl -tag -width "indent"
				\&.It Cm build
				Build the port.
				\&.It Cm install
				Install the port.
				\&.It Fl install-missing-packages
				Install the missing packages.
				\&.El
	.Ed			.Ed
	.El			.El
	.Ss Synopsis Formatting			.Ss Synopsis Formatting
	.Bl -dash -width ""			.Bl -dash -width ""
	.It			.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.:
	▲ Show 20 Lines • Show All 130 Lines • Show Last 20 Lines