groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Copyright notices in groff's man pages


From: Ingo Schwarze
Subject: Re: [Groff] Copyright notices in groff's man pages
Date: Sat, 4 Nov 2017 17:13:40 +0100
User-agent: Mutt/1.8.0 (2017-02-23)

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]