Re: documentation x executable code
On Thu, Jan 06, 2005 at 08:53:07AM +1100, Craig Sanders wrote:
> On Wed, Jan 05, 2005 at 12:03:49PM +0100, David Weinehall wrote:
> > On Wed, Jan 05, 2005 at 08:05:57PM +1100, Craig Sanders wrote:
> > Because this is *exactly* the situation you get with invariant sections.
> > Sure, you can add another invariant section that fixes all the "bugs" in
> > the original version, but that still leaves the buggy version in the
> > document.
>
> for invariant sections (as defined in the GFDL) in a document, that's good
> enough.
>
> for a document, one person's "bugfix" is another person's "censorship".
>
> the point of invariant sections is that nobody can come along later and censor
> the original author's words or put words in their mouths. whether you agree
> with them or not, you do not have the right to change or delete what they
> said, you only have the right to comment upon it.
>
> this is perfectly OK for documentation because only secondary sections may be
> invariant. the primary content (i.e. the subject matter) can never be
> invariant and may be changed at will, e.g. to reflect changes in the
> associated software. THIS is the important freedom for documentation.
>
> the following extract from the GFDL is why Invariant Sections are a licensing
> triviality:
>
> A "Secondary Section" is a named appendix or a front-matter
> section of the Document that deals exclusively with the
> relationship of the publishers or authors of the Document to the
> Document's overall subject (or to related matters) and contains
> nothing that could fall directly within that overall subject.
> (For example, if the Document is in part a textbook of
> mathematics, a Secondary Section may not explain any mathematics.)
> The relationship could be a matter of historical connection with
> the subject or with related matters, or of legal, commercial,
> philosophical, ethical or political position regarding them.
>
> The "Invariant Sections" are certain Secondary Sections whose
> titles are designated, as being those of Invariant Sections, in
> the notice that says that the Document is released under this
> License.
>
> "a named appendix or a front-matter section of the Document that deals
> *exclusively* with the *relationship* of the publishers or authors of the
> Document to the Document's overall subject" (emphasis mine) -- it does not
> matter in the slightest if these things can not be changed by anyone but the
> original authors. they are not in the least bit important for the task of
> accurately documenting software.
>
> the purpose of an Invariant section is to ensure that the author is correctly
> attributed in the manner that they choose, and that *their work* is presented
> in the philosophical context that they choose.
>
> e.g. it is to stop people from changing text like "Professor Fred Bloggs has
> worked in the field of blahblahblah for 50 years" to "Fred Bloggs is a
> fuckwit", and to stop people from deleting a rant on the ethical superiority
> of free software and replacing it with a diatribe. or vice-versa.
>
> these are perfectly legitimate things for an author to want to remain
> invariant. if someone disagrees with them then they can add a comment
> detailing their disagreement, but they do not have the right to censor the
> author's words or to change what they said.
>
> if you don't like their political or ethical stance and want to delete it
> entirely (or worse, change it), then tough luck - write your OWN damn document
> and then you can do whatever you want with it.
>
> these are fundamental ethical principles - censorship is evil, and you do not
> put words in people's mouths. these thing are just plain wrong, in any
> context.
The way it is presented here, makes perfect sense to me. The author must
have the right to keep certain "background/political/philosophical" parts of
his text (secondary) invariant, while allowing all needed updates, additions,
reductions to the "main body" (primary) text. If you don't like the "political"
views of the author, well too bad, then don't use his text. Similar
problem with quoting of RFC and other sources of "imported" _external_
documentation (that should be a copy-exact of their original, otherwise,
what is it worth, a local copy of an RFC that you can't trust for being
a copy-exact ? In that case, you better offer a simple URL pointing to it).
And maybe that is the entire difference:
* in source code of a program, the code _itself_ is the subject matter. The
code itself is all and everything. Since there is no relationship with an
_external_ entity, you don't cause direct damage to an external entity by
changing the code (well, you can break functionality of this code, in
collaboration with something else, but you are not _directly_ hurting some
external code or entity).
* in documentation, you are writing _about_ something _external_. So you
can _directly_ hurt something external by misrepresentation, by e.g.
putting wrong words in some-one's mouth or "censoring" his political,
philosophical views. Or you can cause confusion by distributing a patched
version of an RFC.
For writing about other code (the "primary" content), this problem could
also exist (of hurting the usability of the code by writing incorrect
documentation about it), but at least the _external_ entity is not a
person or a standard, and in practical matter, it is still closely
coupled to the code, so the scope of the damage is limited and easily
correctable.
So, I conclude that the Debian license scheme should cater in some way for
allowing invariant sections as part of the documentation (but not
necessarily in the "main" section if that violates the Social Contract).
Maybe this means putting such documentations that contains invariant
sections in contrib or non-free and explaining to people that such
documentation that contains invariants sections (because they are imported
from external sources (RFC, IEEE, ...) or because the author felt he needed
to make a "political" statement in an invariant section) needs to be
downloaded from a separate package in contrib or non-free (using a
"suggests" dependency on the documentation package that contains
invariant sections).
In such case, I presume many authors of documentation will choose to not
include invariant sections in the technical documentation, so that they
can go with the mainline documentation in main. They will use other forums
for exposing their "political" views.
An interesting consequence of this proposal is that a Copy-Exact of
the GPL License could not longer go into main (as it is essentially
one large invariant section. I quote from GPL:
"Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.")
Peter
Reply to: