git: e7ff917057ea - main - style.mdoc.5: maintenence

From: Warner Losh <imp_at_FreeBSD.org>
Date: Fri, 12 Apr 2024 22:31:49 UTC
The branch main has been updated by imp:

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

commit e7ff917057eaf209c003660f02decb64ccb811da
Author:     Alexander Ziaee <concussious@runbox.com>
AuthorDate: 2024-04-12 22:28:12 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-04-12 22:29:25 +0000

    style.mdoc.5: maintenence
    
    - description: increase visibility by s/file/manual page/
    - examples: s/No Doing Something/Doing Something/
    - examples: remove depreciated .Li macro
    - examples: remove extra newline (one display block)
    - see also: link roff language reference for mandoc
    
    Reviewed by: imp
    Pull Request: https://github.com/freebsd/freebsd-src/pull/1130
---
 share/man/man5/style.mdoc.5 | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/share/man/man5/style.mdoc.5 b/share/man/man5/style.mdoc.5
index c1592bf8b87f..42dbc940074c 100644
--- a/share/man/man5/style.mdoc.5
+++ b/share/man/man5/style.mdoc.5
@@ -1,4 +1,4 @@
-.\"
+.\"-
 .\" SPDX-License-Identifier: BSD-2-Clause
 .\"
 .\" Copyright (c) 2018-2022 Mateusz Piotrowski <0mp@FreeBSD.org>
@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 29, 2022
+.Dd April 12, 2024
 .Dt STYLE.MDOC 5
 .Os
 .Sh NAME
@@ -32,7 +32,7 @@
 .Nd
 .Fx
 .Xr mdoc 7
-file style guide
+manual page style guide
 .Sh DESCRIPTION
 This file specifies the preferred style for manual pages in the
 .Fx
@@ -82,17 +82,17 @@ Format the
 section in the following way:
 .Bd -literal -offset indent
 \&.Bl -tag -width 0n
-\&.It Sy Example 1\\&: No Doing Something
+\&.It Sy Example 1\\&: Doing Something
 \&.Pp
 The following command does something.
 \&.Bd -literal -offset 2n
-\&.Li # Ic make -VLEGAL
+\&.Ic # make -VLEGAL
 \&.Ed
-\&.It Sy Example 2\\&: No Doing Something Different
+\&.It Sy Example 2\\&: Doing Something Different
 \&.Pp
 The following command does something different.
 \&.Bd -literal -offset 2n
-\&.Li # Ic bectl list
+\&.Ic # bectl list
 \&.Ed
 \&.Pp
 It is good to know this command.
@@ -100,24 +100,22 @@ It is good to know this command.
 .Ed
 .Pp
 which renders as:
-.Bd -filled -offset indent
 .Bl -tag -width 0n
-.It Sy Example 1\&: No Doing Something
+.It Sy Example 1\&: Doing Something
 .Pp
 The following command does something.
 .Bd -literal -offset 2n
-.Li # Ic make -VLEGAL
+.Ic # make -VLEGAL
 .Ed
-.It Sy Example 2\&: No Doing Something Different
+.It Sy Example 2\&: Doing Something Different
 .Pp
 The following command does something different.
 .Bd -literal -offset 2n
-.Li # Ic bectl list
+.Ic # bectl list
 .Ed
 .Pp
 It is good to know this command.
 .El
-.Ed
 .El
 .Ss Lists
 .Bl -dash -width ""
@@ -285,6 +283,7 @@ that would be rendered as:
 .Xr man 1 ,
 .Xr mandoc 1 ,
 .Xr mdoc 7 ,
+.Xr roff 7 ,
 .Xr style 9
 .Sh HISTORY
 This manual page first appeared in