All caps .TH page name

All caps .TH page name

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 987 bytes --]

Hi Branden and Ingo!

I've never been convinced about the page title being in all caps in the 
.TH line.  From recent groff@ discussions, I guess that neither of you 
are either.

I'd like to know why this has been the case historically, and any 
opinions you might have about me changing the man-pages to use the same 
caps as the actual identifier that I'm documenting (most of the time 
that would mean lowercase).  Basically, the same rules as within .SH NAME.

Also, does it have any functional implications?  I'm especially 
interested in knowing if that may affect in any way the ability of 
man(1) to find a page when invoked as `man TIMESPEC` for example.  I'm 
not saying necessarily that I'd like to keep that behavior.  I wouldn't 
mind breaking it, if it means that users will be able to differentiate 
upper- and lowercase pages.  We're not in Windows (nor MacOS), anyway.


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: All caps .TH page name

[G. Branden Robinson]

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

Hi Alex,

At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
> I've never been convinced about the page title being in all caps in
> the .TH line.  From recent groff@ discussions, I guess that neither of
> you are either.

Well, Ingo was more comfortable with it than I was.

> I'd like to know why this has been the case historically, and any
> opinions you might have about me changing the man-pages to use the
> same caps as the actual identifier that I'm documenting (most of the
> time that would mean lowercase).  Basically, the same rules as within
> .SH NAME.

I've read every edition of the Unix manual from Version 1 (1971) to
Version 7 (1979) and my surmise is that it was sheer inertia.  The
Teletype machines that were used to set the original versions of the
manual--remember, this is before troff even existed--might have been
capable of boldface through overstriking, but was not used this way as
far as I can tell in the V1 through V3 manual.

So this means that, for emphasis, you had regular type and underlined
type and that was it.

Under such limitations, the use of full capitals for emphasis is not
surprising.

After that--the V4 manual was the first to be typeset with troff--the
practice of full-capping the page titles in the headers was retained.

How deliberate a choice this was is not something I can answer.  The
decision was made in 1972.  You could ask some of the surviving
principal Bell Labs CSRC figures on the TUHS mailing list.

> Also, does it have any functional implications?  I'm especially
> interested in knowing if that may affect in any way the ability of
> man(1) to find a page when invoked as `man TIMESPEC` for example.

My understanding is that mandb(8) indexes based solely on the second
argument to the `TH` macro call and (what it interprets as) the contents
of the "Name" (or "NAME") section of the page.  It parses *roff itself
as best it can to determine this.  So the fact that the _first_ argument
to `TH` might be in full caps doesn't deter it.  (It might in fact have
made mandb(8) authors' job easier if an "honest lettercase" practice had
arisen back in the day--but it didn't).

Since he's a mandb(8) author/maintainer, I would again defer to Colin
Watson's knowledge and expertise in this area.

> I'm not saying necessarily that I'd like to keep that behavior.  I
> wouldn't mind breaking it, if it means that users will be able to
> differentiate upper- and lowercase pages.  We're not in Windows (nor
> MacOS), anyway.

True, although I would take a jaundiced view toward any software project
that distinguished its man page names, whether internally or from
others' solely by a difference in lettercase.

Regards,
Branden

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

Re: All caps .TH page title

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4527 bytes --]

Hi Branden,

On 7/21/22 20:36, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
>> I've never been convinced about the page title being in all caps in
>> the .TH line.  From recent groff@ discussions, I guess that neither of
>> you are either.
> 
> Well, Ingo was more comfortable with it than I was.
> 
>> I'd like to know why this has been the case historically, and any
>> opinions you might have about me changing the man-pages to use the
>> same caps as the actual identifier that I'm documenting (most of the
>> time that would mean lowercase).  Basically, the same rules as within
>> .SH NAME.
> 
> I've read every edition of the Unix manual from Version 1 (1971) to
> Version 7 (1979) and my surmise is that it was sheer inertia.  The
> Teletype machines that were used to set the original versions of the
> manual--remember, this is before troff even existed--might have been
> capable of boldface through overstriking, but was not used this way as
> far as I can tell in the V1 through V3 manual.
> 
> So this means that, for emphasis, you had regular type and underlined
> type and that was it.
> 
> Under such limitations, the use of full capitals for emphasis is not
> surprising.

That makes sense.

> 
> After that--the V4 manual was the first to be typeset with troff--the
> practice of full-capping the page titles in the headers was retained.
> 
> How deliberate a choice this was is not something I can answer.  The
> decision was made in 1972.  You could ask some of the surviving
> principal Bell Labs CSRC figures on the TUHS mailing list.

Is Doug one of them?  I've seem him on the groff@ list from time to 
time.  I added the groff@ list, in case this is of interest to someone 
there.

> 
>> Also, does it have any functional implications?  I'm especially
>> interested in knowing if that may affect in any way the ability of
>> man(1) to find a page when invoked as `man TIMESPEC` for example.
> 
> My understanding is that mandb(8) indexes based solely on the second
> argument to the `TH` macro call and (what it interprets as) the contents
> of the "Name" (or "NAME") section of the page.  It parses *roff itself
> as best it can to determine this.  So the fact that the _first_ argument
> to `TH` might be in full caps doesn't deter it.  (It might in fact have
> made mandb(8) authors' job easier if an "honest lettercase" practice had
> arisen back in the day--but it didn't).

Okay.

> 
> Since he's a mandb(8) author/maintainer, I would again defer to Colin
> Watson's knowledge and expertise in this area.

Added to CC, in case he wants to intervene.

> 
>> I'm not saying necessarily that I'd like to keep that behavior.  I
>> wouldn't mind breaking it, if it means that users will be able to
>> differentiate upper- and lowercase pages.  We're not in Windows (nor
>> MacOS), anyway.
> 
> True, although I would take a jaundiced view toward any software project
> that distinguished its man page names, whether internally or from
> others' solely by a difference in lettercase.

Heh!  You've never tried to clone the Linux man-pages in Windows or 
MacOS, it seems :p

$ find man* -type f \
   | tr '[:upper:]' '[:lower:]' \
   | sort \
   | uniq -d \
   | while read f; do
	find man* -type f \
	| grep -i $f;
   done;
man2/_Exit.2
man2/_exit.2
man3/nan.3
man3/NAN.3


$ find man* -type f \
   | tr '[:upper:]' '[:lower:]' \
   | sort \
   | uniq -d \
   | while read f; do
	find man* -type f \
	| grep -i $f;
   done \
   | while read f; do
	echo ===$f===;
	head -n1 $f;
   done;
===man2/_Exit.2===
.so man2/_exit.2
===man2/_exit.2===
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
===man3/nan.3===
.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
===man3/NAN.3===
.so man3/INFINITY.3


At least, _Exit(2) and _exit(2) point to the same page.  nan(3) and 
NAN(3) don't, though!

We can't blame the writers, since the identifiers have those names in C. 
  Luckily, man(1) shows you the right page if you specify the right string.


I feel a need to fix this lack of precision in the page titles.  Unless 
someone opposes to it with some strong reason, which I don't expect.

It'll take some time to do it, but if no-one speaks in a reasonable 
time, I'll start doing it :).

Cheers,

Alex

> 
> Regards,
> Branden

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: All caps .TH page title

[Colin Watson]

On Fri, Jul 22, 2022 at 01:16:49AM +0200, Alejandro Colomar wrote:
> On 7/21/22 20:36, G. Branden Robinson wrote:
> > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
> > > Also, does it have any functional implications?  I'm especially
> > > interested in knowing if that may affect in any way the ability of
> > > man(1) to find a page when invoked as `man TIMESPEC` for example.
> > 
> > My understanding is that mandb(8) indexes based solely on the second
> > argument to the `TH` macro call and (what it interprets as) the contents
> > of the "Name" (or "NAME") section of the page.  It parses *roff itself
> > as best it can to determine this.  So the fact that the _first_ argument
> > to `TH` might be in full caps doesn't deter it.  (It might in fact have
> > made mandb(8) authors' job easier if an "honest lettercase" practice had
> > arisen back in the day--but it didn't).
> 
> Okay.
> 
> > Since he's a mandb(8) author/maintainer, I would again defer to Colin
> > Watson's knowledge and expertise in this area.
> 
> Added to CC, in case he wants to intervene.

The above is not quite correct.  man-db doesn't index on the .TH section
at all, and I don't believe I've encountered the practice of doing so in
other indexers (I could be wrong, but I think that's something I would
have remembered if I'd noticed it).  Rather, it parses the "NAME" (or
"Name", or a number of localized variants) section of pages using the
man macro set for "foo \- description" lines and uses the left-hand side
of those for page names, or equivalently looks for .Nm requests in pages
using the mdoc macro set.

With the exception of handling localized variants of that section name,
which is a pretty ugly pile of special cases, I believe this to be
fairly traditional behaviour.  I can't say I would have done it that way
if I'd been designing the system from scratch since it really involves
far too much half-arsed parsing, but it seemed to be the usual thing to
do when I came on the scene.

Changing the arguments to .TH won't bother man-db at all.

> > > I'm not saying necessarily that I'd like to keep that behavior.  I
> > > wouldn't mind breaking it, if it means that users will be able to
> > > differentiate upper- and lowercase pages.  We're not in Windows (nor
> > > MacOS), anyway.

man-db's man(1) performs case-insensitive lookups by default, which I've
found to be more useful behaviour.  Case-sensitive lookup can be
requested using the -I/--match-case option.

As far as I know this was an innovation when I introduced it in 2002, so
I don't know how widespread this behaviour is among man(1)
implementations.  You probably can't rely on it.

But in any case, as above, changing the arguments to .TH doesn't affect
this.  I haven't noticed it being widespread practice to spuriously
capitalize the name part of lines in the "NAME" section.

Cheers,

-- 
Colin Watson (he/him)                              [cjwatson@debian.org]

Re: All caps .TH page title

[G. Branden Robinson]

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

At 2022-07-22T01:22:57+0100, Colin Watson wrote:
> On Fri, Jul 22, 2022 at 01:16:49AM +0200, Alejandro Colomar wrote:
> > On 7/21/22 20:36, G. Branden Robinson wrote:
> > > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
> > > > Also, does it have any functional implications?  I'm especially
> > > > interested in knowing if that may affect in any way the ability
> > > > of man(1) to find a page when invoked as `man TIMESPEC` for
> > > > example.
> > > 
> > > My understanding is that mandb(8) indexes based solely on the
> > > second argument to the `TH` macro call and (what it interprets as)
> > > the contents of the "Name" (or "NAME") section of the page.  It
> > > parses *roff itself as best it can to determine this.  So the fact
> > > that the _first_ argument to `TH` might be in full caps doesn't
> > > deter it.  (It might in fact have made mandb(8) authors' job
> > > easier if an "honest lettercase" practice had arisen back in the
> > > day--but it didn't).
[...]
> > > Since he's a mandb(8) author/maintainer, I would again defer to
> > > Colin Watson's knowledge and expertise in this area.
[...]
> 
> The above is not quite correct.  man-db doesn't index on the .TH
> section at all, and I don't believe I've encountered the practice of
> doing so in other indexers (I could be wrong, but I think that's
> something I would have remembered if I'd noticed it).  Rather, it
> parses the "NAME" (or "Name", or a number of localized variants)
> section of pages using the man macro set for "foo \- description"
> lines and uses the left-hand side of those for page names, or
> equivalently looks for .Nm requests in pages using the mdoc macro set.

Ah, thanks, Colin.  A quick consultation of ncurses man pages reveals
that mandb(8)'s idea of the manual section comes from its place in the
directory hierarchy, not from parsing the arguments to the `TH` call.
My error!

> With the exception of handling localized variants of that section
> name, which is a pretty ugly pile of special cases, I believe this to
> be fairly traditional behaviour.  I can't say I would have done it
> that way if I'd been designing the system from scratch since it really
> involves far too much half-arsed parsing, but it seemed to be the
> usual thing to do when I came on the scene.

We could have groff man(7) and mdoc(7) recognize a register, named
`INDEX`, `DB`, or `SUMMARIZE` or something, which would cause the
package(s) to emit the required information, derived solely from page
content, in a desirable format.  Say, JSON, maybe.  Upon seeing this
register and reporting the data, the package could then invoke `nx` to
move to the next input file.

Thus, potentially, the indexing data could be generated with great
speed--you could call groff (or nroff, it wouldn't matter) with as many
man page file arguments as desired, specifying no preprocessor options
(except maybe those for preconv), and a large percentage of page content
would never even be read, let alone formatted.

Why, I wonder, was the thing not done this way in the first place?
Possibly because what follows "Name" can be arbitrary roff language
input.  However...

The "Name" section's contents can be stored in a diversion.  In normal
circumstances, this diversion's contents would be emitted immediately
upon any other `SH` call (or, for degenerate pages that declare no
sections after "Name", when the page's end macro is called[1]).

Once in a diversion, these contents are subject to "sanitization", a
feature I'm chewing over adding to the formatter.[2]  The gist is that
all the garbage (font changes, special character escape sequences) you
currently spent time parsing or stripping away is already removed or
transformed for you, leaving clean, printable ASCII or UTF-8.

At this point I pause to let the wave of horror break over my audience.

Regards,
Branden

[1] andoc.tmac contrives for this to be the case when rendering multiple
    pages.
[2] https://savannah.gnu.org/bugs/?62787

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

Re: All caps .TH page title

[G. Branden Robinson]

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

[Colin and Ingo dropped from CC since I know they read the groff list]

Hi Alex,

At 2022-07-22T01:16:49+0200, Alejandro Colomar wrote:
> On 7/21/22 20:36, G. Branden Robinson wrote:
> > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
> > > I've never been convinced about the page title being in all caps
> > > in the .TH line.
[...]
> > > I'd like to know why this has been the case historically, and any
> > > opinions you might have about me changing the man-pages to use the
> > > same caps as the actual identifier that I'm documenting (most of
> > > the time that would mean lowercase).  Basically, the same rules as
> > > within .SH NAME.
[...]
> > After that--the V4 manual was the first to be typeset with
> > troff--the practice of full-capping the page titles in the headers
> > was retained.
> > 
> > How deliberate a choice this was is not something I can answer.  The
> > decision was made in 1972.  You could ask some of the surviving
> > principal Bell Labs CSRC figures on the TUHS mailing list.
> 
> Is Doug one of them?  I've seem him on the groff@ list from time to
> time.  I added the groff@ list, in case this is of interest to someone
> there.

Yes, Doug McIlroy follows both the groff and TUHS lists.

> Heh!  You've never tried to clone the Linux man-pages in Windows or MacOS,
> it seems :p

No, can't say I've had the...pleasure.

> At least, _Exit(2) and _exit(2) point to the same page.  nan(3) and
> NAN(3) don't, though!

Pretty gross.  A useful counterexample of good practice, though.

> We can't blame the writers, since the identifiers have those names in
> C.  Luckily, man(1) shows you the right page if you specify the right
> string.

Yes, and at least they're closely related and from the same project.

This is the only man page I know of that documents only simple (i.e.,
not function-like) C preprocessor macros.  You're more conversant with
libc-ish man pages so you may know of others, but this is the sort of
content that, as a user, I would prefer to find in, say, a "math.h(3)"
man page.  Having these constants in a page by themselves does little to
situate them within the context of the C math library API.  But I know I
have suggested this to you before.  ;-)

I observe that the most popular simple macro of all, NULL, has no man
page.

> I feel a need to fix this lack of precision in the page titles.
> Unless someone opposes to it with some strong reason, which I don't
> expect.

You never know.  But keep in mind that a strong objection is not the
same thing as a strong reason.

> It'll take some time to do it, but if no-one speaks in a reasonable
> time, I'll start doing it :).

We should all practice our scowling faces for anyone who dares to
promulgate man pages named "lS", "prIntf", or similar.

Regards,
Branden

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

Re: All caps .TH page title

[G. Branden Robinson]

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

At 2022-07-21T20:34:39-0500, G. Branden Robinson wrote:
> Ah, thanks, Colin.  A quick consultation of ncurses man pages reveals
> that mandb(8)'s idea of the manual section comes from its place in the
> directory hierarchy, not from parsing the arguments to the `TH` call.
> My error!

Sorry, no, I was still wrong.  I guess it comes from the file extension
on the man page.

John Gardner's not the only person having trouble today.

90 dB of fans and a dehumidifier to dry out a flooded floor does not
make for the most productive thinking environment.

Regards,
Branden

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

Re: All caps .TH page title

[Alejandro Colomar (man-pages)]

On 7/22/22 04:14, G. Branden Robinson wrote:
>> At least, _Exit(2) and _exit(2) point to the same page.  nan(3) and
>> NAN(3) don't, though!
> 
> Pretty gross.  A useful counterexample of good practice, though.
> 
>> We can't blame the writers, since the identifiers have those names in
>> C.  Luckily, man(1) shows you the right page if you specify the right
>> string.
> 
> Yes, and at least they're closely related and from the same project.
> 
> This is the only man page I know of that documents only simple (i.e.,
> not function-like) C preprocessor macros.  You're more conversant with
> libc-ish man pages so you may know of others,

Actually, I don't.

At least not previous to my introduction of intN_t(3type), which 
documents things like INT8_WIDTH and INT8_MAX (although I didn't [yet] 
create link pages with those name).

> but this is the sort of
> content that, as a user, I would prefer to find in, say, a "math.h(3)"
> man page.  Having these constants in a page by themselves does little to
> situate them within the context of the C math library API.  But I know I
> have suggested this to you before.  ;-)

I remember.  And I didn't ignore the suggestion; I've been thinking 
about it several times.

There are various problems with documenting math.h(0) (section 0 was 
introduced for header files, but I don't know when, how, or why that 
happened; see the man-pages-posix repo for example.  Other projects 
(Oracle? I don't remember well) use a subsection 3head, though.

I think I don't like the idea of _only_ documenting macros in a header 
file doc.  That is likely to produce a huge page such as 
system_data_types(7) once was, or queue(3).  limits.h(0) is an exception 
in my head, since even though it's huge, all of them are related (all 
are limits), and it's easy to read.  limits.h(0) has the advantage that 
you can navigate the page to see the limit that best fits your need; I 
would counter argue that with the following for the general case: man(1) 
supports regex search, so if you just want to search for all limits, 
man(1) supports regex searching, so you could do `man -k -s3def _MAX` to 
serach for *_MAX limits in a hypothetical 3def (or 3macro?) subsection 
dedicated to macros.  See for example:

$ man -s3type -k int._t
int8_t (3type)       - fixed-width basic integer types
intN_t (3type)       - fixed-width basic integer types
uint8_t (3type)      - fixed-width basic integer types
uintN_t (3type)      - fixed-width basic integer types


> 
> I observe that the most popular simple macro of all, NULL, has no man
> page.

Oh, I had been thinking about it exactly yesterday, as I was wroking 
with the both loved and hated void(3type).

Maybe NULL(3something) starts a brand new subsection soon.  Do you have 
any preferences for the section name, since you mentioned it?  :-)


BTW, I think I didn't reply (or if I did was very short) to your comment 
that other languages may find it difficult to mirror our use of 
subsections, since their main section is already a subsection (e.g., 
3pl).  I'd say that since C is the native Unix language, and others are 
just... others?, I'd optimize for C, and let other languages find a way 
to document their things.  It would be easy to say just go away, the man 
pages are for C, but I won't dare to say that, since I like man pages, 
and I'd like to see more documentation for languages that I sometimes 
have to use be in the form of man pages, so I'll try to come up with a 
more imaginative answer:  how about using subsubsections of the form 
3pl_type?  At least it's a possibility.  man(1) would handle them as any 
other subsection, but that's not a big problem.  Maybe man(1) could 
develop a way to provide subsubsections...  Colin, any ideas in this regard?

> 
>> I feel a need to fix this lack of precision in the page titles.
>> Unless someone opposes to it with some strong reason, which I don't
>> expect.
> 
> You never know.  But keep in mind that a strong objection is not the
> same thing as a strong reason.

Yup.  I expect the former, but not the latter. ;)

> 
>> It'll take some time to do it, but if no-one speaks in a reasonable
>> time, I'll start doing it :).
> 
> We should all practice our scowling faces for anyone who dares to
> promulgate man pages named "lS", "prIntf", or similar.

Oh, I trust people is not so evil... I'll train the face just in case, 
though.


Cheers,

Alex

> 
> Regards,
> Branden

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: All caps .TH page title

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1816 bytes --]

Hi,

On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:
> BTW, I think I didn't reply (or if I did was very short) to your comment 
> that other languages may find it difficult to mirror our use of 
> subsections, since their main section is already a subsection (e.g., 
> 3pl).  I'd say that since C is the native Unix language, and others are 
> just... others?, I'd optimize for C, and let other languages find a way 
> to document their things.  It would be easy to say just go away, the man 
> pages are for C, but I won't dare to say that, since I like man pages, 
> and I'd like to see more documentation for languages that I sometimes 
> have to use be in the form of man pages, so I'll try to come up with a 
> more imaginative answer:  how about using subsubsections of the form 
> 3pl_type?  At least it's a possibility.  man(1) would handle them as any 
> other subsection, but that's not a big problem.  Maybe man(1) could 
> develop a way to provide subsubsections...  Colin, any ideas in this 
> regard?

Or, maybe it's the time to write a whole new volume?  I think there's a 
comparable difference between 3type and 3 than between 2 and 3 or 1 and 
8, so it would be merited.  I didn't do it before for two reasons: it 
might break software that assumes than Unix manuals use a single number 
followed by an optional string (I'd say it's not a fair assumption to 
say that man9 would be the last one ever used; if there's 9, there might 
be a 10 some day), and because other projects had already used 3type.

But, that would start a clean namespace.  Maybe it's worth it.

How would you feel if I inaugurate man10 for types, and later man11 for 
non-function-like macros? :D


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: All caps .TH page title

[Ingo Schwarze]

Hi,

Colin Watson wrote on Fri, Jul 22, 2022 at 01:22:57AM +0100:

> man-db doesn't index on the .TH section at all, and I don't believe
> I've encountered the practice of doing so in other indexers
> (I could be wrong, but I think that's something I would have
> remembered if I'd noticed it).

FWIW, the mandoc(1) implementation of the indexes uses the following
to derive names for a page:

 * the first component of the file name,
   including of hard, soft, and .so links
 * in man(7) pages, the first argument of the .TH macro        <<=====
 * in man(7) pages, any words preceding the first "-" or "\-"
   in the NAME section
 * in mdoc(7) pages, the first argument of the .Dt macro       <<=====
 * in mdoc(7) pages, arguments of .Nm macros in the NAME section
 * in mdoc(7) pages, arguments of .Nm macros in the SYNOPSIS
 * in mdoc(7) pages, first arguments of .Fo and .Fn macros in the SYNOPSIS

The last two - mdoc(7) SYNOPSIS content - are only used for man -k
searches explicitly specifying the Nm search key.  All others are also
used for plain man(1) name lookup.

In mandoc the following are used as section names:

 * if the directory name starts with "man" or "cat", the rest of it
 * the file name suffix, starting after the last dot
 * in man(7) pages, the second argument of the .TH macro
 * in mdoc(7) pages, the second argument of the .Dt macro

The above rules often cause pages to end up with more than on name
and and more than one section.  For example, a file called

  man3p/strcpy.3

containing

  .TH strlcat 3bsd
  .SH NAME
  wcslcpy, wcslcat \- yadayada

can be found with any of the following commands, and several more:

  man 3bsd strcpy
  man 3 strlcat
  man wcslcat
  man 3p wcslcpy

As a special case, if the .TH or .Dt argument agrees with one among
the other names but differs in case, it is not used, because
mandoc assumes the other name is likely correctly cased while
the name in the .TH or .Dt macro may have been converted to all caps.

> man-db's man(1) performs case-insensitive lookups by default, which
> I've found to be more useful behaviour.  Case-sensitive lookup can be
> requested using the -I/--match-case option.

In the mandoc implementation, plain man(1) follows the tradition of
being case-sensitive, but i must admit examples of manual pages with
names that differ only in case are hard to find indeed, so it might
make sense to change this and make it agree with man-db.

In the mandoc implementation of apropos(1), searches use case-insensitive
extended regular expressions by default (which originally was a
proposal coming from FreeBSD).  If the regular expression operator '~'
is explicitly specified, the search becomes case-sensitive.  If the -i
option is given, it becomes case-insensitive again.  The substring-search
operator '=' always remains case-insensitive no matter what.

> As far as I know this was an innovation when I introduced it in 2002,
> so I don't know how widespread this behaviour is among man(1)
> implementations.  You probably can't rely on it.
> 
> But in any case, as above, changing the arguments to .TH doesn't affect
> this.  I haven't noticed it being widespread practice to spuriously
> capitalize the name part of lines in the "NAME" section.

Indeed, doing that would be very bad style, not least because it would
make the correct capitalization of the name hard to find for the
human reader of the manual page.

Yours,
  Ingo

Re: All caps .TH page name

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Thu, Jul 21, 2022 at 01:36:20PM -0500:

> I would take a jaundiced view toward any software project
> that distinguished its man page names, whether internally or from
> others' solely by a difference in lettercase.

Inside one project, causing such clashes is certainly a bad idea.
But just as same-case clashes sometimes happen accidentally -
consider this on OpenBSD with the "mono" package installed -

   $ man mdoc | sed -n 4p
       mdoc - semantic markup language for formatting manual pages
   $ man 1 mdoc | sed -n 4p
       mdoc - Mono documentation management tool

different-case clashes also happen occasionally:

   $ man -T ascii err | sed -n '4p;5p'
       err, verr, errc, verrc, errx, verrx, warn, vwarn, warnc,
       vwarnc, warnx, vwarnx - formatted error messages
   $ man -T ascii ERR | sed -n '4p'    
       ERR - OpenSSL error codes

   $ man -T ascii sha256 | sed -n '4p;5p'
       md5, sha1, sha256, sha512 - calculate a message digest (checksum)
       for a file
   $ man -T ascii SHA256 | sed -n '4p;5p;6p;7p'
       SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init,
       SHA224_Update, SHA224_Final, SHA256, SHA256_Init, SHA256_Update,
       SHA256_Final, SHA384, SHA384_Init, SHA384_Update, SHA384_Final,
       SHA512, SHA512_Init, SHA512_Update, SHA512_Final - Secure Hash
       Algorithm

Admittedly, these clashes are extremely rare, so it's not a big issue 
either way, at least not for practical purposes.

Yours,
  Ingo

Re: All caps .TH page title

[G. Branden Robinson]

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

Hi Alex,

At 2022-07-22T13:46:37+0200, Alejandro Colomar wrote:
> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:
> > BTW, I think I didn't reply (or if I did was very short) to your
> > comment that other languages may find it difficult to mirror our use
> > of subsections, since their main section is already a subsection
> > (e.g., 3pl).

In my (Debian-centric) experience, I see "3perl"--just a detail.

> > I'd say that since C is the native Unix language, and others are
> > just... others?, I'd optimize for C, and let other languages find a
> > way to document their things.  It would be easy to say just go away,
> > the man pages are for C, but I won't dare to say that, since I like
> > man pages, and I'd like to see more documentation for languages that
> > I sometimes have to use be in the form of man pages, so I'll try to
> > come up with a more imaginative answer:  how about using
> > subsubsections of the form 3pl_type?  At least it's a possibility. 
> > man(1) would handle them as any other subsection, but that's not a
> > big problem.  Maybe man(1) could develop a way to provide
> > subsubsections...  Colin, any ideas in this regard?

I don't see any reason to privilege the C language more than it already
is.  Let us review the default manual section titles--the material that
appears in the center header by default when man pages are rendered.

  .\" Localize manual section titles for English.
  .de an*localize-strings
  .  ds an*section1 General Commands Manual\"
  .  ds an*section2 System Calls Manual\"
  .  ds an*section3 Library Functions Manual\"
  .  ds an*section4 Kernel Interfaces Manual\"
  .  ds an*section5 File Formats Manual\"
  .  ds an*section6 Games Manual\"
  .  ds an*section7 Miscellaneous Information Manual\"
  .  ds an*section8 System Manager's Manual\"
  .  ds an*section9 Kernel Developer's Manual\"

Literally none of this necessarily implies the use of C.  Instead these
sections are a coalition--perhaps an uneasy one--of three different
categorical axes.

  (1) who needs the information--users, programmers, or administrators
  (2) whether the information is a kernel-invariant or not
  (3) the syntax of data presented to other system components

I suggest that this arrangement survives not just due to blind inertia,
though that may be the preponderant factor, but because in a POSIX
system these categories remain fairly stable.  One can bloat or shrink
the kernel but there's always going to be a kernel.  There is a sharp
distinction between kernel (or supervisor) mode and user mode.  Some
users are more privileged than others, and perform administrative tasks.
The file metaphor as a persistent array of (often seekable, often
persistent) bytes is deeply entrenched.

> Or, maybe it's the time to write a whole new volume?  I think there's
> a comparable difference between 3type and 3 than between 2 and 3 or 1
> and 8, so it would be merited.  I didn't do it before for two reasons:
> it might break software that assumes than Unix manuals use a single
> number followed by an optional string (I'd say it's not a fair
> assumption to say that man9 would be the last one ever used; if
> there's 9, there might be a 10 some day), and because other projects
> had already used 3type.
> 
> But, that would start a clean namespace.  Maybe it's worth it.
> 
> How would you feel if I inaugurate man10 for types, and later man11 for
> non-function-like macros? :D

Permit me to play an unaccustomed role as a voice of conservatism.  I
don't think we need the section number, or even a section suffix, to
communicate information about a data type.

(A) Header files could be put in section 3 under their names as-is.  We
    should remember that C standard library header files, per ISO C,
    need not be literally present on the file system; they can be
    provided by the compiler using unspecified means.  I point this out
    to emphasize their exotic nature.  They need not be ordinary files,
    though on POSIX systems we should expect this.  I don't think
    inaugurating a "section 0" serves any use here, since C identifiers
    will not collide with them.  We do not write a stand-alone man page
    for a member of a structure, so the element "h" of a hypothetical
    "struct math" will be documented in "math(3)", not "math.h(3)".

(B) Collisions in C's name spaces are discouraged by common practice and
    seldom leveraged even where syntactically distinct.  Functions and
    variables ("objects") are in the same name space in C, and data
    types and objects are so confusable[1] that in practice programmers
    treat them as being in the same name space.  For example, structure
    tags enjoy their own name space but most novice and even many
    experienced C programmers are shaky on the fact.  (This ignorance
    was compounded for decades by a common idiom of introducing type
    aliases ("typedefs"[2]) for structs as soon as they were declared.)

The above points are why I think we not only don't need new sections of
the manual, but that suffixes like "type" and "def" are not performing
any service for the reader that isn't clearly and obviously communicated
in the text of the man page, if it is written to a minimum level of
quality.  The synopsis will say what is needed, and within a programming
language, names exposed by an API should not be ambiguous, so the suffix
won't be necessary to aid the apropos/"man -k"-using reader.

Here, let me do an impression.  [tousels hair; puts on big glasses;
becomes copyright rentier; indulges predatory, monopolistic practices]

"Nine sections of the manual ought to be enough for anybody."

Regards,
Branden

[1] https://en.wikipedia.org/wiki/Lexer_hack
[2] A deceitful little term if there ever was one, because it does
    _nothing_ to enhance type conformance checking.  Kernighan pointed
    out that "strong typing is not dimensional analysis" in his article
    "Why Pascal Is Not My Favorite Programming Language", when
    enumerating deficiencies of that language.  Here's his example.

    type
      apple = integer;
      orange = integer;

    C works similarly.

    typedef int apple;
    typedef int orange;

    Kernighan failed to note that strong typing _could_ be dimensional
    analysis, if taken seriously.  Perhaps he didn't because the same
    criticism could then be made of C, which had his name on it and
    proceeded to eat much of Pascal's lunch in the '80s and '90s--for
    reasons conspicuously distinct from the quality of its type
    checking.

    If you want real checking of a primitive type in C, you have to wrap
    it in a one-member struct.  Even then you don't get range
    constraints, which are frequently valuable and which Pascal did
    support.  Kernighan clucked in the same paper that range checks
    "seemed like a service, though they too exact a run-time penalty".
    In other words, they are costly.  I wonder how we might measure the
    cost of failures to observe CERT'S INT{30,32}-C[3] in the quest for
    bragging rights about performance.  Obviously its magnitude was
    recognized only in retrospect.

    Now, lest I seem hard on Kernighan here, let me note that, among
    other excellent points in the paper, his thorough trashing of
    Pascal's array handling, where the size was regarded as an
    integral part of the data type, was completely deserved.  For those
    who haven't read the paper, this means that, yes, in pre-ISO Pascal,
    your function which operated on char arrays of length 4 would not be
    permitted to operate on char arrays of length 5.  The compiler (or
    interpreter) would stop you.  It is hard for me to imagine, as a
    workaday programmer, how Wirth let the language escape the
    laboratory with this defect.

[3] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152052

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

Re: All caps .TH page title

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 9940 bytes --]

Hi Branden,

On 7/22/22 21:03, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2022-07-22T13:46:37+0200, Alejandro Colomar wrote:
>> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:
>>> BTW, I think I didn't reply (or if I did was very short) to your
>>> comment that other languages may find it difficult to mirror our use
>>> of subsections, since their main section is already a subsection
>>> (e.g., 3pl).
> 
> In my (Debian-centric) experience, I see "3perl"--just a detail.

Yeah, I was talking from memory.  You can tell how little perl I write.
Most of my perl knowledge is PCRE (actually, I know quite a bit of 
that), but not much actual perl.


> 
>    .\" Localize manual section titles for English.
>    .de an*localize-strings
>    .  ds an*section1 General Commands Manual\"
>    .  ds an*section2 System Calls Manual\"
>    .  ds an*section3 Library Functions Manual\"
>    .  ds an*section4 Kernel Interfaces Manual\"

4 is special files for me.  Kernel interfaces?  that's a very unclear 
name to me.  syscalls are also kernel interfaces.

>    .  ds an*section5 File Formats Manual\"
>    .  ds an*section6 Games Manual\"

If we have a whole section for rogue(6), anything can get its own section ;)

>    .  ds an*section7 Miscellaneous Information Manual\" >    .  ds an*section8 System Manager's Manual\"
>    .  ds an*section9 Kernel Developer's Manual\"

I wonder why the Linux kernel doesn't use this one.  Did it ever do? 
I've seen some man9 pages floating around, but I don't know where they 
come from, and why they aren't in the Linux man-pages project.

> 
> Literally none of this necessarily implies the use of C.  Instead these
> sections are a coalition--perhaps an uneasy one--of three different
> categorical axes.
> 
>    (1) who needs the information--users, programmers, or administrators
>    (2) whether the information is a kernel-invariant or not
>    (3) the syntax of data presented to other system components
> 
> I suggest that this arrangement survives not just due to blind inertia,
> though that may be the preponderant factor, but because in a POSIX
> system these categories remain fairly stable.  One can bloat or shrink
> the kernel but there's always going to be a kernel.  There is a sharp
> distinction between kernel (or supervisor) mode and user mode.  Some
> users are more privileged than others, and perform administrative tasks.
> The file metaphor as a persistent array of (often seekable, often
> persistent) bytes is deeply entrenched.

That makes sense.  Maybe 3type is good.

> 
>> Or, maybe it's the time to write a whole new volume?  I think there's
>> a comparable difference between 3type and 3 than between 2 and 3 or 1
>> and 8, so it would be merited.  I didn't do it before for two reasons:
>> it might break software that assumes than Unix manuals use a single
>> number followed by an optional string (I'd say it's not a fair
>> assumption to say that man9 would be the last one ever used; if
>> there's 9, there might be a 10 some day), and because other projects
>> had already used 3type.
>>
>> But, that would start a clean namespace.  Maybe it's worth it.
>>
>> How would you feel if I inaugurate man10 for types, and later man11 for
>> non-function-like macros? :D
> 
> Permit me to play an unaccustomed role as a voice of conservatism.  I
> don't think we need the section number, or even a section suffix, to
> communicate information about a data type.
> 
> (A) Header files could be put in section 3 under their names as-is.  We
>      should remember that C standard library header files, per ISO C,
>      need not be literally present on the file system; they can be
>      provided by the compiler using unspecified means.  I point this out
>      to emphasize their exotic nature.  They need not be ordinary files,
>      though on POSIX systems we should expect this.  I don't think
>      inaugurating a "section 0" serves any use here, since C identifiers
>      will not collide with them.  We do not write a stand-alone man page
>      for a member of a structure, so the element "h" of a hypothetical
>      "struct math" will be documented in "math(3)", not "math.h(3)".

Regarding structure tags, I aready defended the need to do something, 
when I added the -struct suffix (which was a poor man's subsection).

If I were to rewrite the C library and kernel from scratch, without 
backwards compatibility, I'd fix many many things.  But that train 
passed many years before I was born.

For one example, we have stat(2) and stat(3type).  Why did they exploit 
the fact that C allows calling a function and a struct the same?  Don't 
ask me.  But they did.

So we need to be able to distinguish struct, union, and enum tags from 
global namespace identifiers.  -struct was an option.  man3type is much 
better, IMO (and already in use by Illumos and other systems).  Maybe 
man10 would be going too far.

But I strongly disagree with the initial temporary solution Michael and 
I decided at first, which was simply to avoid adding a link page stat(3) 
(and a few others) to system_data_types(7), even though we actually 
documented stat in system_data_types(7).
There's a problem, and I want to solve it.

> 
> (B) Collisions in C's name spaces are discouraged by common practice and
>      seldom leveraged even where syntactically distinct.  Functions and
>      variables ("objects") are in the same name space in C, and data
>      types and objects are so confusable[1] that in practice programmers
>      treat them as being in the same name space.  For example, structure
>      tags enjoy their own name space but most novice and even many
>      experienced C programmers are shaky on the fact.  (This ignorance
>      was compounded for decades by a common idiom of introducing type
>      aliases ("typedefs"[2]) for structs as soon as they were declared.)

I wish they used _s suffix for structs, or that at least they didn't 
abuse this C feature, but they did.  It's too late to change that.

> 
> The above points are why I think we not only don't need new sections of
> the manual, but that suffixes like "type" and "def" are not performing
> any service for the reader that isn't clearly and obviously communicated
> in the text of the man page, if it is written to a minimum level of
> quality.  The synopsis will say what is needed, and within a programming
> language, names exposed by an API should not be ambiguous, so the suffix
> won't be necessary to aid the apropos/"man -k"-using reader.

For the replies above, I'm strongly pushing for a 3type and a 
3somethingelse subsections.

Now, I'd really like to get a good name for the constants subsection. 
3def seems to be too constrained to C's #define (and when C adds 
constexpr some day, man3def might be not a good name anymore).

> 
> Here, let me do an impression.  [tousels hair; puts on big glasses;
> becomes copyright rentier; indulges predatory, monopolistic practices]
> 
> "Nine sections of the manual ought to be enough for anybody."

I think there's no need (yet) for new whole sections; you convinced me 
about that. :-)

> 
> Regards,
> Branden
> 
> [1] https://en.wikipedia.org/wiki/Lexer_hack
> [2] A deceitful little term if there ever was one, because it does
>      _nothing_ to enhance type conformance checking.  Kernighan pointed
>      out that "strong typing is not dimensional analysis" in his article
>      "Why Pascal Is Not My Favorite Programming Language", when
>      enumerating deficiencies of that language.  Here's his example.
> 
>      type
>        apple = integer;
>        orange = integer;
> 
>      C works similarly.
> 
>      typedef int apple;
>      typedef int orange;
> 
>      Kernighan failed to note that strong typing _could_ be dimensional
>      analysis, if taken seriously.  Perhaps he didn't because the same
>      criticism could then be made of C, which had his name on it and
>      proceeded to eat much of Pascal's lunch in the '80s and '90s--for
>      reasons conspicuously distinct from the quality of its type
>      checking.
> 
>      If you want real checking of a primitive type in C, you have to wrap
>      it in a one-member struct.  Even then you don't get range
>      constraints, which are frequently valuable and which Pascal did
>      support.  Kernighan clucked in the same paper that range checks
>      "seemed like a service, though they too exact a run-time penalty".
>      In other words, they are costly.  I wonder how we might measure the
>      cost of failures to observe CERT'S INT{30,32}-C[3] in the quest for
>      bragging rights about performance.  Obviously its magnitude was
>      recognized only in retrospect.
> 
>      Now, lest I seem hard on Kernighan here, let me note that, among
>      other excellent points in the paper, his thorough trashing of
>      Pascal's array handling, where the size was regarded as an
>      integral part of the data type, was completely deserved.  For those
>      who haven't read the paper, this means that, yes, in pre-ISO Pascal,
>      your function which operated on char arrays of length 4 would not be
>      permitted to operate on char arrays of length 5.  The compiler (or
>      interpreter) would stop you.  It is hard for me to imagine, as a
>      workaday programmer, how Wirth let the language escape the
>      laboratory with this defect.

BTW, you can do something similar in C:

int foo(int (*foo)[3]);

int a[3], b[4];

foo(&a);
foo(&b);  // compiler error

Not that I see much usefulness in it, but it's curious.

> 
> [3] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152052


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: All caps .TH page title

[Ingo Schwarze]

Hi Alejandro,

On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:

> BTW, I think I didn't reply (or if I did was very short) to your comment 
> that other languages may find it difficult to mirror our use of 
> subsections, since their main section is already a subsection (e.g., 
> 3pl).

Other languages are usually better off to live *outside* the $MANPATH
and tell users to use "man -M" to access their documentation.
For example, on OpenBSD, the TCL manuals live
in /usr/local/lib/tcl/tcl8.5/man/ .
Putting them into /usr/local/man/ would be quite disruptive because
that would cause lots of clashes, including "apply", "break", "cd",
"close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open",
"puts", "pwd", "read", "socket", "time", and so on.  I expect most
other language will cause similar noise.
Perl is better because the clashing names are mostly part of perlfunc(1),
and the majority of other Perl manual page names contain colons.
FORTRAN (traditionally in man3f) is also better because in this
instance, the cryptic FORTAN six-letter identifiers become a virtue
in so far as they prevent clashes.

> I'd say that since C is the native Unix language, and others are 
> just... others?, I'd optimize for C, and let other languages find
> a way to document their things.

True - not because C is better or more worthy, but because looking up
an identifier logically requires specifying the language, and as
explained elsewhere, section suffixes are a poor solution for that.

> It would be easy to say just go away, the man pages are for C,

Absolutely not.  While the manual page format may have some feature
that are particularly well-suited to documenting C, it is not
limited to that role.

> but I won't dare to say that, since I like man pages, 
> and I'd like to see more documentation for languages that I sometimes 
> have to use be in the form of man pages, so I'll try to come up with a 
> more imaginative answer:  how about using subsubsections of the form 
> 3pl_type?  At least it's a possibility.  man(1) would handle them as any 
> other subsection, but that's not a big problem.  Maybe man(1) could 
> develop a way to provide subsubsections...  Colin, any ideas in this 
> regard?

See above.

Alejandro Colomar wrote on Fri, Jul 22, 2022 at 01:46:37PM +0200:

> Or, maybe it's the time to write a whole new volume?  I think there's a 
> comparable difference between 3type and 3 than between 2 and 3 or 1 and 
> 8, so it would be merited.  I didn't do it before for two reasons: it 
> might break software that assumes than Unix manuals use a single number 
> followed by an optional string (I'd say it's not a fair assumption to 
> say that man9 would be the last one ever used; if there's 9, there might 
> be a 10 some day), and because other projects had already used 3type.
> 
> But, that would start a clean namespace.  Maybe it's worth it.

No, that would absolutely not be clean design.  I advise strongly
against it.

First, concatening integer numbers and strings is often bad design
because it significantly complicates processing in various way.
For example, the traps set by the strtol(3) family of functions,
in particular regarding trailing non-digit characters, are
legendary.  Bugs love the breeding ground.  As another example,
numerical vs. alphabetical sorting is a similarly famous trap,
consider the difference of sort(1) vs. "sont -n".  I'm sure
you do *not* want to design a data type represented as a string
such that the first part needs to be sorted numerically and the
second part needs to be sorted alphanumerically - with not even
a delimiting character in between.

Less technically, having a small number of sections with non-desciptive
names is fine; people get used to the meaning of 1 to 9.  But when
you start adding more sections, a scheme with non-descriptive names
sooner or later becomes unsustainable.  "What was section 42 again...
i guess i'll have to look that up."

So the design already strikes me as terrible even before starting
to sonsider portability.
I would expect no end of compatibility problems.

 * Most man(1) implementations will probably treat section 10
   as a subsection of section 1.
 * While "man -s 10" may work with some man(1) implementations,
   "man 10 wchar_t" will fail saying
     man: No entry for 10 in the manual.
   on most.
 * When sorting, you will probably get 1, 10, 11, 2, 3, ...
 * I expect lots of code does
     char sc = '1' + sn - 1;
     asprintf(&fn, "%s.%c%s", name, sc, suffix);
   which leaves you with "name.:suffix" if sn == 10.
 * ...

> How would you feel if I inaugurate man10 for types, and later man11 for 
> non-function-like macros? :D

I wouldn't feel well at all.
I think i'd prefer contracting a common cold to having to deal with that.

Yours,
  Ingo

Re: All caps .TH page title

[Alejandro Colomar (man-pages)]

Hi Ingo,

On 7/23/22 21:29, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:
> 
>> BTW, I think I didn't reply (or if I did was very short) to your comment
>> that other languages may find it difficult to mirror our use of
>> subsections, since their main section is already a subsection (e.g.,
>> 3pl).
> 
> Other languages are usually better off to live *outside* the $MANPATH
> and tell users to use "man -M" to access their documentation.
> For example, on OpenBSD, the TCL manuals live
> in /usr/local/lib/tcl/tcl8.5/man/ .
> Putting them into /usr/local/man/ would be quite disruptive because
> that would cause lots of clashes, including "apply", "break", "cd",
> "close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open",
> "puts", "pwd", "read", "socket", "time", and so on.  I expect most
> other language will cause similar noise.
> Perl is better because the clashing names are mostly part of perlfunc(1),
> and the majority of other Perl manual page names contain colons.
> FORTRAN (traditionally in man3f) is also better because in this
> instance, the cryptic FORTAN six-letter identifiers become a virtue
> in so far as they prevent clashes.

I'm not happy with this approach.  I don't want to be typing paths for 
system stuff (your /usr/local is /usr in GNU/Linux systems; BTW, that's 
a thing I don't like at all from BSDs; IMO (and FHS's), /usr/local is 
for sysadmins to build from source; optional _packages_ should go to /opt).

If you want to search pages in section 3type, `man -s3type regex`. 
However, having some pages in subsections of 3, and others in the main 3 
section, is good for pages in subsections, but bad for pages in the main 
section (`man -s3 regex` would show all of the subsections' pages). 
That has a simple solution: move libc pages to man3c (and libm to man3m, 
...).  Since `man 3 printf` will continue working if this change is 
done, it doesn't seem to have backwards compatibility issues.

Also, you can put unimportant subsections at the end of the search list, 
to not hide other more important pages.

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: All caps .TH page title

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Sun, Jul 24, 2022 at 01:20:46PM +0200:
> On 7/23/22 21:29, Ingo Schwarze wrote:
>> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote:

>>> BTW, I think I didn't reply (or if I did was very short) to your comment
>>> that other languages may find it difficult to mirror our use of
>>> subsections, since their main section is already a subsection (e.g.,
>>> 3pl).

>> Other languages are usually better off to live *outside* the $MANPATH
>> and tell users to use "man -M" to access their documentation.
>> For example, on OpenBSD, the TCL manuals live
>> in /usr/local/lib/tcl/tcl8.5/man/ .
>> Putting them into /usr/local/man/ would be quite disruptive because
>> that would cause lots of clashes, including "apply", "break", "cd",
>> "close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open",
>> "puts", "pwd", "read", "socket", "time", and so on.  I expect most
>> other language will cause similar noise.
>> Perl is better because the clashing names are mostly part of perlfunc(1),
>> and the majority of other Perl manual page names contain colons.
>> FORTRAN (traditionally in man3f) is also better because in this
>> instance, the cryptic FORTAN six-letter identifiers become a virtue
>> in so far as they prevent clashes.

> I'm not happy with this approach.  I don't want to be typing paths for 
> system stuff (your /usr/local is /usr in GNU/Linux systems;

Then use an alias like

  alias tclman='man -M /usr/local/lib/tcl/tcl8.5/man/'

It's not like users are normally using dozens of different languages
at the same time, nor is the number of languages that provide a
collection of manual pages very significant.  So there isn't any
real-world problem that needs solving.

I even considered supporting aliases for manpath directories
in man.conf(5), something like being able to say

  alias tcl /usr/local/lib/tcl/tcl8.5/man/

in /etc/man.conf and then being able to say

  man -M tcl open

Disclaimer: the above is not a finished design, just a preliminary
idea.  But i'm very certain that -M or something derived from -M
is the tool for the job and -s or something derived from -s is not.
Because when you want a python manual page, you most definitely want
"Python only" and it serves no purpose whatsoever to search through
various trees and various sections, and least of all to badly design
a string-based composite data type like "number_language": that causes
all the ambiguity and confusion you are already discussing, and
it is error-prone and fragile in the parser on top of that.

Also, the concept of "for which language" and the concept of sections
are orthognal.  A programming langauge system usually provides
utility programs (1), library functions (3), file formats(5),
administration tools (8), and so on.

The reason i didn't pursue the man.conf(5) alias idea so far is that
the practical need for it is very limited.  No one ever asked me for
it as far as i recall, shell aliases do the job just fine.


> If you want to search pages in section 3type, `man -s3type regex`. 
> However, having some pages in subsections of 3, and others in the main 3 
> section, is good for pages in subsections, but bad for pages in the main 
> section (`man -s3 regex` would show all of the subsections' pages). 
> That has a simple solution: move libc pages to man3c (and libm to man3m, 
> ...).  Since `man 3 printf` will continue working if this change is 
> done, it doesn't seem to have backwards compatibility issues.

While the effect on the end user is indeed limited, you are proposing
a massive file system reshuffle here that seems somewhat in search of
a problem it wants to solve.  Yes, systems do exist that traditionally
use lots of section suffixes, so it *is* vital that man(1) implementations
support such suffixes.  But i claim that even in Solaris, those suffixes
serve little practical purpose and users are best off simply ignoring
them.

> Also, you can put unimportant subsections at the end of the search
> list, to not hide other more important pages.

In *BSD, support for changing the search list was deleted years ago.
That feature was an example of overengineering and useless complication.
I don't recall even one single complaint from a user who wanted the
feature back or explained what they were using it for.  Not one
person needing it in over half a decade since it was deleted...

Yours,
  Ingo


P.S.
I moved this to the bottom because it is off-topic:

> BTW, that's a thing I don't like at all from BSDs; IMO (and FHS's),

Years ago, i tried to engage with the FHS maintainers, arguing that
FHS is for Unux-like systems in general, and trying to contribute
aspects relevant for *BSD.  It was an uphill battle because the
FHS community was very firmly entrenched as "Linux only"; some
didn't even see a need to consider my comments at all, many
comments were rejected saying something like "this particular point
may be unusual on *BSD systems, but it is so important on Linux that
we cannot possibly allow the established *BSD convention for this
point in the FHS" even by those who were in principle willing to
view the FHS as a guideline for Unix-like systems in general.

On top of that, the group was almost dead, much less active than
for example the groff community, and even that is a very small group.
So ultimately, i gave up and left.  Other OpenBSD developers laughed
at me for even trying, essentially saying "Why do you even care
about that Linux-only crap?"  I still disagree and believe a
file system hierarchy standard for Unix-like systems could potentially
be useful.  Just consider that "Where are the URW fonts?"-saga
currently under way on this list as an example.

But dismissing decade-old *BSD standards like the use of /usr/
for the base system and /usr/local/ for packages as a standard
violation, and promoting /opt/ which is firmly a Linux-only
invention, is not going to help.

> /usr/local is for sysadmins to build from source;

Doing that is *very* strongly discouraged on OpenBSD.  If you only want
to try out some unported software, do not install it at all or install
it in your home directory.  If you are serious about providing something
system-wide, you are strongly expected to create a port, even if you do
not publish the port, so it can be properly installed, kept track of
by the package tools, controlled for collisions by the package
tools, and cleanly uninstalled when its time comes.

Creating a package is really simple.  Just a few days ago, senior
ports developers provided help to a user on our lists to do it
properly for company-internal software that will never be published,
and the thread was short because there wasn't that much to explain.

I did build RPMs for SLES at one point in the past when working
for a company, and i dimly remember looking at debian package build
documentation occasionally, and both seemed significantly harder
to both get started with and to master than BSD ports, so Linux
users may have a stronger motivation to just "make install".
Then again, there may also be a slight bias at work, what you are
used to always feels simpler than what you are less familiar with.

In any case, it is very intentional that OpenBSD does *not* provide
a directory to users that they can "make install" to.

> optional _packages_ should go to /opt).

Not even Debian adheres to that.  When i install an additional,
optional package, i.e. one that Debian did not install by default when
the system was originally installed, most of the time, that optional
package goes to /usr/, not to /opt/.

Re: All caps .TH page title

[G. Branden Robinson]

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

At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote:
> But dismissing decade-old *BSD standards like the use of /usr/ for the
> base system and /usr/local/ for packages as a standard violation, and
> promoting /opt/ which is firmly a Linux-only invention,

Oh, no it's not.  I remember that thing from Solaris 2.3 or 2.4.  Here's
a slightly later source.

https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html

Your complaints about the Linux-centricity of the FHS can be explained
largely by QuaNGO corporate politics.[1]  The first Linux file system
organization standard was called FSSTND and dates back to about 1994.
But it had little or no organizational support or funding behind it.
(It is hard to overstate how much Linux seemed like an underdog in those
days.)

You can read some further history at the usual reliable(?) source.

https://en.wikipedia.org/wiki/Free_Standards_Group

Since the FHS is fully under the purview of the Linux Foundation (LF), I
don't think it's reasonable to expect any responses much different than
what you describe.  The LF exists to "promote Linux", which, as with any
NGO with an open-ended mission, in practice means to sustain itself
indefinitely via membership fees.  (In the parlance of journalism, one
can reliably correlate the "seriousness" of any NGO with the level of
compensation enjoyed by its officers.)  The benefits of membership are
significant; you can utterly disregard the terms of the GNU GPL.  If you
are not a member and have transgressed, the Foundation will happily sell
you an indulgence in the form of membership.

Under this umbrella, the Linux kernel is effectively under the BSD
license.  Don't be shocked if even the disclosure of relevant copyright
and license notices is a negotiable point.  This is business.  Under
litigation you'd end up in much the same place, potentially with much
more bad press.  Monetary damages are the fuel that sustains the engine
of civil procedure.  Compliance and specific performance are distant
concerns.

Litigation to enforce the terms of the GPL is stridently characterized
as discouraging and unproductive--we never ask "to whom?" or "of
what?"--except insofar as it drives firms to the reassuring shelter of
Foundation membership.  You can see how it is helpful to characterize
independent GPL plaintiffs as cranks and lunatics--moreover, you do LF a
huge favor if, as such a plaintiff, you actually are a lunatic.

This model is widely regarded as successful; indeed, when limiting your
interviews to members of a cartel, reported levels of satisfaction with
the organization are characteristically high.  It dissolves otherwise.

So guess what?  The BSD camp did ultimately win the copyleft argument
after all.

Regards,
Branden

[1] Some would doubtless argue with the "qua" here.  I remind the reader
    that copyrights are legal monopolies dispensed by the state.
    Copyright enforcement in the United States, for instance, was a
    _wholly_ civil matter until 1897, having spent over a century as a
    government-created tort.

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

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4327 bytes --]

Hi Ingo,

On 7/24/22 16:57, Ingo Schwarze wrote:
[...]
>> I'm not happy with this approach.  I don't want to be typing paths for
>> system stuff (your /usr/local is /usr in GNU/Linux systems;
> 
> Then use an alias like
> 
>    alias tclman='man -M /usr/local/lib/tcl/tcl8.5/man/'
> 
> It's not like users are normally using dozens of different languages
> at the same time, nor is the number of languages that provide a
> collection of manual pages very significant.  So there isn't any
> real-world problem that needs solving.
> 
> I even considered supporting aliases for manpath directories
> in man.conf(5), something like being able to say
> 
>    alias tcl /usr/local/lib/tcl/tcl8.5/man/
> 
> in /etc/man.conf and then being able to say
> 
>    man -M tcl open

Now we're talking.  I've long missed such a thing.
Let's please discuss it.

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>?

Would your -M require that the pages live in a separate path?  Or could 
it support subpaths?

> 
> Disclaimer: the above is not a finished design, just a preliminary
> idea.  But i'm very certain that -M or something derived from -M
> is the tool for the job and -s or something derived from -s is not.
> Because when you want a python manual page, you most definitely want
> "Python only" and it serves no purpose whatsoever to search through
> various trees and various sections, and least of all to badly design
> a string-based composite data type like "number_language": that causes
> all the ambiguity and confusion you are already discussing, and
> it is error-prone and fragile in the parser on top of that.
> 
> Also, the concept of "for which language" and the concept of sections
> are orthognal.  A programming langauge system usually provides
> utility programs (1), library functions (3), file formats(5),
> administration tools (8), and so on.

Agree.

> 
> The reason i didn't pursue the man.conf(5) alias idea so far is that
> the practical need for it is very limited.  No one ever asked me for
> it as far as i recall, shell aliases do the job just fine. >
> 
>> If you want to search pages in section 3type, `man -s3type regex`.
>> However, having some pages in subsections of 3, and others in the main 3
>> section, is good for pages in subsections, but bad for pages in the main
>> section (`man -s3 regex` would show all of the subsections' pages).
>> That has a simple solution: move libc pages to man3c (and libm to man3m,
>> ...).  Since `man 3 printf` will continue working if this change is
>> done, it doesn't seem to have backwards compatibility issues.
> 
> While the effect on the end user is indeed limited, you are proposing
> a massive file system reshuffle here that seems somewhat in search of
> a problem it wants to solve.  Yes, systems do exist that traditionally
> use lots of section suffixes, so it *is* vital that man(1) implementations
> support such suffixes.  But i claim that even in Solaris, those suffixes
> serve little practical purpose and users are best off simply ignoring
> them.

I do want to document types (even if I had to document them in function 
pages, I'd add link pages with the name of the type, for reasons already 
stated in several other threads).

Types are better documented standalone, IMO, also for reasons I detailed 
in several other threads.

And, as also discussed in several threads, having type pages in man3 is 
problematic (collisions, ambiguity (does foo(3) refer to a function or a 
type? foo(3type) does certainly refer to a type; and foo(3[c]) should 
certainly refer to a function).



> 
>> Also, you can put unimportant subsections at the end of the search
>> list, to not hide other more important pages.
> 
> In *BSD, support for changing the search list was deleted years ago.
> That feature was an example of overengineering and useless complication.
> I don't recall even one single complaint from a user who wanted the
> feature back or explained what they were using it for.  Not one
> person needing it in over half a decade since it was deleted...

Okay.


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

FHS and packaging (was: All caps .TH page title)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 7995 bytes --]

Hi Ingo and Branden!

On 7/24/22 16:57, Ingo Schwarze wrote:
 > P.S.
 > I moved this to the bottom because it is off-topic:
 >
 > Alejandro Colomar wrote on Sun, Jul 24, 2022 at 01:20:46PM +0200:
 >> BTW, that's a thing I don't like at all from BSDs; IMO (and FHS's),
 >
 > Years ago, i tried to engage with the FHS maintainers, arguing that
 > FHS is for Unux-like systems in general, and trying to contribute
 > aspects relevant for *BSD.  It was an uphill battle because the
 > FHS community was very firmly entrenched as "Linux only"; some
 > didn't even see a need to consider my comments at all, many
 > comments were rejected saying something like "this particular point
 > may be unusual on *BSD systems, but it is so important on Linux that
 > we cannot possibly allow the established *BSD convention for this
 > point in the FHS" even by those who were in principle willing to
 > view the FHS as a guideline for Unix-like systems in general.
 >
 > On top of that, the group was almost dead, much less active than
 > for example the groff community, and even that is a very small group.
 > So ultimately, i gave up and left.  Other OpenBSD developers laughed
 > at me for even trying, essentially saying "Why do you even care
 > about that Linux-only crap?"  I still disagree and believe a
 > file system hierarchy standard for Unix-like systems could potentially
 > be useful.  Just consider that "Where are the URW fonts?"-saga
 > currently under way on this list as an example.

That you very much for your attempts to make the FHS be a real Unix 
standard.  It's sad to read this.

 >
 > But dismissing decade-old *BSD standards like the use of /usr/
 > for the base system and /usr/local/ for packages as a standard
 > violation, and promoting /opt/ which is firmly a Linux-only
 > invention, is not going to help.

As Branden noted, this wasn't a Linux thing (I don't have the background 
he has, but I researched a lot about this, and found something like that).

 >
 >> /usr/local is for sysadmins to build from source;
 >
 > Doing that is *very* strongly discouraged on OpenBSD.

I guess that's why the directory was reused in the BSDs to install ports 
(probably ports were installed by the sysadmin there, and by extension, 
ports are now always installed there, but that's just a guess).

 >  If you only want
 > to try out some unported software, do not install it at all or install
 > it in your home directory.  If you are serious about providing something
 > system-wide, you are strongly expected to create a port, even if you do
 > not publish the port, so it can be properly installed, kept track of
 > by the package tools, controlled for collisions by the package
 > tools, and cleanly uninstalled when its time comes.

My use case is the following:

As a programmer, I want to provide a reliable and useful Makefile (I 
know that's a rare thing to do, but I like to debug and optimize my 
Makefiles, both for performance and user experience, as we've already 
discussed).

So, packagers/users should be able to pick a project of mine, and trust 
the Makefile to produce a good installation, even in parallel (as good 
as a Makefile can do, that is).


I also want to test that my programs, when installed in the system, 
behave as expected, and that's one of the reasons I debug my programs by 
installing them, and running as a normal user would run them.  Running 
in ~/bin is not the exact same thing as the system, and may not uncover 
some bugs.

So, I run `make install` several times a minute sometimes when 
programming (or when writing manual pages).

It also has the extra benefit that all of the paths are already 
configured by default, so I can omit paths (or skip configuring my 
user's PATH to include things like ~/bin and MANPATH to include 
~/share/man).

 >
 > Creating a package is really simple.  Just a few days ago, senior
 > ports developers provided help to a user on our lists to do it
 > properly for company-internal software that will never be published,
 > and the thread was short because there wasn't that much to explain.

I don't know how easy it is to create a port.

 >
 > I did build RPMs for SLES at one point in the past when working
 > for a company, and i dimly remember looking at debian package build
 > documentation occasionally, and both seemed significantly harder
 > to both get started with and to master than BSD ports, so Linux
 > users may have a stronger motivation to just "make install".
 > Then again, there may also be a slight bias at work, what you are
 > used to always feels simpler than what you are less familiar with.

But certainly, Linux packages are _hard_.  I tried packaging for debian 
several projects of mine, and I always gave up.  I have a list of things 
to read/watch for my next attempt, but I'm very lazy about it, since 
none of my previous attempts were good enough for my taste.

 >
 > In any case, it is very intentional that OpenBSD does *not* provide
 > a directory to users that they can "make install" to.
 >

That's sad, but more sad is that BSDs took an existing path (/usr/local) 
to a different purpose.  I had a discussion in NGINX Unit about it, and 
the decission for now has been: "support prefix=/usr/local for default 
manual installation through the Makefile, and let BSD users adjust to 
their preferred path".  We were concerned that we might get collisions 
with the BSD port also installing in /usr/local, but that's the least 
evil (and considering BSD users don't typically run `make install`, it's 
not so bad).

 >> optional _packages_ should go to /opt).
 >
 > Not even Debian adheres to that.  When i install an additional,
 > optional package, i.e. one that Debian did not install by default when
 > the system was originally installed, most of the time, that optional
 > package goes to /usr/, not to /opt/.

Yeah.  Since the line between optional and non-optional software is not 
so clear, some people have considered optional packages to be those that 
you install manually (i.e., .deb packages downloaded manually).  So /opt 
has become the /usr/local of .deb packages.


On 7/24/22 17:44, G. Branden Robinson wrote:
> At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote:
>> But dismissing decade-old *BSD standards like the use of /usr/ for the
>> base system and /usr/local/ for packages as a standard violation, and
>> promoting /opt/ which is firmly a Linux-only invention,
> 
> Oh, no it's not.  I remember that thing from Solaris 2.3 or 2.4.  Here's
> a slightly later source.
> 
> https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html
> [Branden's long rant about corporations, and NGOs]

I agree with the rant.


BTW, I have a longstanding issue with Debian packages.  Branden, your 
experience with Debian might help, if you find some time.

The thing is: I'd like to provide an official Debian package of the 
man-pages.  There are several reasons for that:

- Be able to use the full power of dpkg(1) to manage the installed files 
(`make install` is quite weak there).

- Show users a good example of how to package their small programs, with 
the minimal stuff (but I aim to do it of very high quality).

- Make it easier for users to install the pages directly from upstream, 
especially now that we haven't released in a year.  (They can already 
`make install`, but that's not perfect, since they likely want dpkg(1) 
to manage the files.  I know there are tools to autogenerate a package 
while installing with `make install`, but the quality of such packages 
is not something that I like.)

- I only want to provide a .deb, for reasons related to your rant.


So I'd like to provide a `make pkg-deb` target to create the package. 
Would you mind helping me do that?


Cheers,

Alex


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Sun, Jul 24, 2022 at 06:17:40PM +0200:
> On 7/24/22 16:57, Ingo Schwarze wrote:

>> I even considered supporting aliases for manpath directories
>> in man.conf(5), something like being able to say
>> 
>>    alias tcl /usr/local/lib/tcl/tcl8.5/man/
>> 
>> in /etc/man.conf and then being able to say
>> 
>>    man -M tcl open

> Now we're talking.  I've long missed such a thing.
> Let's please discuss it.

Well, it wouldn't be the first time i implemented a feature in mandoc
that is not very urgently needed on OpenBSD but where the main need
came from Linux (or Illumos or MacOS, for that matter).

If it doesn't cause disruption or excessive complexity,
which seems unlikely in this case, we can consider it.

Do you think this would really get used in practice?

If so, as a motivation, it would be useful to collect a handful
of languages that would use this.  So far, i'm mostly aware of
Tcl and Tk.  And of the POSIX manual pages.

Of course i can't speak for man-db and other man(1) implementations.
Then again, even if other man(1) implementations would not follow,
maybe having -M aliases might be useful even in a single implementation.
Users of the others could still use shell aliases.

One side effect useful for myself would be that i could do, in man.conf(5),

  alias B /usr/share/man
  alias P /usr/local/man
  alias X /usr/X11R6/man

and then say

  man -kMB sha256

when i only want to base system pages and be undisturbed by ports
pages - right now, i type "-M /usr/share/man" relatively often.

Or say

  man -MP:B

to play with precedence.

> 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

So, lets assume i'm on a amd64 machine and want to learn how
logical domains (a virtualization feature implemented in
SPARC hardware) are configured:

   $ arch
  OpenBSD.amd64
   $ man ldom.conf
  man: No entry for ldom.conf in the manual.
   $ man -S sparc64 ldom.conf
  [...]
  NAME
     ldom.conf  Logical Domain configuration
  [...]

Note that i said -S there, not -s nor -M.

So i advise against doing that for python: the namespace is already
taken for a different purpose.

Using /usr/share/man/python/man3/foo.3 would be similarly bad,
that usually means:

  The translation of /usr/share/man/man3/foo.3
  into the natural language "python".

Typical examples on OpenBSD:

  /usr/local/man/ja/man1/w3m.1
  /usr/local/man/pt_BR/man6/wesnoth.6
  /usr/local/man/de/man1/dvipdf.1

> Would your -M require that the pages live in a separate path?
> Or could it support subpaths?

The directory -M points to needs to contain the usual man1/ man3/
man5/ etc. subdirectories.  Where exactly you put that doesn't
matter for man(1), but i strongly advise against putting it into
/usr/share/man because all the namespace in there is already
taken for other purposes, and putting it in there anyway is likely
to confuse tools like makewhatis(8), mandb(8), catman(8),
and apropos(1).

If a language is so large that it comes with a whole suite of manual
pages (as ooposed to a language like awk(1) small enough to be
documented in a single page), then that language is likely to
already have its own directory for data files, typically somewhere
below /usr/share/.  Maybe it even has its own directory below
/usr/share/doc/ already.  For example, /usr/share/doc/python
already exists on Debian, so /usr/share/doc/python/man/man[1-5]/...
might one be reasoable choice, albeit certainly not the only option.

Yours,
  Ingo

Re: All caps .TH page title

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Jul 24, 2022 at 10:44:47AM -0500:
> At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote:

>> But dismissing decade-old *BSD standards like the use of /usr/ for the
>> base system and /usr/local/ for packages as a standard violation, and
>> promoting /opt/ which is firmly a Linux-only invention,

> Oh, no it's not.  I remember that thing from Solaris 2.3 or 2.4.
> Here's a slightly later source.
> 
> https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html

Oops, thanks for setting me right.

Confirmed:

   > uname -a
  SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise
   > ls -al /opt
  total 2613
  drwxr-xr-x 12 root other      13 Dec 31 2020 .
  drwxr-xr-x 19 root root       22 Aug 17 2018 ..
  drwxr-xr-x  4 root other       4 Feb 10 2015 bop
  drwxr-xr-x 25 root bin        29 Dec  1 2017 csw
  drwxr-xr-x 10 root sys        11 Aug 17 2018 developerstudio12.5
  drwxr-xr-x 10 root sys        11 Aug 17 2018 developerstudio12.6
  drwxr-xr-x  3 root root        3 Feb 10 2015 local
  drwxr-xr-x 12 root sys        12 Jan 22 2015 solarisstudio12.3
  drwxr-xr-x 10 root sys        11 Dec 22 2015 solarisstudio12.4
  drwxr-xr-x 13 root sys        13 Jan 22 2015 solstudio12.2
  drwxr-xr-x 13 root sys        15 Oct 29 2015 SUNWspro
  -rw-------  1 root root  1311633 Oct 29 2015 uninstall_Sun_Studio_12.class
  drwxr-xr-x  3 root root        3 Feb 18 2015 VRTS

It doesn't look as if modern Oracle Solaris uses it very extensively,
but still, it does exist.

[...]
> Under this umbrella, the Linux kernel is effectively under the BSD
> license.

Except that free software projects cannot copy from it - that's
quite a big BUT since allowing *everybody* to copy the code for
any purpose is the central idea of the BSD license.  ;-)

[...]
> The BSD camp did ultimately win the copyleft argument after all.

I'm not so sure about that.  The idea of the BSD license is to
allow all uses that can be licensed to others according to the Berne
Convention, retaining only those rights - essentially the moral rights,
like being known as the author, and abuse of the Works for slandering
the author being prohibited - that are inalienable in the first place
according to the Berne Convention.

Even if in effect, the Copyleft aspect of the GPL is not usually
enforced against Foundation members, GPL code is far from as free
as the Berne Convention would permit it to be, and far from as free
as if it were under a BSD license.

So essentially, you say that in practice, the GPL fails to attain
the goals RMS designed it for, and i say that all the same, it has
some serious and (hopefully) unintended detrimental side effects.

I can't say i'm too happy with that.
I certainly don't regard it as a win.
It looks more like a lose-lose situation to me.

But i don't think we can do much about that.  Groff is still
usable for most users without too much pain.  Unless i want to
contribute significant amounts of code, even i could do so.
And to be fair, even if i wanted to contribute large amounts of
code, the GPL would *not* prevent me from doing that - the thing
the would stop me is the FSF CLA, which is an entirely different
beast.

Nuff' digression!
  Ingo

man0, man3head (was: All caps .TH page title)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4152 bytes --]

[dropped groff@; irrelevant to them]

Hi Branden,

On 7/27/22 18:05, Ingo Schwarze wrote:
> Hi Branden,
> 
> G. Branden Robinson wrote on Sun, Jul 24, 2022 at 10:44:47AM -0500:
>> At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote:
> 
>>> But dismissing decade-old *BSD standards like the use of /usr/ for the
>>> base system and /usr/local/ for packages as a standard violation, and
>>> promoting /opt/ which is firmly a Linux-only invention,
> 
>> Oh, no it's not.  I remember that thing from Solaris 2.3 or 2.4.
>> Here's a slightly later source.
>>
>> https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html
> 
> Oops, thanks for setting me right.
> 
> Confirmed:
> 
>     > uname -a
>    SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise
>     > ls -al /opt
>    total 2613
>    drwxr-xr-x 12 root other      13 Dec 31 2020 .
>    drwxr-xr-x 19 root root       22 Aug 17 2018 ..
>    drwxr-xr-x  4 root other       4 Feb 10 2015 bop
>    drwxr-xr-x 25 root bin        29 Dec  1 2017 csw
>    drwxr-xr-x 10 root sys        11 Aug 17 2018 developerstudio12.5
>    drwxr-xr-x 10 root sys        11 Aug 17 2018 developerstudio12.6
>    drwxr-xr-x  3 root root        3 Feb 10 2015 local
>    drwxr-xr-x 12 root sys        12 Jan 22 2015 solarisstudio12.3
>    drwxr-xr-x 10 root sys        11 Dec 22 2015 solarisstudio12.4
>    drwxr-xr-x 13 root sys        13 Jan 22 2015 solstudio12.2
>    drwxr-xr-x 13 root sys        15 Oct 29 2015 SUNWspro
>    -rw-------  1 root root  1311633 Oct 29 2015 uninstall_Sun_Studio_12.class
>    drwxr-xr-x  3 root root        3 Feb 18 2015 VRTS
> 
> It doesn't look as if modern Oracle Solaris uses it very extensively,
> but still, it does exist.

BTW, Branden, you asked why would I use section 0 for header files 
(although since the lists have been very hot these days, I won't care 
finding the exact email).

I didn't inaugurate section 0 for that.  I just followed existing 
practice.  But, considering our discussions about the topic, and 
considering that I already changed CONFORMING TO to STANDARDS for 
consistency across all manual pages in existence, I'll reconsider.

So, existing practice seems to be divided in:

- Putting header files' pages directly in man3 (e.g., string(3)).
   Done by Linux man-pages, and BSDs (see BSD's sysexits(3)).
   I don't like the idea, especially if the page name doesn't have a
   trailing '.h', since they live in different namespaces.

- Putting them in man3head.
   Done by some Oracle OSes (at least for some versions).

- Putting them in man0.
   Done exclusively by the posix man pages.
   Not even something POSIX is responsible for, AFAIK,
   since we create the pages from the HTML source,
   which has noting to do with sections.
   Debian for example, changes this (see below).
   It seems to be the only place man0 is being used,
   and I have control over it.

- Putting them in man7.
   Debian moves man0 pages to 7POSIX (but uses man7/).


Since there's much division, and I have complete control over one (or 
even two if I can avoid Debian moving the pages to man7) of the 
variants, I could help unify header files manual pages across Unix 
systems by moving POSIX header file manual pages to man3head.

I would also move the only page in the Linux man pages that is in man0 
(added recently by me; sysexits.h(0)) and the man3 header pages from the 
Linux man-pages (such as string(3)) to man3head.

Maybe Debian also gives up modifying upstream pages, since I'll make it 
really hard for them to "fix" man3type anyway (not on purpose, but 
they'll need to come up with a script to modify the link pages).

That would leave us with the following situation:

- Most header file pages would be in man3head (Oracle, POSIX, Linux).

- BSDs still have a few (maybe only one?) header page in man3: sysexits(3).

- Section 0 becomes desert, and maybe someone can give it a new use in 
the future, if a new section is ever need.

Much nicer than before.


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

BSD and GPL (was: All caps .TH page title)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2863 bytes --]

Hi Ingo and Branden,

On 7/27/22 18:05, Ingo Schwarze wrote:
> [...]
>> Under this umbrella, the Linux kernel is effectively under the BSD
>> license.
> 
> Except that free software projects cannot copy from it - that's
> quite a big BUT since allowing *everybody* to copy the code for
> any purpose is the central idea of the BSD license.  ;-)
> 
> [...]
>> The BSD camp did ultimately win the copyleft argument after all.
> 
> I'm not so sure about that.  The idea of the BSD license is to
> allow all uses that can be licensed to others according to the Berne
> Convention, retaining only those rights - essentially the moral rights,
> like being known as the author, and abuse of the Works for slandering
> the author being prohibited - that are inalienable in the first place
> according to the Berne Convention.
> 
> Even if in effect, the Copyleft aspect of the GPL is not usually
> enforced against Foundation members, GPL code is far from as free
> as the Berne Convention would permit it to be, and far from as free
> as if it were under a BSD license.
> 
> So essentially, you say that in practice, the GPL fails to attain
> the goals RMS designed it for, and i say that all the same, it has
> some serious and (hopefully) unintended detrimental side effects.
> 
> I can't say i'm too happy with that.
> I certainly don't regard it as a win.
> It looks more like a lose-lose situation to me.
> 
> But i don't think we can do much about that.  Groff is still
> usable for most users without too much pain.  Unless i want to
> contribute significant amounts of code, even i could do so.
> And to be fair, even if i wanted to contribute large amounts of
> code, the GPL would *not* prevent me from doing that - the thing
> the would stop me is the FSF CLA, which is an entirely different
> beast.

Yes, essentially, the kernel is BSD-licensed to big corporations paying 
to the FSF, but GPL to free software programmers.

BSDs are BSD for everyone.

I'm still using GPL for my own things, but I'm not happy at all with 
this situation, and considered several times giving up and using BSD 
licenses.  I still don't, because I'm not accepting the lose-lose situation.

But at the same time, I'd like to make a note here that the intention 
matters more than the license to me, and my intention is that my code 
can be useful to other open-source programmers.  So, if anyone needs to 
use code of mine in other open-source code, don't be intimidated by the 
license, and you can always ask me for an exception to the license.  The 
end goal is that open-source code improves.

Non-open-source is still strictly limited to GPL regarding my own code. 
The paragraph above is not an invitation to break GPL in my code.

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 6474 bytes --]

Hi Ingo,

On 7/27/22 17:32, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Sun, Jul 24, 2022 at 06:17:40PM +0200:
>> On 7/24/22 16:57, Ingo Schwarze wrote:
> 
>>> I even considered supporting aliases for manpath directories
>>> in man.conf(5), something like being able to say
>>>
>>>     alias tcl /usr/local/lib/tcl/tcl8.5/man/
>>>
>>> in /etc/man.conf and then being able to say
>>>
>>>     man -M tcl open
> 
>> Now we're talking.  I've long missed such a thing.
>> Let's please discuss it.
> 
> Well, it wouldn't be the first time i implemented a feature in mandoc
> that is not very urgently needed on OpenBSD but where the main need
> came from Linux (or Illumos or MacOS, for that matter).
> 
> If it doesn't cause disruption or excessive complexity,
> which seems unlikely in this case, we can consider it.
> 
> Do you think this would really get used in practice?

I don't know.  I haven't received any such feature requests from users.

But I've many times had the feeling that the man hierarchy is so flat 
and is so overpopulated (as soon as you start installing some packages; 
especially those that document their API in man3) that it's hard to find 
what you want.  That's one of the reasons that I think man3type, 
man3const are better outside of man3.

> 
> If so, as a motivation, it would be useful to collect a handful
> of languages that would use this.  So far, i'm mostly aware of
> Tcl and Tk.  And of the POSIX manual pages.

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?

