Hi Jan, adding to what Jason already said...
Jan Stary wrote on Sat, Jun 21, 2014 at 11:43:57AM +0200: > The mandatory .Os macro of an mdoc(7) manpage makes the rendered > manpage have "OpenBSD Reference Manual" at the top center, That is not true. Try mandoc -Ios=FOOBAR /usr/share/man/man1/true.1 It still has "OpenBSD Reference Manual" at the top center. What is shown at the top center is the optional "volume" argument of the .Dt macro, see the mdoc(7) manual for details. Try sed 's/Dt TRUE 1/Dt TRUE 1 FOOBAR/' /usr/share/man/man1/true.1 | mandoc and sed 's/Dt TRUE 1/Dt TRUE LOCAL FOOBAR/' /usr/share/man/man1/true.1 | \ groff -mdoc -Tascii -P-c Groff only allows overriding the volume for non-standard sections, otherwise the default volume name of the standard section takes precedence. Mandoc always uses a volume name provided in .Dt and only falls back to the section's default volume name when .Dt doesn't provide one. > and "OpenBSD X.Y" at the bottom. That is true. > As the mdoc(7) manual says, > > Left unspecified, it defaults to the local > operating system version. This is the suggested form. Yes. That is somewhat unfortunate but cannot easily be improved. On the one hand, if you find old, dusty manuals somewhere, you would like to know where they came from, so having an explicit "OpenBSD 5.5" inside each individual manual would be nice: Even formatting them on Linux, you could still see, "this is an OpenBSD 5.5 manual". However, that would require one commit to each individual manual page for each release, which would be an unreasonable burden. > Viewing the same page on Linux with mandoc, > it renders "General Commands Manual" In order to be closer (even though not identical) to what groff does, we chose that as our default for mandoc-portable, see http://mdocml.bsd.lv/cgi-bin/cvsweb/msec.in?annotate=1.6&cvsroot=mdocml The OpenBSD msec.in is different, see /usr/src/usr.bin/mandoc/msec.in > and "Linux 3.2.0-4-amd64". > > Now, viewing the same manpage on Linux with groff -mdoc, > it renders "BSD General Commands Manual" As Jason already noted, that comes from tmac/doc-common in the groff distribution. In the -current groff git, we have: .ds doc-volume-operating-system BSD .ds doc-volume-ds-1 General Commands Manual .ds doc-volume-ds-2 System Calls Manual .ds doc-volume-ds-3 Library Functions Manual .ds doc-volume-ds-4 Kernel Interfaces Manual .ds doc-volume-ds-5 File Formats Manual .ds doc-volume-ds-6 Games Manual .ds doc-volume-ds-7 Miscellaneous Information Manual .ds doc-volume-ds-8 System Manager's Manual .ds doc-volume-ds-9 Kernel Developer's Manual and then, inside the definition of .Dt, simplifying the code a bit, .ds doc-volume "\*[doc-volume-operating-system] .as doc-volume " \*[doc-volume-ds-\$2] So you effectively end up with \*[doc-volume] equal to "BSD General Commands Manual". > at the top center and "BSD" at the bottom. That "BSD" is not coming form the same place as the other "BSD". Still in -current groff git, the file tmac/doc-common has: .ds doc-default-operating-system BSD and then inside the definition of the .Os macro: .ie "\$1"" \ .ds doc-operating-system "\*[doc-default-operating-system] and then the internal .doc-footer macro later uses \*[doc-operating-system] for the page footer. So, the packager for your Linux distribution should maybe customize \*[doc-volume-operating-system] and \*[doc-default-operating-system] via the mdoc.local mechanism but didn't do so. Oh well, i'm just relizing the names of these variables in groff -current differ from the latest groff release, 1.22.2, where they don't have the doc-* prefix yet. In the OpenBSD groff-1.22.2 port, we are patching doc-common like this: .ds volume-operating-system OpenBSD .ds default-operating-system OpenBSD\~ports The former is for the page header, the latter for the page footer, and the latter can be overridden by .Os. Yours, Ingo
