man4: Use arch specifier of Dt consistently

[ziaee]

Summary

Use the mdoc(7) arch specifier in the document title for (afaik) all remaining manuals reflecting drivers which are only for one architecture. Most are in architecture specific folders, but amd64 only manuals are denoted in man4/Makefile.

These display at the top of the manual [0] without taking up extra lines and are useful in any case, however I hope to use these in the Hardware Release Notes, where architecture specificity is difficult to maintain.

Also tagging riscv developers because we do not have a /man4/man4.riscv/ and we should. All manuals are built for all architectures, but sorting them makes it easier to understand.

[0] Example: https://man-dev.freebsd.org/boot

MFC after: 3 days (any reason why not?)

Test Plan

+ Verify syntax accuracy in mdoc reference manual
+ Verify driver architecture specificity by presence in man4/man4.$arch/ or syntax in man4/Makefile
+ Test patch with makewhatis, apropos and man
+ Reflect on naming conventions and precedence

[ziaee]

Add amd64 based on it's makefile, even though it isn't in a subdir.

[mhorne]

I am happy with the idea of making this consistent across man/man4.$arch.

Practically, how does this information get used? It is not known to me how to query or interact with it via man(1).

Also a word of caution: sys/modules/Makefile, and the whole business of "what driver is built on what platform", is a quagmire of messy exceptions and disharmony. There may be some small easy improvements to be made as it relates to documentation, but finding or applying any kind of systematic organization should not be expected.

Also tagging riscv developers because we do not have a man4.riscv and we should.

This is for me.

In D51264#1170511, @ziaee wrote:

Add amd64 based on it's makefile, even though it isn't in a subdir.

IMO the initial scope was an easy accept, but now you have confused two changes in one.

[ziaee]

In D51264#1170530, @mhorne wrote:

I am happy with the idea of making this consistent across man/man4.$arch.

Practically, how does this information get used? It is not known to me how to query or interact with it via man(1).

If you open the manual, you will see it at the top, like this:
FreeBSD Kernel Interfaces Manual (aarch64)
There may be other ways to interact with it.

Also a word of caution: sys/modules/Makefile, and the whole business of "what driver is built on what platform", is a quagmire of messy exceptions and disharmony. There may be some small easy improvements to be made as it relates to documentation, but finding or applying any kind of systematic organization should not be expected.

Also tagging riscv developers because we do not have a man4.riscv and we should.

This is for me.

In D51264#1170511, @ziaee wrote:

Add amd64 based on it's makefile, even though it isn't in a subdir.

IMO the initial scope was an easy accept, but now you have confused two changes in one.

So, like riscv, these manuals are for drivers that are exclusively for amd64, you can see that in the Makefile, therefore, I think these are not logically separate changes.

[ziaee]

Dt takes one arch argument, but we can use multiple with a comma, the linter doesn't complain and apropos seems unaffected.

If this is fine, we can fix the entire issue of the HW Relnotes architecture specificity by just drawing in the third space separated argument of Dt. Done.

{F123250447}

[0mp]

LGTM.

The man.<arch> manuals are easy.

How did you identify the amd64 ones in man4?

[ziaee]

Thanks!

How did you identify the amd64 ones in man4?

From reading man4/Makefile

[0mp]

In D51264#1171122, @ziaee wrote:

Thanks!

How did you identify the amd64 ones in man4?

From reading man4/Makefile

Nice! I'd mention that in the commit message to make it easier for others to verify that later.

[imp]

So how do you deal with 2 arch?

[ziaee]

In D51264#1171299, @imp wrote:

So how do you deal with 2 arch?

(Not included in this commit but) I tested it and:

.Dt AOUT 4 i386,amd64

Works with mandoc.

[emaste]

In D51264#1171122, @ziaee wrote:

Thanks!

How did you identify the amd64 ones in man4?

From reading man4/Makefile

IMO we should also add a comment there reminding people to update the man page itself if enabling on another architecture - e.g. if the nvdimm kernel module gets added to aarch64 we need to make sure nvdimm.4 is updated.

[ziaee]

IMO we should also add a comment there reminding people to update the man page itself if enabling on another architecture - e.g. if the nvdimm kernel module gets added to aarch64 we need to make sure nvdimm.4 is updated.

Thanks @emaste, that sounds great!