From nobody Fri Apr 10 18:31:15 2026 X-Original-To: dev-commits-src-branches@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4fslkD2h5pz6YBkV for ; Fri, 10 Apr 2026 18:31:16 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4fslkD0QpCz42gB for ; Fri, 10 Apr 2026 18:31:16 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1775845876; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=xQ/JqCSD7BHY9dXEH1U9e1ukCNcltBvcI3INtKtug9c=; b=EZ137XawuxglNfT8MKp+yB3gED2A5bu7hYSv6uhImxoRlE9dNhxdf/2A8xHn3RVK7x3ObM OVgm1joHgcnzQixfeVRhbB21/muAG0pmqe7deIbmfRSh42GwiaVI1yt/x8kXv/S4mfPS1u aVoBn0A4IRFpu36wjX7wUpMEC2fHOWO3dKXrrEWr2M/hmbMpQUCeXV/5VlNmfztV1K/lKD jKfesS0kDxQ8RqwK+1k3DWCst/TS1kPFwQM4jiC0umOllHy5P2FBKlADsDBF3YHHrK0/03 BGHwGqM81sr1fFOjtCRf1ENX4OkFoztJPx0s0SO+GPdAEMM1hBxAqdVSQ9tHjA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1775845876; a=rsa-sha256; cv=none; b=cxR/HJVLYIimsrd3VOPrFR3uaxTDLFZ+lAZa0cmvkPOd110DC4ijdYW2mNGw3j3FJSaCZH tfTzwmqEmV2YnBf8VRWvHFbCA9L73Ieljs5Mnj1nePxlmx7LUmxDzoaNUIIkB4b7Hr+nBF ockPhRilEsG1OA2M7zgqRHOZJltO+ii8enll6E14eVKL40LFIcED2JGD2WjT44Mw+HqzGk Cr4jLmbtHKk0BtK56YSbC644QdrxGNz8XRrNq9TyB1ZBmsqzEO0Iiwl8SRbX5By7TMf1Qs /EqPv6dk5s6sM/TQwvUdsdkdXATDZV5dEnBOBXB3UBL5BwL5Owbn7skCOV7Iwg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1775845876; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=xQ/JqCSD7BHY9dXEH1U9e1ukCNcltBvcI3INtKtug9c=; b=act74Z0Eo96f+wLSkgKtxrGYUalcxnGLm8DwU5NccBIW5Zp3Ico/4T4vIhGPuIP7Ki72Qz ltn4w7LCi9GjOz7yCFdFT8BAlCjqfB8C/fUPcV02WmEJ/gxbOi2VP9Z+tMUSV0zu61qmVG y86NP2OIb5HUEf8dxhS54Z7nliv2frO2fpSWF+s5ebpi1t8jM5HJZcwghrl1Ezd54gN8HE 5k3aphMUKlya1B8k14Ijorgv7VOpu5FTre72uoGtBl9ViQlpuKKHkuDe8LOBeTrjF9V9Hy u/AcahxSy3lq51sXHUvvLyDW7Htp1BMKMwPtTflJXFgQuWHTTaiN9FiHNVWUPw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4fslkC717Xzw0v for ; Fri, 10 Apr 2026 18:31:15 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 38cbc by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Fri, 10 Apr 2026 18:31:15 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Alexander Ziaee Subject: git: 7f30d5cd3373 - stable/15 - style.mdoc: Remove synopsis formatting advice List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-branches@freebsd.org Sender: owner-dev-commits-src-branches@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ziaee X-Git-Repository: src X-Git-Refname: refs/heads/stable/15 X-Git-Reftype: branch X-Git-Commit: 7f30d5cd3373205bcc5411d671de9e4a5ae9941d Auto-Submitted: auto-generated Date: Fri, 10 Apr 2026 18:31:15 +0000 Message-Id: <69d941f3.38cbc.76d7e006@gitrepo.freebsd.org> The branch stable/15 has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=7f30d5cd3373205bcc5411d671de9e4a5ae9941d commit 7f30d5cd3373205bcc5411d671de9e4a5ae9941d Author: Alexander Ziaee AuthorDate: 2026-03-02 10:24:11 +0000 Commit: Alexander Ziaee CommitDate: 2026-04-10 18:28:50 +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 (cherry picked from commit 47326cb470278e891975354286481b5ba876929a) --- 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