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

From: Ingo Schwarze <schwarze@usta.de>
To: Alejandro Colomar <alx.manpages@gmail.com>
Cc: g.branden.robinson@gmail.com, Jakub Wilk <jwilk@jwilk.net>,
	Michael Kerrisk <mtk.manpages@gmail.com>,
	linux-man@vger.kernel.org
Subject: Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)
Date: Wed, 24 Aug 2022 15:22:24 +0200	[thread overview]
Message-ID: <YwYmENPAprVbooAP@asta-kit.de> (raw)
In-Reply-To: <a35cf5e8-ad2c-92bd-ca78-7be3dec3d62e@gmail.com>

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.

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

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.

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?

Yours,
  Ingo