git: 5ae48f972aa6 - stable/13 - style.mdoc.5: Document the conventions for -width

From: Mateusz Piotrowski <0mp_at_FreeBSD.org>
Date: Sat, 12 Feb 2022 16:07:18 UTC
The branch stable/13 has been updated by 0mp (doc, ports committer):

URL: https://cgit.FreeBSD.org/src/commit/?id=5ae48f972aa618483d8dd1090f19c8aad149e09d

commit 5ae48f972aa618483d8dd1090f19c8aad149e09d
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2022-01-29 21:23:49 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2022-02-12 16:07:08 +0000

    style.mdoc.5: Document the conventions for -width
    
    Reviewed by:    debdrup
    MFC after:      2 weeks
    Differential Revision:  https://reviews.freebsd.org/D33394
    
    (cherry picked from commit 79afae3b3f245ffa79726ae097cc843628ae9d92)
---
 share/man/man5/style.mdoc.5 | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/share/man/man5/style.mdoc.5 b/share/man/man5/style.mdoc.5
index f8ad4fb4029b..81f10b9df845 100644
--- a/share/man/man5/style.mdoc.5
+++ b/share/man/man5/style.mdoc.5
@@ -1,7 +1,7 @@
 .\"
 .\" 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
 .\" modification, are permitted provided that the following conditions
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 3, 2021
+.Dd January 29, 2022
 .Dt STYLE.MDOC 5
 .Os
 .Sh NAME
@@ -121,6 +121,42 @@ It is good to know this command.
 .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.:
+.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
+.El
 .Ss Synopsis Formatting
 .Bl -dash -width ""
 .It