Re: Specify man section name at runtime

[Ingo Schwarze <schwarze@usta.de>]

Hi Cameron,

Cameron Katri wrote on Sun, Oct 03, 2021 at 07:16:30PM -0400:

> Well this is a very niche use case, but on FreeBSD they patch msec.in
> to say "FreeBSD General Commands Manual" etc.

I think that patching is ill-advised.  In manual pages, the operating
system name is supposed to be printed in the footer line (lower left
corner), not in the header line.   One consequence of the FreeBSD
patching is that if you format manual pages of another operating system
on FreeBSD, the header line will always include the misleading string
"FreeBSD" anyway, and as you observed, there is no way to tell mandoc
to leave it out.

The string in the footer line, on the other hand, defaults to uname(3),
which already includes "FreeBSD" by default, and can be overridden
both by the "-I os=" option on the command line and by the .Os macro
in the manual page.

The file msec.in does not exist for the purpose of branding that
FreeBSD abuses it for, but to accomodate differing volume conventions
of operating systems.  For example, illumos has traditionally been
using the System V convention that includes

  LINE("4", "File Formats and Configurations")
  LINE("5", "Standards, Environments, and Macros")
  LINE("6", "Games and Demos")
  LINE("7", "Device and Network Interfaces")
  LINE("8", "Maintenance Procedures")
  LINE("9", "Kernel Concepts")

and many subsections, in particular in volume 3.

Of course, that also implies that formatting BSD device driver manuals
on illumos will show the misleading volume title "File Formats and
Configurations", but that can't be helped because manual page files do
not contain any indication which volume numbering scheme they adhere to.

> which means that when I use mandoc -T html to generate my website

I assume you use a Makefile for that purpose, or at least some kind
of script to regenerate the website when needed?

> I have to use a different build of mandoc so that the volume title
> just says "Miscellaneous Information Manual"
> instead of "FreeBSD Miscellaneous Information Manual."

What's wrong with saying something like

  index.html: index.mdoc
    mandoc -T html index.mdoc | sed '/head-vol/s/FreeBSD //' > index.html

in that script?

I doubt that use case warrants adding a feature that makes the
documentation longer and hence harder to read for every user.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv