mdoc: Standardize SYNOPISIS section for drivers

[ziaee]

Summary

Standardize driver manuals on the style used for 12 years in vt(4).
This brings SYNOPSIS across all FreeBSD manual sections into harmony
of meaning where where SYNOPSIS lists available options, and does not
contain prose. Adjust mdoc(7) to reflect the established convention.

https://marc.info/?l=freebsd-arch&m=176782215606871

[ziaee]

make mdoc(7) a bit clearer

[jlduran]

contrib/mandoc/mdoc.7

1187

FreeBSD -> .Fx

[ziaee]

+ demonstrate some pages use optional values in synopsis
+ use the freebsd macro instead of typing freebsd

[ziaee]

update to incorporate device.hints

[ziaee]

tweak

[imp]

share/examples/mdoc/example.4

24–30

why list this twice?

[ziaee]

thanks for taking a look. does this make it more clear?

[ziaee]

fix markup in mdoc.7, sections are referred to with .Em in this manual.

[jhb]

contrib/mandoc/mdoc.7

1187

Hmmm, I guess was only thinking of kernel config lines.

1189

Loader tunables and sysctl nodes aren't really kernel configuration though, I would perhaps be more explicit and say something like:

This denotes strings accepted by
.Xr config 8 ,
device hints,
loader tunables,
and sysctl nodes.

1196–1197

If we are going to have a diff relative to upstream, let's make this be specific to FreeBSD. Also, I would perhaps leave off the kern.vty example here since it is marked up differently in example.4 with a header.

share/examples/mdoc/example.4

18–22

I kind of wish we didn't list files here because device hints and loader tunables can be added to the kernel config via envier, both can also be read and written post-boot via kenv(1), and sysctl nodes can be read and/or written at runtime via sysctl(8) in addition to sysctl.conf. I'd rather document the details of how one uses hints, loader tunables, and sysctls in intro(4) and instead have these headers just be things like:

.Pp
.Sy Device Hints:

The other headings could be "Loader Tunables", "Writable Loader Tunables", and ".Xr sysctl 8 Nodes"

32

I would not bother with kld_list. I think the language in intro(4) the talks about kernel modules should cover kld_list as well as foo_load in loader.conf in which case there is no need to document those in each foo(4) manual page.

45

BTW, alternatively what I've seen in other man pages like cxgbe(4) is using a dedicated .Sh LOADER TUNABLES with a block list to describe loader tunables. I kind of prefer that over adding a lot of clutter to the SYNOPSIS. Some drivers may only have a a few tunables and sysctl nodes, but some drivers have many. Device hints tend to be small (and fairly rare) and I think having them in the SYNOPSIS is probably fine. If you only had hints in the SYNOPSIS then I would suggest something like:

option FOO
device bar
.Pp
hint.bar.0.at=<mumble>
hint.bar.0.port=<mumble>

as a fairly concise format for the SYNOPSIS. Again, how one uses hints would be described in intro(4), not every driver manpage.

[ziaee]

Thanks for looking!

contrib/mandoc/mdoc.7

1189

Sounds good, thanks.

1196–1197

The page as a whole describes what's going on in different environments. It's important to maintain this because it's a language reference.

We are already keeping quite a diff to upstream, and our colleagues want me to widen it even further, such as refusing a change mandoc and groff made to change LIBRARY and the Lb macro -- https://reviews.freebsd.org/D56153

share/examples/mdoc/example.4

18–22

I agree with you and am willing to take this in that direction, but I'm extremely concerned about consensus building. That is a much larger change and to my knowledge we are not currently doing that.

Already we can not agree on what to do this, so everyone is doing whatever they want including breaking common doc best practices. I've been trying to get a handle on this for two years. Doceng started 6 or 7 years ago and then gave up.

I'm trying to standardize on the best thing we already have in the tree across hundreds of manuals for a long time, and I did send a mail to arch@ in January proposing this.

32

Ok, I am happy to do that, thanks.

45

LOADER TUNABLES is a "standard" FreeBSD section in our manuals. In all manual sections, SYNOPSIS lists all the available ways to use it, but the options still need to be explained later in the manual.

[ziaee]

share/examples/mdoc/example.4

18–22

Actually, thinking about this further, the .Sy renders the same as .Cd on terminal. Different on print, but I think that could be confusing.

[ziaee]

Implement the most obviously actionable suggestions from @jhb
+ specify .Cd config types in mdoc.7
+ remove rc.conf configuration from example.4