Re: What's the plan for the user guide?

[Shaun McCance <shaunm gnome org>]

On Wed, 2006-02-08 at 22:14 +0000, Simos Xenitellis wrote:
> O/H Shaun McCance έγραψε:
> > In fact, there's absolutely no way a DocBook document can
> > guarantee its compliance with the FDL, given how much leeway
> > processing applications have with DocBook.  For instance:
> >
> >     Include, immediately after the copyright notices, a
> >     license notice giving the public permission to use the
> >     Modified Version under the terms of this License, in
> >     the form shown in the Addendum below.
> >
> > Authors can put this information in the articleinfo or
> > bookinfo element in their DocBook, but they can't ensure
> > that it will be rendered "immediately after the copyright
> > notices".
> This is <legalnotice></legalnotice> and it comes after the copyright statement.
> 
> The TLDP (www.tldp.org) is using heavily the GFDL and they have a
> Guide to Authors with template documents, at
> http://www.tldp.org/LDP/LDP-Author-Guide/

My point is that there is no way a DocBook-using author can
guarantee that the legalnotice will be placed "immediately
after the copyright notices", as required by the FDL.  If I
were so inclined, I could rearrange the elements in the info
page in my stylesheets right now, and it wouldn't make them
any less DocBook-compliant.

The more general gripe along these lines is that the FDL
makes requirements regarding presentation.  With semantic
source formats like DocBook, authors are not in a position
to specify or guarantee presentation.

> Just to make sure, we (well, you :-) are the owners of the docs, so we
> are not talking about being sued by someone.

I own very few of the docs.  I'm the default maintainer
of any document whose author disappears, but that doesn't
mean I own the copyright on those documents.  If we had
a single copyright holder, none of this would matter.

> >>> What we need is a simple copyleft license that does not
> >>> impose undue restrictions on modification.  Basically,
> >>> anything beyond maintaining visible contributor credits
> >>> is just too much.  It would also be nice to have built-in
> >>> provisions for allowing reuse of code samples in contexts
> >>> outside the documentation.
> >> Is there a consensus for such a license to be GFDL compatible?
> >
> > In what way?  Let's postulate the GDL, the Gnome Documentation
> > License, just so we have a named something to talk about.  There
> > is no way we can allow FDL content inside of the GDL, because
> > the FDL simply doesn't allow it.  We could, certainly, allow
> > GDL content to be used inside FDL, much like the LGPL allows
> > you to "escalate" the license to GPL.
> >
> > There's no consensus on anything right now.  But if people feel
> > such a clause is important, then we can incorporate it.  This
> > isn't a unilateral dictate from the Fearless Leader.  It's all
> > about the community.
> I feel that since there are no maniac previous contributors of GNOME
> documentation
> out in the wild, we can focus now on writing the documents. I feel we
> are not ready
> to jump to a new license.
> The format that looks more suitable for the type of documentation for
> GNOME is DITA, which needs some time to mature.

I don't think DITA is a good solution.  It has one thing
in common with my plans, which is that it eschews the whole
linear document approach.  But it's trying to be everything
for everybody, making it even more complex than DocBook.

What we need is a simple semantic markup that addresses
our particular needs directly, rather than an incredibly
difficult format that I'll spend years trying and failing
to implement correctly.

--
Shaun