Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar <alx.manpages@gmail.com>]

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

Hi Ingo,

On 8/24/22 15:22, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Sat, Aug 20, 2022 at 02:40:58PM +0200:
> 
>> Should I keep the static part of the COLOPHON in a REPORTING BUGS section?
> 
> I do not think a manual page should include *any* boilerplate text.
> Text that is the same everywhere is nothing but a distraction
> and a waste of screen real estate.

Agree.  I was hesitant of removing that, which mtk added a long time 
ago, since he claimed an important improvement in awareness of the 
existence of the project.  But I prefer using reportbug(1) and dpkg(1) 
or apt(8) (or equivalent in other distros) to find out how to report bugs.

> 
>> And an even more general question?  Should a manual page state the
>> COPYRIGHT,
> 
> No, it should *not* state any Copyright in the *formatted* text.
> Every file should contain a Copyright and license header at the top
> as a comment though: in a manual page file, .\" stating the Coypright
> and license of that particular manual page, in a program source file,
> /* */ stating the Coypright and license of that particular source file.
> 
> Manual pages are for users who want to use the program or function.
> For merely using it, they do not need to consider *any* Copyright or
> license, at least as long as it is more or less free software.

Greg KH expressed concern about the copyright of the example programs 
some time ago.  He asked what license applies to them, and how should a 
user know, that is, is a user allowed to create derived programs from 
those examples?  Should we state their license in a C comment within the 
example program?  Or just assume that it's a meaningless program and 
that anyone can just copy it indiscriminately because, who cares about 
such a tiny insignificant piece of code?

> 
> Stating the Copyright and license matters for packagers and for
> developers or companies who consider copying parts of files for their
> own projects, and those people are used to looking at source files.
> 
>> AUTHORS,
> 
> Mentioning the main AUTHORS of the original implementation of the program -
> for example, Robert Morris and Lorinda Cherry for bc(1) - and also
> mentioning the main AUTHORS of your current implementation, if it
> was rewritten from scratch, seems most important to me.

I guess in the Linux man-pages that means just don't use it at all. 
Original authors of Linux and GNU are Linux and RMS and that's well 
known.  Current author of any given feature is probably a combination of 
thousands of people.

> 
> Mentioning the AUTHORS of the manual page seems much less relevant
> to me, and it is usually omitted.  Mentioning them is not wrong, though,
> and it some cases, it can be interesting.  For example, some programs
> used to be notorious for not having any manual page whatsoever until
> some Debian developers - who were not even associated with the projects
> maintaining those programs - took pity and wrote a manual page.
> Crediting those brave souls feels fair to me, just as an example.
> 
> If you mention people who wrote the manual but did not contribute
> significantly to the program itself, be explicit that they wrote
> the manual page.
> 
>> and REPORTING BUGS of the software it documents, or
>> of the page itself, or both?
> 
> Any REPORTING BUGS section feels like a bad idea to me - see above
> regarding boilerplate text.
> 
> Besides, if a user is unable to use whatever package manager they
> have, inspect which package the program they are using (and its
> manual page) belong to, and inspect the project website how to
> properly report a bug, would you really expect a useful bug report?
> I certainly wouldn't.  So not having a REPORTING BUGS section
> will discourage only extremely clueless users, whereas having one
> will likely annoy anyone of even minimal competence.
> 
> On top of that, i have often seen bug reporting instructions in
> manual pages that were literally several decades out of date,
> up to and including advertising bang path mail addresses.
> I guess you would not like ending up in that trap, right?

Yup!

So, I'll just drop the COLOPHON section without replacement.

Cheers,

Alex

> 
> Yours,
>    Ingo

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

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