From nobody Thu Aug 6 22:31:41 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 4hGMTB1RZKz6nLc8 for ; Thu, 06 Aug 2026 22:31:42 +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 "YR1" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4hGMT930MLz4PWp for ; Thu, 06 Aug 2026 22:31:41 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1786055501; 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=hr2kAaa/UKZokWphtNzHwF8j3//tEhAWarmD/X6vMyU=; b=pulMeEKvrb7Q8EBQgWT5MmFRip5lxbQfuScQmsJxYUL13ySwjU+B0Cq9Sv+7gMSRYuaWzT y+goL2a6jK5ElMLUZjjBpVPymv/OZUk63eTxblBNIvDMI/M4QbLfTcg72xGIM6xFge00Zo w1JFRYLsCHHZKs1GCnAX6BNgAbBCo1p54cMw9PPzyv8CnKpIBUR6Qe8ZcxTYaqBy1zJwMI ihcapNBCrXy0A+vVBKybDWMSu6GxTBT9Tfoa/CUoKYl4ef+IXGdPxeXbHPvi2KUq8+e5b0 QCtIJASh6XPMG6aB4xO1xV1tp0FBPzSEk8k0vzUbkQs9Gt0smxKeJRW2lcOgDg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1786055501; a=rsa-sha256; cv=none; b=FC1a9ReOJazAm20HbgGucV+iD5IWjk4gGSgYRfzVayllaPankn8sPl+E9Juk2gtmytB9F9 PSOxEk0FiSS0JGnFZPNslkZ633UTD1BYBGPjiLGskfJ0wcz1AdD7OK5ga199Z7s6Wvidwn gB2Cw614fFtjsLvZKXKgbvNHz8hYe3PvKq9SU7dAP5HaQMa1WMvogtkEYoTMCeCQbQ/gha QTF8QwLfVgwnvFxL73Y/VgGLS+B/56mOcVAy2lF7ZTYE3y/VKoxPlK9hjruoIhFBrqr+Un DTC+2jDcrZk19XxV/sS/GrUKsvzwxLHzh0s0oTj4B5yyN31s0VlNoykR+XJRSg== 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=1786055501; 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=hr2kAaa/UKZokWphtNzHwF8j3//tEhAWarmD/X6vMyU=; b=oRYkNO6ZxPCt5fGK8vLd/cFMe23VAZvit609OCTxcJlKvk0kb5ihqHbU0V2DeanQgfjP62 pMTHlc+B3fAhJBvriegafUWOKu2q7N4hGSHr60uL55dM2R/HxjfpPH5Hq5Ul3/PNPlu8MY xlrWblMzgD5JTMgMNqT/48OuYFs6Jf/rjeZU3CXozf1FpVajtzJEm9+HC7EV044U+gythX +nOi03gs6u7RBuR+k3VLJlR4mMzxEFh65+jO0EaC9OIdiYbsX2HGi6YGuXoGRLc46G17W0 fFdoq8lbHLClX+sj7ifd2Z/cZh+wSteJYmqK6Kkc6NcZLXOXlzYaMQVFS6IU2Q== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4hGMT920tjzgsm for ; Thu, 06 Aug 2026 22:31:41 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 1de71 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Thu, 06 Aug 2026 22:31:41 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Alexander Ziaee Subject: git: e5c5e7db7ebd - stable/14 - 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 List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list 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/14 X-Git-Reftype: branch X-Git-Commit: e5c5e7db7ebdf67355f26b561e1e2902d5e6cc5e Auto-Submitted: auto-generated Date: Thu, 06 Aug 2026 22:31:41 +0000 Message-Id: <6a750b4d.1de71.701a9f4a@gitrepo.freebsd.org> The branch stable/14 has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=e5c5e7db7ebdf67355f26b561e1e2902d5e6cc5e commit e5c5e7db7ebdf67355f26b561e1e2902d5e6cc5e Author: Alexander Ziaee AuthorDate: 2026-03-02 10:24:11 +0000 Commit: Alexander Ziaee CommitDate: 2026-08-06 22:23:42 +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