ocs_fc.4: Cleanup

[ziaee]

Summary

+ more consistent document description
+ enumerate available options in synopsis
+ tag spdx
+ tweak list rendering
+ cleanup HARDWARE
+ reflow excessively long lines silencing linter warnings
+ fix link macros

MFC after: 3 days

Note to michaelo: This is how we fix the hardware notes. They are generated, so we actually don't want to edit them directly. While I'm here, might as well clean up everything else.

[michaelo]

share/man/man4/ocs_fc.4

115

Since you are already touching these: GEN is not an acronym, it is an abbreviation. It should be "Gen"

[ziaee]

thanks michaelo! also add pcie, that's a helpful detail

[michaelo]

When comparing with other drivers they say how to compile into the kernel. Is this not relevant?

[ziaee]

In D56753#1300071, @michaelo wrote:

When comparing with other drivers they say how to compile into the kernel. Is this not relevant?

It's not just irrelevant, it's completely wrong and undermines the entire structure of the manual pages. Think about it. In every section, SYNOPSIS does not contain prose. It enumerates all available options, which should be described in DESCRIPTION. Drivers should also do that. We have almost 200 manuals in the tree following the format I use here, and I intend to standardize upon this. I proposed this on arch@ in January with no objections -- https://marc.info/?l=freebsd-arch&m=176782215606871

I gave a talk on this at BSDCan last year, which has some relevant comments from the mandoc author -- https://www.youtube.com/watch?v=RthIOXpwwsM

[michaelo]

In D56753#1300105, @ziaee wrote:

In D56753#1300071, @michaelo wrote:

When comparing with other drivers they say how to compile into the kernel. Is this not relevant?

It's not just irrelevant, it's completely wrong and undermines the entire structure of the manual pages. Think about it. In every section, SYNOPSIS does not contain prose. It enumerates all available options, which should be described in DESCRIPTION. Drivers should also do that. We have almost 200 manuals in the tree following the format I use here, and I intend to standardize upon this. I proposed this on arch@ in January with no objections -- https://marc.info/?l=freebsd-arch&m=176782215606871

Ah, yes -- there was no reaction to your announcement. Strange.

I gave a talk on this at BSDCan last year, which has some relevant comments from the mandoc author -- https://www.youtube.com/watch?v=RthIOXpwwsM

Yes, I remember this one, it was very informative. I wonder whether the Foundation could provice credits for AI agents to do this automatically and then review manually.

[ziaee]

In D56753#1300625, @michaelo wrote:

In D56753#1300105, @ziaee wrote:

In D56753#1300071, @michaelo wrote:

When comparing with other drivers they say how to compile into the kernel. Is this not relevant?

It's not just irrelevant, it's completely wrong and undermines the entire structure of the manual pages. Think about it. In every section, SYNOPSIS does not contain prose. It enumerates all available options, which should be described in DESCRIPTION. Drivers should also do that. We have almost 200 manuals in the tree following the format I use here, and I intend to standardize upon this. I proposed this on arch@ in January with no objections -- https://marc.info/?l=freebsd-arch&m=176782215606871

Ah, yes -- there was no reaction to your announcement. Strange.

Usually people only reply to arch@ if they want to ask clarifying questions or point out deficiencies. Since I've already been working on this for a year, many people have already helped me explore all the corner cases.

I gave a talk on this at BSDCan last year, which has some relevant comments from the mandoc author -- https://www.youtube.com/watch?v=RthIOXpwwsM

Yes, I remember this one, it was very informative. I wonder whether the Foundation could provice credits for AI agents to do this automatically and then review manually.

One reason they don't is that I'm by far the most active doc reviewer and I have said that I am not interested and do not consent to reviewing AI generated output.

When I'm reviewing something someone wrote, we're working together to build something. The feedback I spend my brief existence providing is teaching others corner cases and making their understanding better. It's not just about the thing getting built, because actually the volunteer environment is the most important thing that will also keep attracting people to the project. It doesn't matter if I take 5 more years to update all of the manuals, 200 are already done and there are 500 left. This problem is older than I am, it doesn't need to be all solved at once.