The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=47326cb470278e891975354286481b5ba876929a
commit 47326cb470278e891975354286481b5ba876929a Author: Alexander Ziaee <[email protected]> AuthorDate: 2026-03-02 10:24:11 +0000 Commit: Alexander Ziaee <[email protected]> CommitDate: 2026-03-02 11:10:21 +0000 style.mdoc: Remove synopsis formatting advice Remove incorrect advice. The first rule was no spaces padding pipes when showing alternates. Almost universally we not do this, and third party manuals do not either. The second was using Cm to mark up symbols. This advice is in conflict with mdoc(7), and the extended documentation on mdoc linked below, which is also linked at the bottom of mdoc(7). Conflicting information in our docs is a natural result of documentation proliferation. The most important thing we can do to reduce technical debt in the documentation is reduce the amount of doc overlap. Excessive technical debt and conflicting rules is a barrier to new contributors. This type of work requires thorough expertise, is not glamorous at all, and to add insult to injury, is socially unsafe. To get new contributors to the docs project, we must deduplicate documentation. We have the mdoc manual, examples/mdoc, style.mdoc, and the fdp chapter on manual pages. With this many, they will inevitably come to contain conflicting information, and people will learn not to read them or work on them. MFC after: 3 days Ref: https://mandoc.bsd.lv/mdoc/style/commands.html Differential Revision: https://reviews.freebsd.org/D55298 --- share/man/man5/style.mdoc.5 | 67 --------------------------------------------- 1 file changed, 67 deletions(-) diff --git a/share/man/man5/style.mdoc.5 b/share/man/man5/style.mdoc.5 index e0c41915ecb1..84eb281dc76a 100644 --- a/share/man/man5/style.mdoc.5 +++ b/share/man/man5/style.mdoc.5 @@ -152,73 +152,6 @@ Install the missing packages. \&.El .Ed .El -.Ss Synopsis Formatting -.Bl -dash -width "" -.It -Do not put whitespace between alternative parameters separated with a pipe -.Pq Dq | , -e.g.: -.Bd -literal -offset indent -\&.Cm compression Cm on Ns | Ns Cm off -\&.Cm install Fl -all Ns | Ns Ar portname Ar ... -.Ed -.Pp -which in the SYNOPSIS section is rendered as: -.Bd -unfilled -offset indent -.Cm compression Cm on Ns | Ns Cm off -.Cm install Fl -all Ns | Ns Ar portname Ar ... -.Ed -.It -Use -.Sy \&Cm -to stylize characters that are command modifiers -.Po e.g., -.Dq \&, , -.Dq @ -or -.Dq "=" -.Pc . -For example: -.Bd -literal -offset indent -\&.Sm off -\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where -\&.Sm on -.Ed -.Pp -which renders as: -.Bd -filled -offset indent -.Sm off -.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where -.Sm on -.Ed -.Pp -instead of: -.Bd -literal -offset indent -\&.Sm off -\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where -\&.Sm on -.Ed -.Pp -which would render as: -.Bd -filled -offset indent -.Sm off -.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where -.Sm on -.Ed -.Pp -It is important to realize that in the correct example, -.Dq \&, , -.Dq @ -and -.Dq = -are stylized with -.Sy \&Cm . -At the same time, the square brackets -.Pq Dq "[]" -are not stylized as they do not belong to the syntax of the -.Fl -meet -flag. -.El .Ss Quoting .Bl -dash -width "" .It
