Differential D53340

style.mdoc.5: Document use of config, rc.conf, loader.conf, and sysctl.conf in SYNOPSIS
Needs ReviewPublic
Actions

Authored by 0mp on Oct 24 2025, 7:45 PM.

Details

Reviewers

ziaee

Summary

Suggested by: Alexander Ziaee

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Skipped

Unit

Tests Skipped

Build Status

Buildable 68102
Build 64985: arc lint + arc unit

Event Timeline

0mp created this revision.Oct 24 2025, 7:45 PM

Herald added subscribers: ziaee, imp. · View Herald TranscriptOct 24 2025, 7:45 PM

0mp requested review of this revision.Oct 24 2025, 7:45 PM

Harbormaster completed remote builds in B68102: Diff 165000.Oct 24 2025, 7:45 PM

0mp added a reviewer: ziaee.Oct 24 2025, 7:53 PM

Hey, thanks for doing this. Initial bikeshed:

share/man/man5/style.mdoc.5
230	This is very broad. According to mdoc(7), it's very specifically: "Documents the utility invocation syntax, function call syntax, or device configuration." So, OtherBSDs interpret "device configuration" to mean exclusively the config(8) declarations, but in FreeBSD for drivers only (afaik), we've seemingly always interpreted this to also include the files that configure devices at runtime.
236

0mp added inline comments.Oct 24 2025, 11:14 PM

share/man/man5/style.mdoc.5
230	Hey! I've read mdoc's take on this as well. I just thought that it would be nice to document what we already do. I couldn't think of a better phrase for now than "all kinds of relevant information". Perhaps we could just list what's allowed, which would be: config(8) loader.conf(5) sysctl.conf(5) rc.conf(5) command-line syntax function syntax anything else?

0mp retitled this revision from style.mdoc.5: Document use of rc.conf, loader.conf, and sysctl.conf in SYNOPSIS to style.mdoc.5: Document use of config, rc.conf, loader.conf, and sysctl.conf in SYNOPSIS.Thu, Nov 13, 5:36 PM

Improve the descirption. Point the reader to mdoc(5) for the defaults and additionally allow very specific files.
Use X instead of %d.

Harbormaster completed remote builds in B68612: Diff 166380.Thu, Nov 13, 5:37 PM

0mp marked 2 inline comments as done.Thu, Nov 13, 5:38 PM

0mp added inline comments.

share/man/man5/style.mdoc.5
230	Addressed.
253	If we use Cd here, aren't we hiding that from apropos Va?

typo

Harbormaster completed remote builds in B68613: Diff 166381.Thu, Nov 13, 5:39 PM

ziaee added inline comments.Thu, Nov 13, 5:42 PM

share/man/man5/style.mdoc.5
231	5 would make sense as a file format, but its a 7 as a language specifier.
232	I wish we could say something that sounds less exclusive. I feel like this is going to be used against us like "well style.mdoc says a b or c".
242	This also doesn't need to be quoted, so maybe we shouldn't tell them to quote it so we don't promote cargo culting, especially since it's a whole line argument macro

ziaee added inline comments.Thu, Nov 13, 5:45 PM

share/man/man5/style.mdoc.5
253	We would be if that was the only place we used it, but the synopsis isnt the only place its put in the manual. It get enumerated in the synopsis but still has to be explained usually in SYSCTLS or SYSCTL VARIABLES (the latter is more common but also a bit redundant). But, this is what we've been doing. If we use something other than Cd, you'll have to abuse the formatting with low level roff escapes too, which we do not do and I do not want to recommend.

ziaee added inline comments.Fri, Nov 14, 3:21 AM

share/man/man5/style.mdoc.5
237	We also use device hints, see ppc(4)

Revision Contents
Changeset List

Path

Size

share/

man/

man5/

style.mdoc.5

23 lines

Diff 165000

View Options

share/man/man5/style.mdoc.5

style.mdoc.5: Document use of config, rc.conf, loader.conf, and sysctl.conf in SYNOPSISNeeds ReviewPublicActions