Re: Subdirs of man*/ (was: [PATCH] ascii.7: chase down History to earliest) (refers: man -M tcl)

Alejandro Colomar <alx.manpages@xxxxxxxxx> · Mon, 17 Oct 2022 15:45:22 +0200

Hi!

On 10/17/22 13:56, наб wrote:
On Mon, Oct 17, 2022 at 01:10:51PM +0200, Alex Colomar wrote:
[CC += groff@, since it was CCd in the old conversation referred to here]
On 7/27/22 17:32, Ingo Schwarze wrote:
Alejandro Colomar wrote on Sun, Jul 24, 2022 at 06:17:40PM +0200:
I wondered for a long time what happens if you create subdirs within a
man? section.  How do man(1)s handle </usr/share/man/man3/python/foo.3>?
On *BSD systems, that typically means:

    The architecture-specific library function foo(3)
    for the "python" hardware architecture.

Here are a few examples from OpenBSD:

    /usr/share/man/man1/sparc64/mksuncd.1
    /usr/share/man/man2/armv7/arm_sync_icache.2
    /usr/share/man/man2/i386/i386_iopl.2
    /usr/share/man/man3/octeon/cacheflush.3
    /usr/share/man/man3/sgi/get_fpc_csr.3
    /usr/share/man/man4/alpha/irongate.4
    /usr/share/man/man4/amd64/mpbios.4
    /usr/share/man/man4/luna88k/cbus.4
    /usr/share/man/man4/macppc/openpic.4
    /usr/share/man/man4/powerpc64/opalcons.4
    /usr/share/man/man4/riscv64/sfgpio.4
    /usr/share/man/man5/sparc64/ldom.conf.5
    /usr/share/man/man8/hppa/boot.8
    /usr/share/man/man8/macppc/pdisk.8
    /usr/share/man/man8/sgi/sgivol.8
    /usr/share/man/man8/sparc64/ldomctl.8

On 10/17/22 03:22, наб wrote:
Cf., well, the UNIX Programmer's Manual:
    https://www.tuhs.org/Archive/Distributions/Research/Dennis_v1/UNIX_ProgrammersManual_Nov71.pdf
PDF page 191; yes, the typographical convention here is insane, and
the contemprary-correct way to refer to this page from within the manual
would be /just/ "/etc/ascii", but, given the context, "/etc/ascii (VII)"
makes the most sense to me

I just saw this and wondered if the subdirs in the past were used as just
part of the manual page name...

This typographical convention disappeared as early as V2;
the top-right page numbers were all trimmed to basename space section
(/etc/ascii (VII)        becomes ascii (VII)
  /dev/tty0 ... tty5 (IV) becomes tty0 (IV)
  &c.)

Cf.
https://www.tuhs.org/Archive/Distributions/Research/Dennis_v2/v2man.pdf

Thanks!!

In the BSD side of the proverbial family tree I don't see anything
similar to what you describe until 4.4BSD which has bsd.man.mk MANSUBDIR
and uses it to install to MANDIR/manN/MANSUBDIR/page.N, and uses it
reasonably broadly for vax/sparc/whatever.
I think this is as present-day?

Yeah, it looks like.

I don't see any on-line manuals in the SysIII/SysVr[1234] dumps I have,
so I assume these were distributed as books only, so idk.
Seeing as no arch-specific subdirectories survive in the illumos gate,
arch-only features are sometimes annotated "(not in 3B2)" inline,
and that the more esoteric pages have their center-top-page
(where you'd get "General Commands Manual" or whatever nowadays)
say like "(not on PDP-11)"/"(PDP-11 only)"/"(VAX stand-alone only)"/
"(3B20S only)" but are otherwise part of the same big book I assume
that never happened there.

Without context idk what you mean specifically

It comes back to this linux-man@ (and groff@) discussion:
<https://lore.kernel.org/linux-man/66c19a09-ef0f-0d85-0380-37a67ac483dd@xxxxxxxxx/>

There, Ingo talked about some idea he had:
<https://lore.kernel.org/linux-man/Yt1dz0+xfRuyCcXo@xxxxxxxxxxx/>

And we continued in this subthread, which was renamed:
<https://lore.kernel.org/linux-man/9e8a291d-672f-baec-3980-ae265712bd7b@xxxxxxxxx/>

Basically it can be resumed like this:

I started adding mandirs such as man3type, man3const, man3head; and we 
were discussing if that was a good organization, and if it would fit 
nicely into other existing things like 3bsd, 3perl, 3posix, ...

Also, having perl or python (or even posix) man pages open up by default 
or mess with autocomplete is not so nice when you're not interested in 
reading them.

So a solution I had thought would be to use subdirs, so you could for 
example:

$ man [-s] 3const foo       # manual for constant foo in C.
$ man [-s] 3const perl/foo  # manual for constant foo in perl.

Ingo's idea is to use:

$ man 3const foo
$ man -M perl [-s] 3const foo

which is compatible with the current use of MANSUBDIRs in the BSDs.

but I hope this shines
some light or whatever.

Yep, it helps :)

Cheers,

Alex

--
<http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature

Description: OpenPGP digital signature