Accepting GNU Free Documentation Licensed content

[Ben Coyote Woodard]

On 8/21/19 3:50 AM, Mark Wielaard wrote:
> Hi Ben,
>
> On Tue, 2019-08-20 at 12:18 -0700, Ben Coyote Woodard wrote:
>> What do you guys think of accepting derived works based upon GNU Free
>> Documentation Licensed content? https://www.gnu.org/licenses/fdl-1.3.en.html
>>
>> As far as I can tell, allowing a project like elfutils the freedom to
>> fork and derive specialized content is what this license was intended to
>> do and elfutils use of the various GPL licenses expresses an overall
>> intention to not restrict user's freedom. The GFDL is in line with that
>> intention.
> As long as it has "with no Invariant Sections, with no Front-Cover
> Texts, and with no Back-Cover Texts" I am fine with GFDL. Otherwise it
> is a pain to share and an argument could be made (as e.g. Debian does)
> that it isn't really a Free license.
Yeah the man pages simply reference the main GDFL.
>
> The DWARF Standard Document is also published under the GFDL 1.3, so we
> could then also freely use some standard texts.
>
> That said, I actually like the documentation being under the same
> license as the code (GPL) since that makes it easy to share
> documentation and code. e.g. We could generate an initial set of man
> pages for the tools with https://www.gnu.org/software/help2man/ and
> then copy/paste changes between the man pages and the source code.
> Which isn't possible if we use different incompatible licenses between
> documentation and code.
>
> The counter argument of course is that a manual describes something
> different (better) than the simple code docs/help does. So sharing code
> and documentation might not happen all that much in the first place.

I find this argument much more convincing.  There are formatting issues 
such as the length of the text and the supported man page sections which 
are not part of the  usage text. I therefore think that the man pages 
should be independent from the usage text.

>
>> e.g. there is readelf and eu-readelf is designed to take the same
>> options and work the same way but there may be a couple of differences.
>> Why don't we just fork the readelf man page and describe any differences
>> that there may be.
> How are those manuals generated?

They are using perl's pod format and POD::MAN, -- <sigh> yet another 
markup format. I know that you ultimately would prefer sphinx. Given the 
excessive number of markup formats, I'm disinclined to use any of them. 
They are all johnny come latelys and hopefully most of them will die off 
and be merged into each other. Using any particular one just perpetuates 
its existence by increasing its installed base. *roff on the other hand 
has been around for generations. It will only die when man is extended 
to directly read some more modern format. (Why hasn't someone done this 
yet? ...)

> Do you want to keep sharing/updating
> them from binutils? Or just use them as initial templates?
My thought was to create a handful of stubs which just point to 
analogous binutils pages and then compare the binutils pages to what the 
elfutils actually do. If I find any differences, then I was planning on 
forking the binutils version of the man page with just the minimal 
modifications so that it has an obvious fork point, which is diff-able 
and evolutionary history. This would allow us to effectively cherry pick 
changes when it suits us.
>
> It would be good to see which differences there are in options. We try
> to not be deliberately incompatible, but I believe there are some
> (accidental) incompatibilities anyway.

Right. I think carefully going through the options and the man page 
should help surface these. I think not having documentation kind of put 
you in a straight jacket. Since anything beyond --help was implicitly 
assumed to be documented by binutils's man pages, you were required to 
stay in sync. Having your own documentation will allow Elfutils to kick 
off the dusty shackles of binutils and intelligently move forward to 
support a broader range of use cases in this modern era.


>
> Cheers,
>
> Mark