Documentation vs. Software (Re: Savannah rejects a project because it uses GPL)
Bernhard R. Link
brlink at debian.org
Thu Feb 16 11:47:43 UTC 2006
* Alfred M. Szmidt <ams at gnu.org> [060215 20:41]:
> > Now variable names we better forget and look at comments, they are
> > clearly documentation in every sense I can think of.
>
> I disagree strongly with this.
> [...]
> The main difference between comments and documentation is really to
> whom they are directed. Comments are directed for the person who is
> editing the actual code, and documentation is for the person wishing
> to learn about it.
Those distrinctions are a bit fuzzy. Especially as many manuals also
include hacking-howtos, or information about the internal data
structures and workflows. (And with free software libraries, users
are even on the same language level, so things get even more fuzzy).
> > [...] parameters people may need there. So do I have to rewrite that
> > comment under a free license?
>
> Since a comment isn't documentation, no. :-)
Ways there may vary, but good we at least agree that those have to be
free.
>
> But software is not only the source code with its comments, it need
> more things to work (even though one may say those things are not
> part of the software, as it is no program and thus not software by
> some definitions): one needs labels for some ui elements, catalogs
> with translations of those, if it is a gui also icons, contents of
> help- tags popping up, perhaps even some animations showing what
> the program does. Those form a integral part of the program, and
> being able to change the program logics but not those ui elements
> is annoying, as if forcing to separate them, as some variant may
> want to embed the icons or help texts within the source. Thus those
> things should clearly have all the freedoms attached to them the
> program code has.
>
> I don't know if it is that clear. I'd be ok if a recording of a song
> was verbatim only in a program.
Well, the need for freedoms for program source code is not clear either.
Many people distpute that. Having to throw away some sound effects for
some embedded device, when it would still fit with some lossy
compression in there is not what I call freedom. (Or to strech or
remix some effects to fit to new animations or a different sequence of
actions in a program). And even some background music may need some
serious filtering (assume it causes some vibrancy, but changing the
general sound output would make other things sound bad), or adaption
or remixing (when it was somehow fitting to the actions or other
soundeffects the program mixed in and is no longer). All possible
(though for me as music-hater a bit unlikely) situations, I'd not
feel very free in.
> I wouldn't call troff/latex files for `program source. They all spit
> out a static file, one could compare it to a file with values in it,
> that you give to a program, which then spits out a fractal image. Is
> the file with the values, just numbers, source code? Or even a
> program? Of course not. A LaTeX/groff file is more akin to a very
> long parameter list (this is stretching it a bit, but that is what it
> kinda is)
A program is also some kind of parameter list. I'm always suprised to
see how complex interfaces are possible with some Xresources and some
generic X program. Of course many such documents contain not much code,
but they still can and often enough do.
What about the following piece of a manpage I once wrote, is it still
only parameters?
.de command
. ds command at tmp \fB\\$1\fP
. nr command at space 1
. shift
. while \\n[.$] \{\
. ie '\\$1'[' \{\
. if ( \\n[command at space] == 1 ) .as command at tmp \& \&
. as command at tmp [
. nr command at space 0
. \}
. el .ie '\\$1']' \{\
. as command at tmp ]
. nr command at space 1
. \}
. el .ie '\\$1'|' \{\
. as command at tmp |
. nr command at space 0
. \}
. el .ie '\\$1'(' \{\
. as command at tmp \& (\fB
. nr command at space 0
. shift
. while !'\\$1')' \{\
. ie '\\$1'|' .as command at tmp \fP|\fB\h'-1'
. el \{\
. if ( \\n[command at space] == 1 ) .as command at tmp \& \&
. as command at tmp \\$1
. nr command at space 1
. \}
. shift
. \}
. shift
. as command at tmp \fP)
. nr command at space 0
. \}
. el \{\
. if ( \\n[command at space] == 1 ) .as command at tmp \& \&
. as command at tmp \fI\\$1\fR
. nr command at space 1
. \}
. shift
. \}
\&\\*[command at tmp]
..
> So there is documentation within programs, and there are programs
> within documentation, and many things hard to distinguish. And many
> things shifting between those. Take a documentation of some
> interface, add some machine parsable tags to generate headers file
> from it, which freedoms do you need?
>
> Use, modify, copy. All of which the licenses from the FSF allow.
The free software licenses do. The FDL does not allow modification in
reasonable ways. (plus has some glitches with copying). I hope that
the FDL is unsuitable for code has not to be discussed.
> So there are many reasons to not make a distinguish between all
> those bits contained in an OS by some undefinable criterias
> wheather they cause the creation of something the CPU interprets
> (machine code) or to be interpreted by something interpreted by the
> CPU (scripts) one the one side, and things interpreted by something
> interpreted by the CPU (images, texts, ...).
>
> This is the eniterly wrong way to look at it. This message is just a
> stream of bits that get interpeted in one way or another. Does this
> mean that you should have any right to modify what I have written into
> saying something that I have not? Ofcourse not.
If you make me depend on this message, I want those rights. People
differ on what needs to be free, and I can accept different opinions.
But if functional works are restricted, that might be legal, but I'll
still call it immoral.
> Yet, all the `bits' I
> used can be understood by an interpeter if I reorder them enough.
> Does this mean that what I have written is a program? No.
Thus far, it's true.
> Does this mean that other rights apply? Obviously.
That is a reasoning I cannot uphold. Your message may not need the
freedom as much as some technical stuff (though more freedom is still good),
but that has almost nothing to do weather it is a program or not.
The criteria is that there is no need to mix it with something that is
mixed with something that might be mixed with code. Your bits are by
that license unsuitable for programs, thus they are unsuitable for
documention (be it programs, software, non of those or whatever) shiped
together with things dedicated to run a computer.
A (for me simple) criterion to decise what definitly needs those freedom
is simple: If it is sensible to include it in an OS, it definitely needs
those rights attached. (Either it is unneeded cruft that does not belong
there anyway, or it has the possiblity to limit me in an immoral way).
> You are (correct me if I am wrong) basing your argument that if one
> cannot make clear distinction between data and data, then it all
> should be treated the same way. This really makes no sense... It is
> trivial to clearly see the difference between documentation, a program
> and a poem.
Sorry, this is neither trivial, nor easy. And I bluntly belief it is not
possible at all.
> > Although many people today believe the documentation is not part of
> > the software.
>
> If you would have written `part of the program distribution image',
> then I'd agree. But since I think that documentation is clearly not
> software, I cannot agree.
So you believe there are only few people believing like you that
documentation can never be software? ;->
> I'd like to hear the definiton of `free' here. Since we are
> discussing the GFDL, I should note that the GFDL doesn't prohibit how
> you operate your computer. Neither does a copy of the GNU Manifesto
> which cannot be modifed.
The GFDL does not prohibit me to operate my computer. But stuff only
licensed under the GFDL and no free software license prohibit me to
help others to operate their computer.
Bernhard R. Link
More information about the Discussion
mailing list