Hi Branden, G. Branden Robinson wrote on Sat, Nov 04, 2017 at 10:33:10AM -0400:
> Anyway, for the time being I propose we choose one of two courses of > action: > > (A) Make man pages' copyright and permission notices visible in the roff > source file only, and put them in plain ASCII in comments. Stop > defining macros for them. Author information, if present, can be > directly inlined into the man page, not stuffed into a private macro > to be popped later. FWIW, i'm strongly in favour of that option. When giving talks about how to write good documentation, i regularly provide putting Copyright notices into the rendered form shown to the user as an example of what must *not* be done. The goal of documentation is to be useful for the reader, for the person trying to use the software, and to be concise. Using the software almost never requires reading the license, and even in the rare exceptional case where it might (like for a web interface software that redistributes generated files containing parts of its own code), it does not need to be in each and every manual page. I consider Copyright notices in the user interface, that is, in manual pages, and even a bit worse in stdout or stderr of the program, outright rude and disrespectful of the user: "Here, i know for sure you won't need this more than once, and probably not at all, but i'm still making you look at it each and every time." Copyright notices are relevant for people who want to change and redistribute te code and to packagers, so they belong into source files, into a prominent files like COPYING or LICENSE in the source tree, and into the proper section of the web site for the program. A pointer belongs into INSTALL such that people installing the software are made aware of the license *once* hwne installing, and such that packages can easily copy the information into the packaging database (in whatever form is appropriate). I have always found it unfortunate that groff, which is used a lot as a documentation formatter and does have some well-merited authority in that area, is setting this horrible example that people might follow. Note that i'm not saying that authors should be disrespected and their rights hidden; i'm an author myself. Credit where credit is due, but not in a place that each and every user is continuously forced to look at. See, i'm a user, too, and i want concise documentation and concise program output. In stdout and stderr, every unnecessary word is a very serious nuisance, and two additional lines are hellish, they make stuff scroll off the screen and bury the output i'm looking for in heaps of crap. > (B) Maintain the (very recent) status quo, with copyright notices marked > up and permission notices flowed as groff recommends. > > Again, my preference is for (A). Please do. Also, yes, a manual page should not contain any user-defined strings or macros, not for Copyright, not for AUTHORS, and not for anything else. KISS, maximum maintainability for programmers who do *not* spcialize in roff(7) syntax but, say, in C or some other language, and maximum portability are good goals. > Whatever the consensus is, I'm happy to make the changes to align > the 68 man pages in the groff source tree with it. Thanks for volunteering to do that work. Don't worry about the exact format. According to international law, Copyright notices are optional, and worrying about national law is a rabbit hole that leads nowhere, there are just too many different legislations. If they are given, which is indeed to be strongly recommended to help people reading the file, all that matters is that the word "Copyright" appears (in english), that the name of the author(s) and all years of creation appear, that they contain no lies and nothing that could be misunderstood - more as a matter of common sense than for legal reasons. Thanks, Ingo
