manual pages for types

manual pages for types

[Alejandro Colomar]

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

Hi Branden,

I guess you remember the discussion a few months ago about pages of the 
form statx-struct(3).  I'm still not convinced by that, because it means 
more typing, and because it breaks with existing practice.  libbsd for 
example just puts timespec(3) in the global 3 section, with no -struct. 
  Also, some other UNIX systems don't put -struct, but move the pages to 
3TYPE, a subsection of 3.  I think I like that way most, and that also 
fixes the concerns that Michael had about shadowing other more important 
pages, because we can just tell man-db to specify that 3TYPE should be 
one of the last things to check.  What do you think about it?

I think I'm going to move all type pages to 3TYPE.  Also, I don't know 
if I should use a separate directory for that or use man3 and just 
change the extension.  What would you do?  I see that debian just puts 
everything in man? and then only changes the file extension, but there 
are other systems that also change dirs, right?  What should we do upstream?

Cheers,

Alex

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

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

Re: manual pages for types

[G. Branden Robinson]

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

Hi Alex,

At 2022-06-09T10:57:07+0200, Alejandro Colomar wrote:
> I guess you remember the discussion a few months ago about pages of
> the form statx-struct(3).

I do!

> I'm still not convinced by that, because it means more typing, and
> because it breaks with existing practice.  libbsd for example just
> puts timespec(3) in the global 3 section, with no -struct.  Also, some
> other UNIX systems don't put -struct, but move the pages to 3TYPE, a
> subsection of 3.  I think I like that way most, and that also fixes
> the concerns that Michael had about shadowing other more important
> pages, because we can just tell man-db to specify that 3TYPE should be
> one of the last things to check.  What do you think about it?

I think we're bumping into (1) inherent limitations of manual
sectioning; (2) the growing diversity of implementation languages used
in *nix development; and (3) long-standing practices of incomplete
library documentation.

Points (1) and (2) are coupled.  A Perl programmer often doesn't need to
see manual pages about C libraries, so the practices of (A) prefixing
Perl-related man pages with a "perl" prefix in their names and (B)
putting those man pages in a bespoke section called "3perl" have arisen.

Neither is a wonderful solution because, as you note, they can require
more typing.  I therefore have some mild reservations about a different,
new section suffix called "type".  C isn't the only language that has
types.  So I think this practice pushes a problem to the future, where
addressing it via the same means will become _more_ cumbersome.  Imagine
a future where we have section suffixes "perltypes" and "pythontypes".

These problems aren't as bad as they could be because factor (3) rides
to the rescue.  Faced with a difficulty in placing documentation
sensibly, fast-moving developers make the decision either to not write
documentation in manual page format, or not to write it at all.

In a fantasy world, albeit one where I'm curiously confined to the C
language, I would document the data types and global non-function
symbols exposed by a library interface in a man page named for its
header file.  I would also include there a list of functions exposed by
the library, possibly with some synoptic information.

stdio(3) and ncurses(3) are pretty good examples of how to do this,
though in my opinion neither of them does enough to help the programmer
organize the large number of provided functions in their brain.
(ncurses has categorical pages, but unfortunately doesn't make them
visible until you visit them, and its API, largely for historical
reasons, has multiple orthogonal axes--sometimes you need a "w" prefix
for window addressing, and sometimes you need a "w" infix or suffix to
indicate the use of a wide character type in the argument list.)

Nevertheless, I don't think moving things to "3type" is a choice that it
will be painful to unwind later (should the need arise) in terms of user
experience.  Most people won't want to mess with typing "[-s] 3type"
before the page name they want, so they won't.  They therefore won't
develop a habit they have to be trained out of later.  Where "3type" can
do the most good is probably in the manual section search order.

So even if it's not an optimal solution, it can still be a good idea.
I'd judge it like this: does the change bring order to chaos by
improving topical coverage and/or discoverability?  Does it impose
technical debt?

> I think I'm going to move all type pages to 3TYPE.  Also, I don't know
> if I should use a separate directory for that or use man3 and just
> change the extension.  What would you do?  I see that debian just puts
> everything in man? and then only changes the file extension, but there
> are other systems that also change dirs, right?  What should we do
> upstream?

I would ask that you not put "type" in full capitals.  ;-)

In the abstract there is no problem with having all of these pages in
man3 upstream, if you aim to reflect the section suffixes in the file
names.  There will be no name collisions.

Historically there have been problems with file system performance when
directories accumulate a lot of entries.  As far as I know this isn't a
problem on any modern, commonly-used file system.  Further, my Git
checkout says that the Linux man-pages project has only about 1,700
files in the man3 directory.  The performance problems I've heard about
arise when the number of dirents is greater by an order of magnitude or
more.  No matter how diligent you are as a technical writer, it's going
to be hard to swell the man-pages corpus to that degree.  :)

If distributors need to change the arrangement to suit their performance
requirements, they are better placed to do so.  It is a choice that has
most of its impact at run time anyway, and distribution packaging
systems are well practiced at rearranging their upstreams' "make
install" results.

For development and maintenance of the man pages themselves, I think
retaining the existing directory structure has the virtues of keeping
things simpler and not confusing new contributors with an organizational
distinction that doesn't communicate any new information.

These are just my opinions--I'm not an oracle.

Regards,
Branden

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

Re: manual pages for types

[Alejandro Colomar]

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

Hi Branden,

On 6/18/22 18:39, G. Branden Robinson wrote:

> I think we're bumping into (1) inherent limitations of manual
> sectioning; (2) the growing diversity of implementation languages used
> in *nix development; and (3) long-standing practices of incomplete
> library documentation.
> 
> Points (1) and (2) are coupled.  A Perl programmer often doesn't need to
> see manual pages about C libraries, so the practices of (A) prefixing
> Perl-related man pages with a "perl" prefix in their names and (B)
> putting those man pages in a bespoke section called "3perl" have arisen.
> 
> Neither is a wonderful solution because, as you note, they can require
> more typing.  I therefore have some mild reservations about a different,
> new section suffix called "type".  C isn't the only language that has
> types.  So I think this practice pushes a problem to the future, where
> addressing it via the same means will become _more_ cumbersome.  Imagine
> a future where we have section suffixes "perltypes" and "pythontypes".
> 
> These problems aren't as bad as they could be because factor (3) rides
> to the rescue.  Faced with a difficulty in placing documentation
> sensibly, fast-moving developers make the decision either to not write
> documentation in manual page format, or not to write it at all.
> 
> In a fantasy world, albeit one where I'm curiously confined to the C
> language,

Oh, what a wonderful fantasy world!  :D

> I would document the data types and global non-function symbols

You were reading my mind, were you?

Not that I plan to do it soon (first come the types, and that may take 
many, many years), but I do have a longstanding wish of documenting all 
symbols.  I'd like to be able to do things such as `man IOV_MAX`.  I 
still don't know how to implement that, but documenting headers in 
section 0 and then adding link pages with the names of the macros 
defined in them is one of the ideas.  I'll be accepting suggestions, if 
you wish to propose them.

> exposed by a library interface in a man page named for its
> header file.  I would also include there a list of functions exposed by
> the library, possibly with some synoptic information.

I have a conflict with that.  I like the idea of having all of the 
functions defined by a header listed (not documented) together, so that 
it may help discover similar functions better suited for a specific job, 
that one might not have known otherwise.

But I don't like the idea of duplicating documentation, including the 
synopsis, because that will mean more maintenance costs.  See that I've 
been cleaning definitions of types in function pages after having them 
documented in type pages:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=cb3366169531510bcc7d445e15df68396291a05d>
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=6c809df77b359bb3a9e06f32547e0aed155408be>

Pages like string(3) work like a SEE ALSO, and we already have SEE ALSO. 
  I've also considered having includes with the prototypes, which could 
be included from various pages, but that's something I'm willing to do, 
because having standalone pages is also much easier to handle.

> 
> stdio(3) and ncurses(3) are pretty good examples of how to do this,
> though in my opinion neither of them does enough to help the programmer
> organize the large number of provided functions in their brain.
> (ncurses has categorical pages, but unfortunately doesn't make them
> visible until you visit them, and its API, largely for historical
> reasons, has multiple orthogonal axes--sometimes you need a "w" prefix
> for window addressing, and sometimes you need a "w" infix or suffix to
> indicate the use of a wide character type in the argument list.)

Basically the same problems as SEE ALSO.  You don't know what they're 
about, until it's too late :)

> 
> Nevertheless, I don't think moving things to "3type" is a choice that it
> will be painful to unwind later (should the need arise) in terms of user
> experience.  Most people won't want to mess with typing "[-s] 3type"
> before the page name they want, so they won't.  They therefore won't
> develop a habit they have to be trained out of later.  Where "3type" can
> do the most good is probably in the manual section search order.
> 
> So even if it's not an optimal solution, it can still be a good idea.
> I'd judge it like this: does the change bring order to chaos by
> improving topical coverage and/or discoverability?  Does it impose
> technical debt?

I've already done it:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=178eaf37e2e971cae88bd4d3f124ede0afbb1015>

I think it was a good move.

> 
> I would ask that you not put "type" in full capitals.  ;-)

Didn't.

> 
> In the abstract there is no problem with having all of these pages in
> man3 upstream, if you aim to reflect the section suffixes in the file
> names.  There will be no name collisions.

I was thinking more about having them better organized.  I prefer having 
many dirs with few files, rather than unreadable ls(1) output.

It's always easier to merge dirs rather than split dirs, although in 
this case, it's pretty much the same difficulty (low).

> 
> Historically there have been problems with file system performance when
> directories accumulate a lot of entries.  As far as I know this isn't a
> problem on any modern, commonly-used file system.  Further, my Git
> checkout says that the Linux man-pages project has only about 1,700
> files in the man3 directory.  The performance problems I've heard about
> arise when the number of dirents is greater by an order of magnitude or
> more.  No matter how diligent you are as a technical writer, it's going
> to be hard to swell the man-pages corpus to that degree.  :)
> 
> If distributors need to change the arrangement to suit their performance
> requirements, they are better placed to do so.  It is a choice that has
> most of its impact at run time anyway, and distribution packaging
> systems are well practiced at rearranging their upstreams' "make
> install" results.

Actually, I've been working hard on providing a very flexible Makefile 
that should work unmodified for as many distributors as possible. 
That's why I considered that having the Makefile install into separate 
dirs, and let the distributor merge them later, could be a good idea.

But since the smallest diff for the Makefile was to use a single one, I 
did that for now.

> 
> For development and maintenance of the man pages themselves, I think
> retaining the existing directory structure has the virtues of keeping
> things simpler and not confusing new contributors with an organizational
> distinction that doesn't communicate any new information.

I think it is easier with one dir, but for another reason:  less 
typing/better autocomplete.

> 
> These are just my opinions--I'm not an oracle.
> 

I tend to like your opinions.  I'll keep asking your Oracle ;).

Cheers,

Alex

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

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