#1022844 mandirs: man subsection directories are needed for mandoc(1)

Package:
manpages
Source:
manpages
Submitter:
Alejandro Colomar
Date:
2023-01-06 18:45:06 UTC
Severity:
normal
#1022844#5
Date:
2022-10-26 19:15:01 UTC
From:
To:
Hi Marcos,

I've seen you removed the manual page subsections present upstream.
We had a discussion (actually, a few of them) about the organization of
subsections in the upstream mailing list:

<https://lore.kernel.org/linux-man/761bb12f-31e0-369d-8315-d2e1545505c7@gmail.com/T/#u>
<https://lore.kernel.org/linux-man/b7ecc62d-3b46-c6be-d102-3ede7b81b4ed@gmail.com/T/#m7179683eed367e312b06686f73ba4f3f9957a0b2>

I'll quote what Ingo (mandoc(1) maintainer) said:

I'd like to suggest using the same directories as upstream.

I understand Debian tries to follow the FHS as closely as possible, and
it only recognizes man[1-8]/ as man sections, but I think it doesn't
harm to use man*/ directories, considering that other software will
behave better.

Cheers,

Alex
#1022844#10
Date:
2023-01-06 18:35:22 UTC
From:
To:
Hello Alejandro,

Debian policy is clear on this point: manual pages should be assigned
to man[1..9]/ dirs [1]. Lintian also issues error tags when this
behavior is not observed [2].

The desired section expressed through the file extension and the .TH
field is not modified. All .so links are corrected to point to the
corresponding man page. 

From dh_installman(1) manual page:

" ...you tell dh_installman what man pages go in your packages, and it
figures out where to install them based on the section field in their
.TH or .Dt line. If you have a properly formatted .TH or .Dt line, your
man page will be installed into the right directory, with the right
name (this includes proper handling of pages with a subsection, like
3perl, which are placed in man3, and given an extension of .3perl). If
your .TH or .Dt line is incorrect or missing, the program may guess
wrong based on the file extension."

What is the precise drawback of this solution?

Greetings,
Marcos

[1] https://www.debian.org/doc/debian-policy/ch-docs.html#manual-pages
[2] https://lintian.debian.org/tags/odd-place-for-manual-page
#1022844#15
Date:
2023-01-06 18:40:51 UTC
From:
To:
Hello Marcos,

There are two (not huge drawbacks, but they exist):

-  mandoc(1) (and possibly other software) understands that if a page is in
directory manX, it is in section X, so it will for example appear in searches of
pages in that section.

-  3 is for functions and 3const is for constants, so having them separate makes
it easier to list all functions and all constants in a system (or at least those
that are documented in manual pages.

Cheers,

Alex