ether_gen_addr(9): fix `OUI_FREEBSD_BASE` description

[ngie]

Summary

There's no such thing as a "FreeBSD Foundation Base OUI" - correct this
description by using .Fx and removing "Foundation" from the description.

MFC after: 1 week

[kevans]

share/man/man9/ether_gen_addr.9

71

This was supposed to serve as a pointer to find more details- the Foundation is infact the arbiter of and entity behind the OUI that we use for this

[ngie]

share/man/man9/ether_gen_addr.9

71

This seems like a better spot to document that requirement. Adding this policy detail to a random manpage doesn't help since all manpages would need to do similar to ensure parity:

% git diff sys/net/ieee_oui.h
diff --git a/sys/net/ieee_oui.h b/sys/net/ieee_oui.h
index b5dd9fccefe1..b8cba10d1135 100644
--- a/sys/net/ieee_oui.h
+++ b/sys/net/ieee_oui.h
@@ -30,7 +30,11 @@
  *
  */
 
-/* Organizationally Unique Identifier assigned by IEEE 14 Nov 2013 */
+/**
+ * Organizationally Unique Identifier assigned by IEEE 14 Nov 2013.
+ *
+ * This OUI is managed by the FreeBSD Foundation.
+ */
 #define OUI_FREEBSD_BASE 0x589cfc000000
 #define OUI_FREEBSD(nic) (OUI_FREEBSD_BASE | (nic))

I would be game for referring to OUI_FREEBSD_BASE in this manpage instead of the explicit OUI prefix.

[kevans]

share/man/man9/ether_gen_addr.9

71

No objection to that, but this isn't a random manpage- it's the only function that hands MAC addresses out of this OUI, so I'm not sure what you mean by needing to add it to all. It seems incredibly relevant when trying to decide what this KPI is going to generate for you, since we've had a mix of LAA generation things in the past.

[ngie]

share/man/man9/ether_gen_addr.9

71

No objection to that, but this isn't a random manpage- it's the only function that hands MAC addresses out of this OUI, so I'm not sure what you mean by needing to add it to all. It seems incredibly relevant when trying to decide what this KPI is going to generate for you, since we've had a mix of LAA generation things in the past.

I see.

Let me step back and give you an idea of how this change "came about".

Running make manlint identities potential issues with mandoc text in manpages. One class of issues that's frequently cited is replacing .Fx with FreeBSD, .Nx with NetBSD, etc. "FreeBSD Foundation" is a complaint for this target because FreeBSD is into the organization string.

My first reaction when I did this was to make the string more generic by removing "FreeBSD" from the manpage entirely, leveraging .Fx alone, since the original description didn't seem accurate to me with my earlier context and it didn't seem to match the constant in the consumed code.

My gut feeling about this is (really) given that this is a specific entity name ("FreeBSD Foundation") that should remain as-is, the issue should be ignored. Moreover, the ability to ignore the issue should be handled within the mandoc linter logic and this should be added to the allowlist.

Suggested next steps: I can make comment edit to just the header, drop the manpage change, and file another issue so that strings like "FreeBSD Foundation" no longer get flagged by make manlint. Does that sound good?

[kevans]

share/man/man9/ether_gen_addr.9

71

I think that sounds perfect, thank you!