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

Re: Why documentation and programs should not be treated alike

Richard Stallman wrote:
    >The main difference between a program and documentation is that a
    >program does something, while documentation is passive;

By this argument, source code to a program (of the sort which must be compiled to run) is not a program.

That's a pedantic approach to the issue.  I'd say a source program
does do something (after you compile it).

And can therefore, in your opinion be encumbered by unlimited numbers of Invariant Sections (presumably in 'mandatory comments') while remaining free, as long as they can be removed from the actual executable binary, I suppose.

I think that nontechnical invariant comments do not make a program
non-free, but not for those reasons.  The reason is that this is a
packaging requirement that doesn't really restrict you from making the
program substantively behave as you want it to.
Glad you're consistent about that. You've even almost convinced me. :-) However, I think GFDL "Invariant Sections" in manuals are worse than that, and are non-free, because they do really restrict you from making the manual say substantially what you want it to, by requiring it to also say certain other things. Whether I agree with those things or not is irrelevant. (Just as the ls --hangman requirement restricts the way a program can behave.)

Further, the GFDL requirements are *not* written as packaging requirements. They are written as content requirements. Perhaps a thorough rewrite would make this "packaging" interpretation clear and self-evident? It isn't right now.

Anyway, the only packaging requirement specifically accepted by the Debian project is distribution in patch-file format (and that's discouraged). There's no blanket exemption for packaging requirements in Debian, perhaps unlike at the FSF. If you think there should be, amend the Social Contract or the DFSG.

Furthermore, a manual in any markup format (LaTeX, HTML, info, texinfo) is not passive: it does something, namely generating the actual manual in the intended-to-read format (printed, visible on screen in 'info' or 'mozilla', etc.) So manuals in any markup format -- including all the GNU manuals -- are thus akin to programs, and should be judged by those criteria.

That's focusing on form rather than substance.  A manual typically has
source code which contains markup, and that is formally analogous to
the source code of a program.  But in substance the two cases are
completely different.

In the compiled form of a program, you can't see anything important
about it.  If even the comments are missing, you can't understand the
important aspects of the program.  Thus, access to the real source is
essential for a program to be considered free.
You can see what it *does*, just not how it does it. This is very similar to seeing the "compiled" form of a manual, if you care at all about markup.

In the "compiled" form of a manual, as long as there is no DRM to stop
you from reading it, everything that matters is plain to see.  You see
the contents, and you even see the fonts and indentation that were
selected by the markup.  The markup commands, which you don't see, and
any comments in the markup, are far less important than what you do
see.  If you can read the published manual, what you see is everything
that really matters.
Ever seen a Postscript file? It's *all there*, and it's a thoroughly documented format, but it's quite hard to see.

Anyway, this highly subjective judgement as to what "really matters" is a matter on which sensible people can easily disagree, and we do. It's also quite irrelevant to debian-legal, whose job is *not* to determine what "really matters". If you want to argue about that, go to debian-project and propose that the Debian Social Contract be changed.

This is why the GFDL does not require "complete corresponding source
code" for a published manual.  It's easier to change the manual if you
have this, but no disaster if you don't: you just have to write your
own mark-up, which is pretty straightforward.
Says you. I find it less straightforward, personally, than reimplementing many types of programs from scratch! (This is because I'm not very good with markup languages.)

 The requirement for a
transparent copy is so that you don't have to keyboard the whole text
again in order to publish a modified manual.
Why not just require source? I guess you prefer to require that the manual be available as a text file than that it be available in its original source format. I don't really understand or agree with this.

 Even that is not
impossible, but it's a bigger pain than writing mark-up afresh.  (I
think the right thing to do is to distribute the complete
corresponding source code.

    >  For manuals, there is a real danger that the
    >"source" will be in a format that free software cannot read, and thus
The same danger *does* exist for programs, and happens often: a 'free' program written in an interpreted language with no free interpreter or translator is effectively non-free in exactly the same way. Yet there is no similar clause in the GPL.

These are two different kinds of problems, two different issues.  A
program in a language with no free interpreter is nonetheless
transparent if the language is documented and the source is legible.
To be non-transparent, it would have to be obfuscated (and then it
would not be the real source code, so the GPL would reject it).
Conversely, the GFDL does not require the transparent copy to be
processable by a free text formatter.

To write a program in language A can be very different from writing it
in language B; it is not really the same program.
If it does the same thing....

 But whatever text
you want to write, you can write it in any word processor or text
formatter, and it is the same text.  And any word processor can
store the text in a transparent format.
Essentially, you're saying that only the (ASCII-encodable) text matters. *shrug*. In general, I disagree.

The definition of "transparent format", although laudable in concept, is hopelessly vague, and does not seem to me to correspond with its goal. If it was defined as a "Publically specified and freely implementable format with no deliberate obfustication", or something close to that, I think it would not generate complaint. But it's *still* the same issue for program source code and for manuals. Suppose someone starts claiming to have satisfied the GPL by distributing source code in a proprietary, generally unreadable (but not deliberately obfusticated) file format?

>I agree with you that it is a drawback to be unable to intermix the
>program code and the documentation.  But this drawback has nothing to
>do with any of the specific features of the GFDL that have been
>criticized here.  The old simple documentation license that we used
>for most GNU manuals years ago, which nobody here has claimed was
>non-free, would give you the same consequence.  The problem is simply
>due to the fact that the software and the manual have incompatible
But that license was not incompatible with all possible program licenses. The GFDL apparently is.

Reply to: