fhopen.2: Document the O_NAMEDATTR flag

[rmacklem]

Summary

Commit 2ec2ba7e232d added support for the O_NAMEDATTR flag to
the fhopen(2) syscall for main.

This patch updates the man page for this flag.

Another man page that explains named attributes will
be introduced in a future commit.

[ziaee]

lib/libsys/fhopen.2

86

Should we instead mention this in the errors section for predictability and conciseness?

137

These seem roughly alphabetized, should we instead put these after line 127?

[rmacklem]

Removed the sentence w.r.t. the specific error, since
it is covered in the ERROR section. Also, moved the
ENOATTR entries so that they are in alphabetical order,
as suggested by ziaee@.

[ziaee]

I do really love putting the commit that the work depends on in "Fixes: " instead of the introductory sentence of the commit message. It makes me feel like the the sentence is clean and just explaining for me, and very predictable to track the tree of events related to the commit.

[rmacklem]

In D49718#1134202, @ziaee wrote:

I do really love putting the commit that the work depends on in "Fixes: " instead of the introductory sentence of the commit message. It makes me feel like the the sentence is clean and just explaining for me, and very predictable to track the tree of events related to the commit.

I just tried this. The problem is that the line ends up about 100 characters long,
using what the Committer's Guide recommends. Is that ok?
(I've never done this before. I will also note that I always do man pages
separately, so "Fixes:" might not be accurate.)

[ziaee]

The problem is that the line ends up about 100 characters long, using what the Committer's Guide recommends. Is that ok?

That's a great question. I truncate them, using between 8 and 12 characters of commit hash and the most useful cross section of the commit message titles to keep it under 72 characters, like this:

https://reviews.freebsd.org/D49671

[emaste]

Standard format for Fixes is Fixes: <short (12 char) hash> ("<Original commit first line in parens and quotes>") If the line ends up long that's fine.

[rmacklem]

Oops. I didn't see emaste@'s comment until after
doing the commit.

I do have a question for Ed though. Is the case where
a man page is documenting a change in another commit
a reasonable usable of "Fixes:"?

[emaste]

There's tooling that can find cherry-picks (MFCs) in a branch that have a corresponding Fixes: commit in main that hasn't been cherry-picked, so Fixes: for a commit that adds a man page entry is sensible. It basically signals "If you have the commit identified by the Fixes: tag, you should take this one too.