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
