Re: documentation x executable code
On Thu, Jan 06, 2005 at 05:31:31AM -0500, Glenn Maynard wrote:
> On Thu, Jan 06, 2005 at 10:56:57AM +0100, Peter Vandenabeele wrote:
> > 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).
>
> Of course, non-free documentation can and does go in non-free. I'm
> not quite sure what your position is (above you seem to say invariant
> text is acceptable, here you seem to say that it isn't).
My position is as follows:
Trivially, every author has the right to license his own writing as
he wishes, including the use of invariant sections, but that is not
the question ...
If I get it right, the practical question at hand is:
"Should we allow / do we need invariant sections (beyond
meta-data such as licenses or legally required snips of
text) in documentation that goes in "main" ?"
Do we need it ?
===============
For technical documentation, I don't see an immediate need to have
invariant sections in main. This may mean that we are limiting the subject
matter of the documentation to documenting the program and not extending
it to describing or importing elements held by _external_ bodies:
* "political/philosophical" views held by people
* externally defined standards held by standardisation bodies
I consider "people" and "standardisation bodies" as "external bodies"
in this context.
These views and standards are valuable in itself, and it might be useful
to have such invariant elements (political statements and copies of selected
RFC and other standards) as part of another section of Debian (non-free,
contrib, "external" (?), ...).
Advantages/disadvantages
========================
If we say "no" then I see these disadvantages:
* some authors will not want to contribute documentation because they
cannot put invariant blocks into that documentation, or they just
don't like publishing under a license that does not allow that.
* we may have to remove some documentation that is currently in main
because it contains invariant parts (beyond meta-data ...).
If we say "yes" then I see these disadvantages:
* we get stuck forever with invariant parts of text in main. This means
that we will drag along these parts to the end of times and don't have
a legal means to take that out, except by removing the entire document
and rewriting it from scratch (the cost of which is growing as more
and more is added to the document).
The idea that was raised to writing a diff to such invariant section to
me seems quite off-topic for technical documentation. Documentation tries
to accurately describe the workings and use of a program, it is not a
discussion forum. So, I don't consider that an adequate answer to the
remark that even an invariant section can be modified in that way.
* when the political arena changes, invariant descriptions of this
political views can become very disturbing. Same for changing
standards actually. You would need to drag along an old version of
a standard forever (creating ballast and confusion) ?
* we will demotivate authors that do not agree with the political views
in the invariant sections, or that just don't want to contribute to
documentation with invariant sections.
Current conclusion:
===================
When looking at the minimal requirements for the documentation and the
disadvantages of these 2 alternatives, my feeling is that in the long
run, we are better of with _not_ allowing invariant sections in
documentation in "main". By that, we may limit the scope of such
documentation in main to the design and functionality of the actual
program. On the short term, this may be somewhat painfull since some
existing documentation would be moved from main to {non-free|contrib}.
One element that is not clear to me is what to do with documentation
under GFDL, that _allows_ invariant sections, but does not _have_ any
at this time ?
HTH,
Peter
Reply to: