Re: man -M tcl (was: All caps .TH page title)

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Fri, Jul 29, 2022 at 02:03:51PM +0200:

> BTW, I guess you also have the POSIX man pages in BSDs.  Do they come 
> from the kernel repo that I maintain, or do you have your own separate 
> repos?

  $ less /usr/ports/books/man-pages-posix/Makefile
 [...]
 COMMENT =    POSIX manual pages
 DISTNAME =   man-pages-posix-2013-a
 MASTER_SITES=https://www.kernel.org/pub/linux/docs/man-pages/man-pages-posix/
 EXTRACT_SUFX=.tar.xz
 [...]
 DOCDIR =     ${PREFIX}/share/doc/posix
 [...]
 # mapping of categories: source => destination
 MANS =          0p      3
 MANS +=         1p      1
 MANS +=         3p      3
 [...]

I don't know off the top of my head what FreeBSD and NetBSD ports do,
but you can no doubt look it up if you are interested.

> I'd like to discuss about the best place to recommend putting manual pages.
> 
> Do you know if any projects (Tcl and Tk maybe) are already using a 
> specific path for man pages?

 $ pkg_locate /man/man | grep -v :/usr/local/man | \
   sed 's/[^\/]*\/[^\/]*$//' | sed -E 's/(.*):(.*):(.*)/\3:\1/' | \
   sort | uniq > tmp.txt
 $ vi tmp.txt  # minimal manual cleanup
 $ cat tmp.txt
/usr/local/cyrus/man/:cyrus-imapd-3.4.4
/usr/local/heirloom-doctools/man/:heirloom-doctools-191015p0
/usr/local/jdk-1.8.0/man/:jdk-1.8.0.332.b09.1v0
/usr/local/jdk-11/man/:jdk-11.0.15.10.1v0
/usr/local/jdk-17/man/:jdk-17.0.3.7.1v0
/usr/local/lib/eopenssl/man/:openssl-1.0.2up4
/usr/local/lib/eopenssl11/man/:libretls-3.5.2
/usr/local/lib/eopenssl11/man/:openssl-1.1.1q
/usr/local/lib/eopenssl30/man/:openssl-3.0.5
/usr/local/lib/erlang21/man/:erlang-21.3.8.24v0
/usr/local/lib/erlang21/man/:erlang-wx-21.3.8.24v0
/usr/local/lib/node_modules/npm/man/:node-16.15.1v0
/usr/local/lib/ruby/gems/3.1/gems/kramdown-2.3.1/man/:ruby31-kramdown-2.3.1
/usr/local/lib/stk/4.0.1/man/:STk-4.0.1p19
/usr/local/lib/swipl-7.6.0/xpce/prolog/lib/:swi-prolog-7.6.0p15
/usr/local/lib/tcl/tcl8.5/man/:tcl-8.5.19p6
/usr/local/lib/tcl/tcl8.6/man/:tcl-8.6.12
/usr/local/lib/tcl/tk8.5/man/:tk-8.5.19p2
/usr/local/lib/tcl/tk8.6/man/:tk-8.6.12
/usr/local/plan9/man/:plan9port-20210323
/usr/local/riscv32-esp-elf/share/man/:riscv32-esp-elf-binutils-2.35.1.2020.1223
/usr/local/riscv32-esp-elf/share/man/:riscv32-esp-elf-gcc-8.4.0.2021.2
/usr/local/riscv32-esp-elf/share/man/:riscv32-esp-elf-gdb-2.35.1.2021.2
/usr/local/share/doc/posix/man/:man-pages-posix-2017a
/usr/local/share/docbook2X/xslt/:docbook2x-0.8.8p5
/usr/local/share/fish/man/:fish-3.4.1p3
/usr/local/share/libowfat/man/:libowfat-0.32p0
/usr/local/share/man/:smplayer-22.2.0
/usr/local/xtensa-esp32-elf/share/man/:xtensa-esp32-elf-binutils-2.35.1.2020.1223p0
/usr/local/xtensa-esp32-elf/share/man/:xtensa-esp32-elf-gcc-8.4.0.2021.2
/usr/local/xtensa-esp32-elf/share/man/:xtensa-esp32-elf-gdb-2.35.1.2021.2p0
/usr/local/xtensa-esp32s2-elf/share/man/:xtensa-esp32s2-elf-binutils-2.35.1.2020.1223
/usr/local/xtensa-esp32s2-elf/share/man/:xtensa-esp32s2-elf-gcc-8.4.0.2021.2
/usr/local/xtensa-esp32s2-elf/share/man/:xtensa-esp32s2-elf-gdb-2.35.1.2021.2
/usr/local/xtensa-esp32s3-elf/share/man/:xtensa-esp32s3-elf-binutils-2.35.1.2020.1223
/usr/local/xtensa-esp32s3-elf/share/man/:xtensa-esp32s3-elf-gcc-8.4.0.2021.2
/usr/local/xtensa-esp32s3-elf/share/man/:xtensa-esp32s3-elf-gdb-2.35.1.2021.2
/usr/local/xtensa-lx106-elf/share/man/:xtensa-lx106-elf-binutils-2.32p0
/usr/local/xtensa-lx106-elf/share/man/:xtensa-lx106-elf-gcc-10.2.0p3

I can't say so far if those paths are the default paths upstream chose
or in how many cases the OpenBSD porter chose them instead.
Finding out requires looking at each of these about 35 ports
individually.

> I think something under $docdir would be a nice place.
> 
> The FHS mentions[1] </usr[/local]/share/doc>.
> GNU specifies[2] that $docdir should be </usr/local/share/doc/pkgname> 
> for a </usr/local> prefix.
> 
> So they seem to agree in where $docdir lives.  Then we could make the 
> pkg-specific mandirs be </usr/local/share/doc/pkgname/man/man*>.
> 
> What are your thoughts?

Yes, even though /usr/local/share/doc/pkgname/man/man* is a bit long,
it makes more sense than paths like

  /usr/local/cyrus/man/
  /usr/local/heirloom-doctools/man/
  /usr/local/lib/erlang21/man/
  /usr/local/lib/node_modules/npm/man/
  /usr/local/lib/stk/4.0.1/man/
  /usr/local/lib/tcl/tcl8.6/man/
  /usr/local/plan9/man/
  /usr/local/share/fish/man/

Then again, *if* we go the -M alias way, these paths are only
ever used in the man.conf(5) file.  So where exactly they are
has no major impact on the user and is more a matter of system
cleanliness.

Yours,
  Ingo