Specify man section name at runtime

Specify man section name at runtime

[Cameron Katri]

[-- Attachment #1: Type: text/plain, Size: 547 bytes --]

Hello,

	I want to add the ability to specify the man section name at runtime,
instead of at compile time in msec.in. But I wanted to see how I
should implement it. I was thinking as a setting in man.conf, or as a
command line argument, or both. I wanted to know if this is something
you would be interested in actually incorporating and what it's
interface should look like before I start working on anything.

- Cameron Katri

-- 
Cameron Katri
Email: me@cameronkatri.com
PGP Fingerprint: 7D3B36CEA40FCC2181FB6DCDBAFFD97826540F1C

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: Specify man section name at runtime

[Jan Stary]

On Oct 03 13:49:18, me@cameronkatri.com wrote:
> I want to add the ability to specify the man section name at runtime,
> instead of at compile time in msec.in.

Why would you want that?

Also, why would you specify a string on a command line
only to have it displayed back at you?

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

Re: Specify man section name at runtime

[Ingo Schwarze]

Hi Cameron,

Cameron Katri wrote on Sun, Oct 03, 2021 at 01:49:18PM -0400:

> I want to add the ability to specify the man section name

I suspect you are talking about the volume titles (for example,
"General Commands Manual", "System Calls Manual", etc.), not about
section names (for example, "SYNOPSIS", "DESCRIPTION", "SEE ALSO", etc.).

> at runtime, instead of at compile time in msec.in.

Why?

What is the use case requiring that?

> But I wanted to see how I should implement it.
> I was thinking as a setting in man.conf,

Hard to judge without knowing what it is needed for, but at first sight,
it does not look like something that system administrators would need to
configure on a machine-by-machine basis.

> or as a command line argument,

That does not sound very convincing either.  Why would any user
type in long titles on the command line?

> or both.

When it comes to new features, less is usually more.  A new feature
needs a very good justification.

Perfection isn't when nothing more can be added, but when nothing
unimportant can be taken away.

> I wanted to know if this is something you would be interested in
> actually incorporating

So far, given the total lack of any justification, no, i am not (yet)
interested.

If you can explain a very convincing use case, the level of interest
might grow.

> and what it's interface should look like before I start working
> on anything.

Before it is possible to even start considering user interface design
for *any* feature, the critical question to consider is: what is the
purpose of the feature?  What will it be used for, and by which
kinds of users?

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

Re: Specify man section name at runtime

[Cameron Katri]

[-- Attachment #1: Type: text/plain, Size: 1093 bytes --]

On Sun, Oct 03, 2021 at 08:49:19PM +0200, Ingo Schwarze wrote:
> Hi Cameron,
> 
> Cameron Katri wrote on Sun, Oct 03, 2021 at 01:49:18PM -0400:
> 
> > I want to add the ability to specify the man section name
> 
> I suspect you are talking about the volume titles (for example,
> "General Commands Manual", "System Calls Manual", etc.), not about
> section names (for example, "SYNOPSIS", "DESCRIPTION", "SEE ALSO", etc.).

Yes.

> > at runtime, instead of at compile time in msec.in.
> 
> Why?
> 
> What is the use case requiring that?

Well this is a very niche use case, but on FreeBSD they patch msec.in to
say "FreeBSD General Commands Manual" etc. which means that when I use
mandoc -T html to generate my website 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."

> 
> Yours,
>   Ingo

Thanks for the feedback.

- Cameron Katri

-- 
Cameron Katri
Email: me@cameronkatri.com
PGP Fingerprint: 7D3B36CEA40FCC2181FB6DCDBAFFD97826540F1C

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: Specify man section name at runtime

[Ingo Schwarze]

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

Re: Specify man section name at runtime

[Cameron Katri]

[-- Attachment #1: Type: text/plain, Size: 1472 bytes --]

On Mon, Oct 04, 2021 at 10:06:59AM +0200, Ingo Schwarze wrote:
> 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
> 

I will try and get this patch removed from FreeBSD, which I agree is a
much better solution.

- Cameron Katri

-- 
Cameron Katri
Email: me@cameronkatri.com
PGP Fingerprint: 7D3B36CEA40FCC2181FB6DCDBAFFD97826540F1C

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]