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: freebsd/freebsd-src#1130

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,15 +24,15 @@
 .\" 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
 .Nm style.mdoc
 .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,42 +82,40 @@ 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.
 \&.El
 .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