documentation

[Matthew C. Weigel]

On Wed, 29 Aug 2001, SamBC wrote:

> > It started life as the Debian Free Software Guidelines. It was
> > never put through any consideration for covering the slightly
> > different world of documentation.  It is ill-considered to tack on
> > new duties.
>
> Point me at the bits which make a problem, aside from cases of obvious
> intelligent reinterpretation...

How about the title?  I'm not saying that the general principles don't
apply to free documentation - I'm saying that the exact set of
trade-offs, made with an eye towards bringing the principles into the
real world, were developed specifically for the 'real world' of
software.

Therefore, the principles behind the FSG and OSD still apply, but the
FSG and OSD themselves do not.  You can certainly hold documentation to
them, but that was not their intent.

For instance, would 4. Integrity of The Author's Source Code (either
one) mean that you could distribute modified PDFs of a patch-only
document (since PDF is definitely not the "form of choice" for editing
documents, and should probably qualify for being a binary), but not
TeX?  What about HTML - should it be considered a "binary" form that
you can distribute modified, or a "source" form that you can restrict
to patches-only?

> > > Good point (for most readers) - but I'm sure there are some
> > > unfriendly peeps out there.
> >
> > Errr... peeps?  Surely marshmallow cremes aren't too unfriendly...
>
> peeps = people. An irritating shortening I picked up somewhere a
> while back.

Then I guess I don't understand what you're saying.

> > *In Windows*?  What about MacOS?
>
> No reason diff shouldn't still work. A lot of gnu stuff has been
> ported, and note mingw and cygwin, if people really want. But here
> we're debating technicalities, as we agree in principle that patches
> aren't good for docs.

Yes.  If we started with the assumption that "printout" was the final
output, akin to binary executables, they would be fine - you'd download
the source in, for example, TeX, apply the patches included with your
version of the software, and print it out.  But, most documentation is
now viewed online, in 'raw' formats like HTML or nroff.  What's more,
you have - between HTML, man2html.cgi, and PDF plugins - the ability
and motivation to distribute modified documents willy nilly.

> Presumably changed since I last looked. It was a while ago, but they said
> 'click here for license information for all LDP docs' or something
> equivalent...

See 5. License Requirements at www.linuxdoc.org/manifesto.html.

> I agree this is pathetic, especially with the standing of W3C
> online... but what can we do?

There's a slim chance someone in the OSI is reading this, or your
responses to it (at least the new webmaster hasn't killfiled me).
Perhaps someone can explain why it *hasn't* been approved?  Shouldn't
it be a priority, so that the much-respected W3C can get a spot on
sourceforge.net?
-- 
 Matthew Weigel
 Research Systems Programmer
 mcweigel at cs.cmu.edu ne weigel at pitt.edu

--
license-discuss archive is at http://crynwr.com/cgi-bin/ezmlm-cgi?3