In general the man pages do not care what OS and manual they are shipped
with, so they don't get to choose the names of them. We were tempted to
do so, as we had inconsistently chosen OS names for the mandoc and
man-db/groff implementations. Since this has been rectified since, we
can just drop this boilerplate from the man pages.
nixos/manual/manpages: add description on previewing manpage files
I was a bit lost with the new manpage format and it took me some time to
find the corresponding pull request by @pennae with a very helpful
comment of @alyssais that mentioned this:
https://github.com/NixOS/nixpkgs/pull/213256#issuecomment-1407713215
As @pennae noted, the file path is only a fallback if it cannot be resolved in the man database
Co-authored-by: pennae <82953136+pennae@users.noreply.github.com>
since we want to move away from docbook and having docbook manpages
around is going to block further progress we have to translate the
current nixos manpages from docbook it *something* else. mdoc seems the
most appropriate choice since markdown can't represent all the things
manpages can differentiate with even more extensions. if we ever need
html manpages we can render them using troff, like many of the online
manpage viewers, or rewrite them again. since we haven't had html
manpages for any of these in many years that seems unlikely to happen.
unlike most of the recent markdown conversions this comes with a lot of
minor rendering changes, mostly in spacing. docbook-xslt creates manual
pages in a very different dialect than mdoc (which is used here).