> 
> Of course i can't speak for man-db and other man(1) implementations.
> Then again, even if other man(1) implementations would not follow,
> maybe having -M aliases might be useful even in a single implementation.
> Users of the others could still use shell aliases.

Yep.  I don't think that should be a problem.

> 
> One side effect useful for myself would be that i could do, in man.conf(5),
> 
>    alias B /usr/share/man
>    alias P /usr/local/man
>    alias X /usr/X11R6/man
> 
> and then say
> 
>    man -kMB sha256
> 
> when i only want to base system pages and be undisturbed by ports
> pages - right now, i type "-M /usr/share/man" relatively often.

Yes, I also often want to compare the differences between the last 
release of the man-pages, and the page that I'm modifying, and that 
would be simpler with such a feature.

> 
> Or say
> 
>    man -MP:B
> 
> to play with precedence.
> 
>> 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
> 
> So, lets assume i'm on a amd64 machine and want to learn how
> logical domains (a virtualization feature implemented in
> SPARC hardware) are configured:
> 
>     $ arch
>    OpenBSD.amd64
>     $ man ldom.conf
>    man: No entry for ldom.conf in the manual.
>     $ man -S sparc64 ldom.conf
>    [...]
>    NAME
>       ldom.conf  Logical Domain configuration
>    [...]
> 
> Note that i said -S there, not -s nor -M.
> 
> So i advise against doing that for python: the namespace is already
> taken for a different purpose.

Yeah, idea discarded.

> 
> Using /usr/share/man/python/man3/foo.3 would be similarly bad,
> that usually means:
> 
>    The translation of /usr/share/man/man3/foo.3
>    into the natural language "python".
> 
> Typical examples on OpenBSD:
> 
>    /usr/local/man/ja/man1/w3m.1
>    /usr/local/man/pt_BR/man6/wesnoth.6
>    /usr/local/man/de/man1/dvipdf.1

Makes, sense; also discarded.

> 
>> Would your -M require that the pages live in a separate path?
>> Or could it support subpaths?
> 
> The directory -M points to needs to contain the usual man1/ man3/
> man5/ etc. subdirectories.  Where exactly you put that doesn't
> matter for man(1), but i strongly advise against putting it into
> /usr/share/man because all the namespace in there is already
> taken for other purposes, and putting it in there anyway is likely
> to confuse tools like makewhatis(8), mandb(8), catman(8),
> and apropos(1).
> 
> If a language is so large that it comes with a whole suite of manual
> pages (as ooposed to a language like awk(1) small enough to be
> documented in a single page), then that language is likely to
> already have its own directory for data files, typically somewhere
> below /usr/share/.  Maybe it even has its own directory below
> /usr/share/doc/ already.  For example, /usr/share/doc/python
> already exists on Debian, so /usr/share/doc/python/man/man[1-5]/...
> might one be reasoable choice, albeit certainly not the only option.

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?

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?

Cheers,

Alex


[1]: <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html>
[2]: <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man0, man3head (was: All caps .TH page title)

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Fri, Jul 29, 2022 at 01:33:12PM +0200:

> BTW, Branden, you asked why would I use section 0 for header files 
> (although since the lists have been very hot these days, I won't care 
> finding the exact email).
> 
> I didn't inaugurate section 0 for that.
> I just followed existing practice.

I just looked at my forest (i.e., my collection of trees).

Version 3 AT&T UNIX contains these files in man/man0/:

 * a macro file "aa" setting adjustment mode, indentation,
   and something for page breaks and header or footer lines
 * a file "basinf", kind of a quick start guide for UNIX,
   mostly about logging in and out, but also containing
   some remarks about programming and text processing
 * a sed script "headrc", rather cryptic
 * the famous permuted "index" file that used to be printed
   together with the UNIX manuals
 * a file "intro" containing the title page, preface,
   and introduction for the manuals
 * a file "toc" containing the table of contents of the manuals,
   in the typical section-then-alphabetic order
 * an ed script "tocrc", rather cryptic
 * a file "xx", obviously intended as a template for writing
   a new manual page

The following systems use man/man0 for similar purposes:

 * v4, v6, PWB, v7, 32v, v8, v10, System III
 * 3BSD, 4.0BSD, 4.1BSD, 4.2BSD, 4.3BSD-Tahoe, 4.3BSD-Reno
 * 4.4BSD, 4.4BSD-Lite1, 4.4BSD-Lite2, NetBSD

The exact content varies, but it's always used for auxiliary files
like macros files, scripts, tools, and front matter.
Usage of man/man0 is especially extensive in v10, which
contains several man/man0 directories in various places
with several dozen files contained in them.

> But, considering our discussions about the topic, and 
> considering that I already changed CONFORMING TO to STANDARDS for 
> consistency across all manual pages in existence, I'll reconsider.
> 
> So, existing practice seems to be divided in:
> 
> - Putting header files' pages directly in man3 (e.g., string(3)).

That practice is deprecated in OpenBSD:

   $ uname -a
  OpenBSD isnote.usta.de 7.1 GENERIC.MP#613 amd64
   $ man string
  man: No entry for string in the manual.

The way to get this information looks like this now:

   $ man -k In=string.h
  bit_alloc, bit_clear, bit_decl, bit_ffc, bit_ffs, bit_nclear, bit_nset,
    bit_set, bit_test, bitstr_size(3) - bit-string manipulation macros
  bzero, explicit_bzero(3) - write zeroes to a byte string
  memccpy(3) - copy string until character found
  memchr, memrchr(3) - locate byte in byte string
  memcmp(3) - compare byte string
  memcpy(3) - copy bytes
  memmem(3) - locate a byte substring in a byte string
  memmove(3) - copy bytes
  memset(3) - write a byte to byte string
  stpcpy, stpncpy(3) - copy strings
  strcat(3) - concatenate two strings without bounds checking
  strchr, index(3) - locate first occurrence of a character in a string
  strcmp, strncmp(3) - compare strings
  strcoll, strcoll_l(3) - compare strings according to current collation
  strcpy(3) - copy a string without bounds checking
  strcspn(3) - span the complement of a string
  strdup, strndup(3) - save a copy of a string
  strerror, strerror_l, strerror_r(3) - get error message string
  strlcpy, strlcat(3) - size-bounded string copying and concatenation
  strlen, strnlen(3) - find length of a string
  strmode(3) - convert inode status information into a symbolic string
  strncat(3) - concatenate a string with part of another
  strncpy(3) - copy part of a string to another
  strpbrk(3) - locate multiple characters in string
  strrchr, rindex(3) - locate last occurrence of a character in a string
  strsep(3) - separate strings
  strsignal(3) - get signal description string
  strspn(3) - span a string
  strstr, strcasestr(3) - locate a substring in a string
  strtok, strtok_r(3) - string token operations
  strxfrm, strxfrm_l(3) - transform a string under locale
  timingsafe_bcmp, timingsafe_memcmp(3) - timing-safe byte sequence comparisons
  audio, audioctl(4) - device-independent audio driver layer

The reason for deprecating pages with names of the form "header_name(3)"
is less that we don't want non-function-name pages in section 3 and more
that we don't want manual pages for header files.

I don't think FreeBSD and NetBSD deprecated such pages though;
i still see lib/libc/string/string.3 in FreeBSD and NetBSD.

>    Done by Linux man-pages, and BSDs (see BSD's sysexits(3)).

OpenBSD deprecated sysexits(3) - the whole feature, not only the
name of the manual page.  The DESCRIPTION in our page starts as
follows:

     A few programs exit with the following non-portable error codes.
     Do not use them.

While i highly respect Eric Allman, IMHO inventing "sysexits"
was a bad idea.

>    I don't like the idea, especially if the page name doesn't have a
>    trailing '.h', since they live in different namespaces.
> 
> - Putting them in man3head.
>    Done by some Oracle OSes (at least for some versions).

Sounds like the least bad solution to me.

> - Putting them in man0.
>    Done exclusively by the posix man pages.
>    Not even something POSIX is responsible for, AFAIK,
>    since we create the pages from the HTML source,
>    which has noting to do with sections.
>    Debian for example, changes this (see below).
>    It seems to be the only place man0 is being used,
>    and I have control over it.

As explained above, man/man0 has traditionally been used for
something else.  The traditional use has lost much of its
importance during the last two decades and right now, it doesn't
seem likely to me that it might need to be revived, but still,
not clashing with it seems better if it can be avoided.

> - Putting them in man7.
>    Debian moves man0 pages to 7POSIX (but uses man7/).

I don't like that.  The "Miscellaneous Information Manual" (section 7)
is mostly intended to be user-facing pages like editline(7),
environ(7), glob(7), hier(7), man(7), packages(7), ports(7),
re_format(7), symlink(7), utf8(7).  Pages that are only interesting
for programmers are less welcome in section 7, even though a few
exceptions exist, for example operator(7).
Manual pages for C header files clearly need to be part of
the "Library Functions Manual" (section 3).

> Since there's much division, and I have complete control over one (or 
> even two if I can avoid Debian moving the pages to man7) of the 
> variants, I could help unify header files manual pages across Unix 
> systems by moving POSIX header file manual pages to man3head.
> 
> I would also move the only page in the Linux man pages that is in man0 
> (added recently by me; sysexits.h(0)) and the man3 header pages from the 
> Linux man-pages (such as string(3)) to man3head.
> 
> Maybe Debian also gives up modifying upstream pages, since I'll make it 
> really hard for them to "fix" man3type anyway (not on purpose, but 
> they'll need to come up with a script to modify the link pages).
> 
> That would leave us with the following situation:
> 
> - Most header file pages would be in man3head (Oracle, POSIX, Linux).

That all makes sense to me.

> - BSDs still have a few (maybe only one?) header page in man3: sysexits(3).

Don't worry about that one, it is utterly unimportant, and almost
nobody uses it.

> - Section 0 becomes desert, and maybe someone can give it a new use in 
> the future, if a new section is ever need.

As argued above, it might be best to not repurpose man/man0.

Yours,
  Ingo

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

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1062 bytes --]

On 7/29/22 15:22, Ingo Schwarze wrote:
>> 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.

Yeah, I do want to have system cleanliness, especially to help 
programmers organizing their file hierarchy know where they should put 
things.

So, let it be </usr/local/share/doc/pkgname/man/man*>.

I'll have a look at the POSIX man pages and see if there's something I 
can do there.

Thanks,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]