From nobody Mon Mar 2 11:15:37 2026 X-Original-To: dev-commits-src-all@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 4fPbvY3T9Wz6TGL0 for ; Mon, 02 Mar 2026 11:15:37 +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 4fPbvY2fyzz3GMw for ; Mon, 02 Mar 2026 11:15:37 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1772450137; 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=cU5aUEfeimkhIK+oA4oJqg7VddlcNGpjY/3jIUSHrlY=; b=pYZ6UVBad/PpQJq3F17ZzK3F7kNMwRwTLokFzSKQPiVMIDRhWSHb1XUXkE7jheOTPEx9Bc 8WV0IYWgLGsLKWHv3HZKLSaMALxeLnSkaqTiHNsa/P7L8Ex4IR1k8Yn8l46qu5q9NpNuaL WCIYJjkAH3d4ERc4e53igcKjFySQ9xfFUmlPtI/LGnpjC7dVEfho9mc5JemoeP8EI/t+vE pjOiL8zeqW1WPV70ZHmTjVYhAtIjn9khY/cutR9ML/402C5RmZGUWgoamjVkN3jxU5XC7l j3NUOMdW+tHle6iut4dsfnh74g5Bi+8lteyq6Kd0d6TvZSwrHuyfQGPUs2mYmg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1772450137; a=rsa-sha256; cv=none; b=c7Fa8foQ9ayN+T0YuBOgY2RwULfPQ0jbyD4vYE80hjZqDHGOmAy8FyUIQ6IBhwieBNQsvT Ud5aPAJoURSP2dLHTUhGa/W7EA/+bSEYGtMfI87WApxVZ/JHBeuq0cJidYUx0I2oTeUp+9 lPG2FKxEOkXbQHEL58fyOab99H0m6xQ8dGcZh/vMLSOHzx1baWLBf3udB/UKOTzfoyQ/Up bNEZ2pGZ01/KF5N35Uh3KWhP5qQ0dpUNPDyoFWnfz1vdjZ274ArMc6GHsY5FVgwGDOHJyz aszL71JUzCdHTUuZp4lVg4OtLj6S+EPAJgLGbl5kagRLvQZl8dGFqDtFv+JvfQ== 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=1772450137; 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=cU5aUEfeimkhIK+oA4oJqg7VddlcNGpjY/3jIUSHrlY=; b=SglDzhkSWNnVglAp9SuC1hXsFlNjhFOsmEwJ2WwAenIgKojwNq1BmdRltoZ/GA99QEG5pS VzLicNpBCzy9rBnzFYb+q26U/+Sy2PkugkGCrhwSQYw/NG7uiFEZYqgD6VnmfK3BNd7gHl s0CPXuUj9Af/gCzyiYY2QMv7XmQ6/EtbG1o2yFcBL9Rg1del58S7FGyIh1e7XQo34kzsIY 41Ac2HO2eKk5ums3BWZjPvpVMOW3tzQJOWy5R3ChRtQ5FP9nL2w5DMJWt9CWpIn4u5kO8f zQTxEtzIP6WgcmQc8tOpB8OxvdSm5MGFIWURcL9EteThC0VeSCM60hAud2A14w== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4fPbvY1xZ9zYqC for ; Mon, 02 Mar 2026 11:15:37 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 368da by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Mon, 02 Mar 2026 11:15:37 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Alexander Ziaee Subject: git: 47326cb47027 - main - style.mdoc: Remove synopsis formatting advice List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@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/main X-Git-Reftype: branch X-Git-Commit: 47326cb470278e891975354286481b5ba876929a Auto-Submitted: auto-generated Date: Mon, 02 Mar 2026 11:15:37 +0000 Message-Id: <69a57159.368da.4c403145@gitrepo.freebsd.org> The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=47326cb470278e891975354286481b5ba876929a commit 47326cb470278e891975354286481b5ba876929a Author: Alexander Ziaee AuthorDate: 2026-03-02 10:24:11 +0000 Commit: Alexander Ziaee 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