| 1 |
On Wed, 17 Jul 2019 15:25:10 +0200 |
| 2 |
Michał Górny <mgorny@g.o> wrote: |
| 3 |
|
| 4 |
> What are your comments? |
| 5 |
|
| 6 |
I think there's a situation not covered by this prose which is in a bit |
| 7 |
of a grey area as per the intentions behind it, (but I would argue is |
| 8 |
otherwise fine). |
| 9 |
|
| 10 |
Some systems ship multiple types of documentation, and some, simply |
| 11 |
having the package installed means the documentation is available as |
| 12 |
the documentation is part of the installed sources. |
| 13 |
|
| 14 |
In the perl ecosystem, if one wants to read documentation for the |
| 15 |
installed module "Foo", one only needs to do `perldoc Foo`. |
| 16 |
|
| 17 |
The perl *installer* toolchain however *also* generates manpages with |
| 18 |
the extension ".3pm", which we currently *universally* strip, because |
| 19 |
they're surplus to requirements, and most users don't expect to use |
| 20 |
`man` to read their perl module documentation. |
| 21 |
|
| 22 |
( Perldoc incidentally converts POD to groff on the fly and so its |
| 23 |
pretty much identical ) |
| 24 |
|
| 25 |
We have exemptions for shipping man-pages for executables, as they |
| 26 |
don't get the '.3pm' extension, and they make sense, because then, "I |
| 27 |
have /usr/bin/foo, man foo will tell me about it" as an assumption |
| 28 |
works fine. |
| 29 |
|
| 30 |
I don't think any of this is "a problem" as such for us, just |
| 31 |
suspecting there are other similar cases out there not covered by the |
| 32 |
letter of the policy. |
| 33 |
|
| 34 |
In short, the policy suggests that our blanket removal of man pages |
| 35 |
is harmful, even though it really isn't the case. ( That is, man pages |
| 36 |
for this system are not primary documentation, merely secondary ) |
| 37 |
|
| 38 |
That said, we never plan on gating this removal behind a USE flag, it |
| 39 |
would create an *impossible* amount of work. |
Archives